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...

Navigation et Focus au clavier/manette

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 navigation entre les éléments de l'interface utilisateur à l'aide du clavier ou de la manette s'effectue en changeant le nœud qui est activement sélectionné. C'est ce qu'on appelle aussi changer le focus de l'interface utilisateur. Chaque nœud Control dans Godot est capable d'avoir le focus. Par défaut, certains nœuds de contrôle ont la capacité de s'emparer automatiquement du focus en réagissant à des actions d'interface utilisateur intégrées telles que ui_up, ui_down, ui_focus_next, etc. Ces actions sont visibles dans les paramètres du projet dans la carte des entrées et peuvent être modifiées.

Avertissement

Comme ces actions sont utilisées pour le focus, elles ne doivent pas être utilisées pour tout code de jeu.

Paramètres des nœuds

En plus de la logique intégrée, vous pouvez définir ce que l'on appelle les voisins du focus pour chaque nœud de contrôle individuel. Cela permet de régler avec précision le chemin que prend le focus de l'interface utilisateur dans l'interface utilisateur de votre projet. Les paramètres des nœuds individuels se trouvent dans le dock inspecteur, dans la catégorie "Focus" de la section "Control".

Les options de voisinage sont utilisées pour définir les nœuds pour la navigation quadridirectionnelle, comme l'utilisation des touches fléchées ou du D-pad d'une manette. Par exemple, le voisin du bas sera utilisé lors de la navigation vers le bas avec la flèche vers le bas ou en appuyant sur le D-pad. Les options "Next" et "Previous" sont utilisées avec le bouton de changement de focus, tel que Tab sur les systèmes d'exploitation de bureau.

Note

Un nœud peut perdre le focus s'il devient caché.

Le réglage de mode définit comment un nœud peut obtenir le focus. All signifie qu'un nœud peut obtenir le focus en cliquant dessus avec la souris, ou en le sélectionnant avec un clavier ou une manette. Click signifie qu'on peut seulement obtenir le focus en cliquant dessus. Enfin, None signifie qu'il ne peut pas obtenir le focus. Les différents nœuds control ont des paramètres par défaut qui diffèrent selon comment ils sont généralement utilisés. Par exemple, les nœuds Label sont définis à "None" par défaut, alors que les boutons sont tous définis à "All".

Assurez-vous de configurer correctement vos scènes pour le focust et la navigation. Si un nœud n'a pas de voisin de focus configuré, le moteur essaiera de deviner automatiquement le prochain control. Cela peut entraîner un comportement involontaire, en particulier dans une interface utilisateur complexe qui n’a pas de flux de navigation vertical ou horizontal bien défini.

Code nécessaire

Pour que la navigation au clavier et à la manette fonctionne correctement, tout nœud doit obtenir le focus via le code lorsque la scène démarre. Sans cela, l’appui sur des boutons ou des touches n’aura aucun effet.

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.