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

Navegação por Teclado/Controle e Foco

É um requisito comum para uma interface de usuário ter suporte completo a teclado e controle para navegação e interação. Há duas razões principais pelas quais isso é benéfico para os projetos: acessibilidade aprimorada (nem todos podem usar controles de mouse ou toque para interações) e preparar seu projeto para consoles (or apenas para pessoas que preferem jogar com um controle no PC).

A navegação entre elementos de UI com teclado ou controle é feita alterando qual nó está ativamente selecionado. Isso também é chamado de alterar o foco da UI. Todo nó Control no Godot é capaz de receber foco. Por padrão, alguns nós de controle têm a capacidade de capturar o foco automaticamente reagindo a ações de UI integradas, como ui_up, ui_down, ui_focus_next, etc. Essas ações podem ser vistas nas configurações do projeto no mapa de entrada (input map) e podem ser modificadas.

Aviso

Como essas ações são usadas para o foco, elas não devem ser usadas para nenhum código de gameplay.

Configurações do nó

Além da lógica integrada, você pode definir o que é conhecido como vizinhos de foco (focus neighbors) para cada nó de controle individual. Isso permite ajustar finamente o caminho que o foco da UI faz pela interface do usuário do seu projeto. As configurações para nós individuais podem ser encontradas no painel Inspetor, sob a categoria "Focus" da seção "Control".

As opções de vizinhos são usadas para definir nós para navegação em 4 direções, como usar as setas do teclado ou o D-pad de um controle. Por exemplo, o vizinho inferior (bottom neighbor) será usado ao navegar para baixo com a seta para baixo ou ao pressionar para baixo no D-pad. As opções "Next" (Próximo) e "Previous" (Anterior) são usadas com o botão de alternância de foco, como Tab em sistemas operacionais de desktop.

Nota

Um nó pode perder o foco se for ocultado.

A configuração de modo define como um nó pode ser focado. All significa que um nó pode ser focado clicando nele com o mouse ou selecionando-o com um teclado ou controle. Click significa que ele só pode ser focado clicando nele. Por fim, None significa que ele não pode receber foco de forma alguma. Diferentes nós de controle têm configurações padrão distintas para isso com base em como são normalmente usados; por exemplo, nós Label são definidos como "None" por padrão, enquanto botões são definidos como "All".

Certifique-se de configurar adequadamente suas cenas para foco e navegação. Se um nó não tiver um vizinho de foco configurado, o motor tentará adivinhar o próximo controle automaticamente. Isso pode resultar em comportamentos indesejados, especialmente em uma interface de usuário complexa que não possui um fluxo de navegação vertical ou horizontal bem definido.

Código necessário

Para que a navegação por teclado e controle funcione corretamente, algum nó deve ser focado por meio de código quando a cena iniciar. Sem fazer isso, pressionar botões ou teclas não fará nada.

Você pode usar o método Control.grab_focus() para focar um controle. Aqui está um exemplo básico de como definir o foco inicial com código:

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

public override void _Ready()
{
    GetNode<Button>("StartButton").GrabFocus.CallDeferred();
}

Agora, quando a cena iniciar, o nó "Start Button" estará focado, e o teclado ou um controle poderão ser usados para navegar entre ele e os outros elementos da UI.