Keyboard/Controller Navigation and Focus
It is a common requirement for a user interface to have full keyboardand controller support for navigation and interaction. There are two mainreasons why this is beneficial for projects: improved accessibility (not everyonecan use mouse or touch controls for interactions), and getting your projectready forconsoles (or just for people who preferto game with a controller on PC).
Navigating between UI elements with keyboard or controller is done bychanging which node is actively selected. This is also called changing UI focus.EveryControl node in Godot is capable of having focus.By default, some control nodes have the ability to automatically grab focusreacting to built-in UI actions such asui_up,ui_down,ui_focus_next, etc.These actions can be seen in the project settings in the input map and can be modified.
Warning
Because these actions are used for focus they should not be used for anygameplay code.
Node settings
In addition to the built-in logic, you can define what is known as focus neighborsfor each individual control node. This allows to finely tune the path the UI focustakes across the user interface of your project. The settings for individualnodes 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, suchas using arrow keys or a D-pad on a controller. For example, the bottom neighborwill be used when navigating down with the down arrow or by pushing down onthe D-pad. The "Next" and "Previous" options are used with the focus shift button,such asTab on desktop operating systems.
Note
A node can lose focus if it becomes hidden.
The mode setting defines how a node can be focused.All means a node canbe focused by clicking on it with the mouse, or selecting it with a keyboardor 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 havedifferent default settings for this based on how they are typically used, forexample,Label nodes are set to "None" by default,whilebuttons are set to "All".
Make sure to properly configure your scenes for focus and navigation. If a node hasno 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'thave well-defined vertical or horizontal navigation flow.
Necessary code
For keyboard and controller navigation to work correctly, any node must be focused onusing code when the scene starts. Without doing this, pressing buttons or keys won'tdo anything. Here is a basic example of setting initial focus with code:
func_ready():$StartButton.grab_focus()
publicoverridevoid_Ready(){GetNode<Button>("StartButton").GrabFocus();}
Now when the scene starts the "Start Button" node will be focused, and the keyboardor a controller can be used to navigate between it and other UI elements.