네이티브 설정 예제는 공개 API를 완전하게 사용하는 소비자입니다. README의 명령으로 두 화면 표현 중 어느 쪽으로든 실행할 수 있습니다. 이 예제는 Button, Input, Select, Textarea, Field, Label, Combobox, Calendar, DatePicker, Checkbox, Switch, RadioGroup, Slider, Progress, Toggle, ToggleGroup을 내비게이션 및 오버레이 컨트롤과 조합합니다. 라이브러리에는 외형을 넣지 않습니다. 내비게이션과 오버레이 가이드는 탭과 키보드 도움말 팝오버를 설명합니다. 레이아웃과 데이터 가이드는 Schedule 테이블과 폼의 ScrollArea 조합을 다룹니다.
gpui_deck::init(cx)를 한 번 호출하고 창 콘텐츠를 gpui_deck::Root 안에 둡니다.
Root는 Tab 순회를 제공하고, 열린 Dialog 안에서는 순회를 그 안으로 가둡니다. 각
컨트롤에 안정적인 요소 ID와 접근 가능한 레이블을 지정합니다.
상태 소유권
| 컨트롤 | 상태 소유자 | 애플리케이션 갱신 |
|---|---|---|
| Textarea | 유지되는 Entity<TextareaState> | 주변 화면 표현을 위해 관찰합니다. 편집은 기존 Input 이벤트가 보고합니다 |
| Field | 애플리케이션의 레이블, 도움말, 필수 여부, 검증 오류 | 기존 Input, Textarea, Combobox 쿼리 주위에 현재 메타데이터를 렌더링합니다. 새 입력 상태는 없습니다 |
| Label | 애플리케이션 텍스트, 대상 FocusHandle, 비활성화 플래그 | 클릭하면 기존 컨트롤에 포커스를 줍니다. 접근 가능한 이름과 비활성화 상태를 동기화합니다 |
| Combobox | 유지되는 Entity<ComboboxState> | 렌더링을 위해 관찰합니다. ComboboxEvent::Change가 사용자가 확정한 선택 값을 보고합니다 |
| Calendar | 유지되는 Entity<CalendarState> | 렌더링을 위해 관찰합니다. CalendarEvent::Change가 변경된 단일/다중/범위 선택을 보고합니다 |
| DatePicker | 기존 Calendar/Popover 상태를 조합하는 유지되는 Entity<DatePickerState> | 선택과 팝업 렌더링을 위해 관찰합니다. 단일 및 완성된 범위 이벤트는 팝업이 닫힌 뒤 발생하고, 부분/다중 이벤트는 팝업을 유지합니다 |
| Checkbox | CheckboxState 또는 bool 타입의 애플리케이션 필드 | on_change가 다음 상태를 보고합니다. 저장한 뒤 cx.notify()를 호출합니다 |
| Toggle | 애플리케이션 bool | on_change가 다음 눌림 값을 요청합니다. pressed로 다시 렌더링합니다 |
| ToggleGroup | 유지되는 Entity<ToggleGroupState> | 렌더링을 위해 관찰합니다. ToggleGroupEvent::Change가 선택된 값을 항목 순서대로 보고합니다 |
| Switch | 애플리케이션 bool | on_change가 다음 값을 보고합니다. 저장한 뒤 cx.notify()를 호출합니다 |
| RadioGroup | 유지되는 Entity<RadioGroupState> | 렌더링을 위해 엔티티를 관찰합니다. 사용자 선택 변경은 RadioGroupEvent::Change를 구독합니다 |
| Select | 유지되는 Entity<SelectState> | 렌더링을 위해 엔티티를 관찰합니다. 확정된 사용자 변경은 SelectEvent::Change를 구독합니다 |
| Slider | 유지되는 Entity<SliderState> | 렌더링을 위해 관찰합니다. SliderEvent::Change가 변경된 정렬 값을 보고합니다 |
| Progress | 애플리케이션 백분율과 불확정 플래그 | 렌더링마다 현재 값과 상태를 전달합니다. 상호작용 콜백은 없습니다 |
Checkbox와 Switch는 제어 컴포넌트입니다. 렌더링만으로는 애플리케이션 상태가
바뀌지 않습니다. 콜백 이후 애플리케이션이 전달한 값을 바꾸지 않으면
컨트롤은 그 값을 계속 표시합니다. 프로그램에서 필드를 바꾸면 다음 렌더링에
반영되며 on_change는 호출되지 않습니다.
네이티브 예제처럼 유지되는 엔티티와 그 구독은 뷰에 보관합니다. 렌더링할 때마다 RadioGroupState를 다시 만들면 선택과 안정적인 옵션 포커스 핸들이 사라집니다.
키보드와 비활성화 동작
| 입력 | Checkbox / Switch | RadioGroup |
|---|---|---|
| Tab / Shift-Tab | 활성화된 컨트롤로 들어가거나 나갑니다 | 선택된 활성 옵션으로, 선택이 없으면 첫 번째 활성 옵션으로 들어갑니다. 그룹 전체가 하나의 Tab 스톱입니다 |
| Space / Enter | 네이티브 활성화 경로로 다음 값을 요청합니다 | 포커스된 옵션을 선택합니다 |
| Right / Down | 선택 이동이 없습니다 | 다음 활성 옵션을 선택하고 포커스합니다. 끝에서는 처음으로 돌아갑니다 |
| Left / Up | 선택 이동이 없습니다 | 이전 활성 옵션을 선택하고 포커스합니다. 처음에서는 끝으로 돌아갑니다 |
| Escape | 상위 영역으로 전파됩니다 | 상위 영역으로 전파됩니다 |
RadioGroup의 화살표 선택은 즉시 적용됩니다. Select는 팝업이 열려 있는 동안 대기 중인 키보드 커서를 유지하고 활성화할 때만 확정합니다. 둘 다 비활성화된 옵션을 건너뜁니다. 비어 있거나 모든 옵션이 비활성화된 RadioGroup에는 Tab 스톱이 없습니다.
비활성화된 컨트롤은 활성화를 무시하고 Tab 순회에서 제외됩니다. 포커스된 컨트롤이 비활성화되면 포커스가 떠날 때까지 포커스 바인딩을 유지하므로 Tab과 Shift-Tab으로 이웃 컨트롤에 계속 도달할 수 있습니다.
검증 범위
기존 GPUI 테스트는 포인터와 네이티브 키 이벤트 라우팅, checked/mixed 메타데이터, 비활성화 동작, 그룹 내비게이션, 숫자 컨트롤, 그리고 두 화면 표현에 걸친 대표적인 설정 흐름을 다룹니다. 헤드리스 이벤트 시뮬레이션은 운영체제 IME, 스크린리더, 혼합 DPI 디스플레이, 네이티브 창의 렌더링된 외형을 검증하지 않습니다. 이러한 확인은 자동화된 동작 테스트와 별개로 남아 있습니다.