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

키보드/컨트롤러 탐색 및 포커스

탐색 및 상호 작용을 위해 전체 키보드와 컨트롤러를 지원하는 것은 사용자 인터페이스의 일반적인 요구 사항입니다. 이것이 프로젝트에 도움이 되는 두 가지 주된 이유는 향상된 접근성(모든 사람이 상호 작용을 위해 마우스나 터치 컨트롤을 사용할 수 있는 것은 아님)과 프로젝트를 콘솔(또는 PC에서 컨트롤러로 게임을 선호하는 사람들을 위해)에 맞게 준비하는 것입니다.

키보드 또는 컨트롤러를 사용하여 UI 요소 간 탐색은 어느 노드가 활성으로 선택되는지 변경하여 수행됩니다. 이를 UI 포커스 변경이라고도 합니다. Godot의 모든 Control 노드는 집중할 수 있습니다. 기본적으로 일부 컨트롤 노드에는 ui_up, ui_down, ui_focus_next 등과 같은 내장 UI 작업에 반응하여 자동으로 포커스를 잡는 기능이 있습니다. 이러한 작업은 입력 맵의 프로젝트 설정에서 볼 수 있으며 수정할 수 있습니다.

경고

이러한 액션은 집중을 위해 사용되므로 게임플레이 코드에 사용하면 안 됩니다.

MultiMesh 설정

내장된 로직 외에도 각 개별 컨트롤 노드에 대해 포커스 인접 항목을 정의할 수 있습니다. 이를 통해 프로젝트의 사용자 인터페이스 전반에 걸쳐 UI 포커스가 이동하는 경로를 미세하게 조정할 수 있습니다. 개별 노드에 대한 설정은 "제어" 섹션의 "초점" 범주 아래 인스펙터 독에서 찾을 수 있습니다.

이웃 옵션은 화살표 키 또는 컨트롤러의 D패드 사용과 같은 4방향 탐색을 위해 노드를 정의하는 데 사용됩니다. 예를 들어 아래쪽 화살표를 사용하여 아래로 탐색하거나 D 패드를 아래로 누를 때 아래쪽 이웃이 사용됩니다. "다음" 및 "이전" 옵션은 데스크톱 운영 체제의 :kbd:`Tab`과 같은 포커스 이동 버튼과 함께 사용됩니다.

참고

노드가 숨겨지면 포커스를 잃을 수 있습니다.

모드 설정은 노드의 초점을 맞추는 방법을 정의합니다. **모두**는 노드를 마우스로 클릭하거나 키보드 또는 컨트롤러로 선택하여 초점을 맞출 수 있음을 의미합니다. **클릭**은 클릭해야만 초점을 맞출 수 있다는 의미입니다. 마지막으로 **없음**은 전혀 집중할 수 없음을 의미합니다. 다양한 컨트롤 노드에는 일반적으로 사용되는 방식에 따라 이에 대한 기본 설정이 다릅니다. 예를 들어 Label 노드는 기본적으로 "없음"으로 설정되고 :ref:`buttons <class_Button>`은 "모두"로 설정됩니다.

초점과 탐색을 위해 장면을 올바르게 구성했는지 확인하십시오. 노드에 구성된 포커스 이웃이 없으면 엔진은 자동으로 다음 제어를 추측하려고 시도합니다. 이로 인해 특히 수직 또는 수평 탐색 흐름이 잘 정의되지 않은 복잡한 사용자 인터페이스에서 의도하지 않은 동작이 발생할 수 있습니다.

필요한 코드

키보드 및 컨트롤러 탐색이 올바르게 작동하려면 씬이 시작될 때 코드를 사용하여 노드에 초점을 맞춰야 합니다. 이렇게 하지 않으면 버튼이나 키를 눌러도 아무 일도 일어나지 않습니다.

Control.grab_focus() 메서드를 사용하여 컨트롤에 초점을 맞출 수 있습니다. 다음은 코드를 사용하여 초기 포커스를 설정하는 기본 예입니다.

GDScriptC#

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

이제 씬이 시작되면 "시작 버튼" 노드에 초점이 맞춰지고 키보드나 컨트롤러를 사용하여 다른 UI 요소 사이를 탐색할 수 있습니다.