Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Navigazione e focus tramite tastiera/controller

It is a common requirement for a user interface to have full keyboard and controller support for navigation and interaction. There are two main reasons why this is beneficial for projects: improved accessibility (not everyone can use mouse or touch controls for interactions), and getting your project ready for consoles (or just for people who prefer to game with a controller on PC).

La navigazione tra gli elementi dell'interfaccia utente con la tastiera o con il controller avviene cambiando quale nodo è attivamente selezionato. Questa operazione si può anche dire cambiare il "focus" dell'interfaccia utente. Ogni nodo Control in Godot è capace di avere il focus. Come predefinito, alcuni nodi di controllo hanno la capacità di acquisire automaticamente il focus, reagendo ad azioni integrate dell'interfaccia utente come ui_up, ui_down, ui_focus_next, ecc. Queste azioni sono disponibili nelle impostazioni del progetto nella mappa di input e si possono modificare.

Avvertimento

Poiché queste azioni sono utilizzate per il focus, non si dovrebbero utilizzare in alcun codice di gioco.

Impostazioni dei nodi

In addition to the built-in logic, you can define what is known as focus neighbors for each individual control node. This allows to finely tune the path the UI focus takes across the user interface of your project. The settings for individual nodes can be found in the Inspector dock, under the "Focus" category of the "Control" section.

Neighbor options are used to define nodes for 4-directional navigation, such as using arrow keys or a D-pad on a controller. For example, the bottom neighbor will be used when navigating down with the down arrow or by pushing down on the D-pad. The "Next" and "Previous" options are used with the focus shift button, such as Tab on desktop operating systems.

Nota

A node can lose focus if it becomes hidden.

The mode setting defines how a node can be focused. All means a node can be focused by clicking on it with the mouse, or selecting it with a keyboard or controller. Click means it can only be focused on by clicking on it. Finally, None means it can't be focused at all. Different control nodes have different default settings for this based on how they are typically used, for example, Label nodes are set to "None" by default, while buttons are set to "All".

Make sure to properly configure your scenes for focus and navigation. If a node has no focus neighbor configured, the engine will try to guess the next control automatically. This may result in unintended behavior, especially in a complex user interface that doesn't have well-defined vertical or horizontal navigation flow.

Codice necessario

For keyboard and controller navigation to work correctly, any node must be focused by using code when the scene starts. Without doing this, pressing buttons or keys won't do anything.

You can use the Control.grab_focus() method to focus a control. Here is a basic example of setting initial focus with code:

GDScriptC#

func _ready():
    $StartButton.grab_focus.call_deferred()

Now when the scene starts, the "Start Button" node will be focused, and the keyboard or a controller can be used to navigate between it and other UI elements.