# Control Focus Switching and TAB/ALT Handling

## Architecture Overview

Control focus management in GacUI operates across three distinct architectural layers, each with specific responsibilities:

### Layer 1: Composition-Level Focus (`GuiGraphicsComposition`)

The lowest layer handles focus at the composition level through `GuiGraphicsHost`:

- `GuiGraphicsHost` maintains the currently focused composition in the `focusedComposition` member variable
- `GuiGraphicsHost::SetFocusInternal` is the core focus-switching method that:
  - Fires `lostFocus` event on the currently focused composition (if any)
  - Updates `focusedComposition` to the new composition
  - Resets caret point to (0,0)
  - Fires `gotFocus` event on the newly focused composition
- `GuiGraphicsHost::SetFocus` validates that the composition belongs to this host before calling `SetFocusInternal`
- `GuiGraphicsHost::ClearFocus` removes focus from any composition
- `GuiGraphicsHost::GetFocusedComposition` returns the currently focused composition
- Each composition has an event receiver that fires `gotFocus` and `lostFocus` events

### Layer 2: Control-Level Focus (`GuiControl`)

The middle layer connects controls to composition-level focus:

- Each `GuiControl` has a `focusableComposition` property (can be null)
- `GuiControl::SetFocusableComposition` attaches `gotFocus` and `lostFocus` event handlers to the composition
- When composition gains focus: `GuiControl::OnGotFocus` is called, which:
  - Sets `isFocused = true`
  - Updates control template state
  - Fires `FocusedChanged` event
- When composition loses focus: `GuiControl::OnLostFocus` is called, which:
  - Sets `isFocused = false`
  - Updates control template state
  - Fires `FocusedChanged` event
- `GuiControl::GetFocused` checks if the control is currently focused
- `GuiControl::SetFocused` is the public API to focus a control:
  - Returns early if no focusable composition exists
  - Returns early if control is not visually enabled
  - Returns early if focusable composition is not eventually visible
  - Gets the graphics host from the focusable composition
  - Calls `host->SetFocus(focusableComposition)`

### Layer 3: Focus Loss on State Changes

Focus is automatically cleared when controls undergo certain state changes:

- **When disabled**: `GuiControl::SetEnabled(false)` calls `UpdateVisuallyEnabled`, which triggers `OnLostFocus` if the control was focused
- **When hidden**: `GuiControl::SetVisible(false)` does NOT automatically clear focus (based on test case comments indicating unclear behavior)
- **When deleted**: `GuiGraphicsHost::DisconnectCompositionInternal` is called recursively, clearing `focusedComposition` if it matches the disconnected composition

## TAB Key Navigation

### Architecture Components

TAB navigation is managed by `GuiTabActionManager`, which is created and owned by `GuiGraphicsHost`.

#### IGuiTabAction Interface

Controls implement `IGuiTabAction` service to participate in TAB navigation:

- `GetAcceptTabInput()`: Returns whether control accepts TAB character as input (if true, TAB key is passed to control instead of used for navigation)
- `GetTabPriority()`: Returns priority for TAB order (-1 = lowest priority, 0, 1, 2... = higher priorities)
- `IsTabEnabled()`: Returns whether control can be tabbed to (checks if control is visible and enabled)
- `IsTabAvailable()`: Returns whether control is available for TAB navigation (checks if focusable composition exists)

#### Control List Building (`BuildControlList`)

The TAB manager builds a prioritized list of focusable controls:

- Uses `tab_focus::CollectControls` to recursively collect all controls from the control host
- Groups controls by their `TabPriority` value
- Inserts controls in priority order: 0, 1, 2, ..., then -1 (default/unprioritized)
- For each control, recursively collects its children and inserts them after the parent
- Result is a flattened list `controlsInOrder` sorted by TAB priority
- Cache is invalidated when a control's `TabPriority` changes via `GuiControl::SetTabPriority`

#### Focus Navigation (`GetNextFocusControl`)

Finding the next focusable control:

- Rebuilds control list if cache is invalidated (`available == false`)
- Takes current focused control and offset (+1 for forward TAB, -1 for backward SHIFT+TAB)
- Finds start index in the control list
- Wraps around using modulo arithmetic: `(index + offset + count) % count`
- Loops through controls until finding one that is both `IsTabAvailable()` and `IsTabEnabled()`
- Returns the next focusable control or null if none found

#### Key Event Handling

TAB key processing in `GuiTabActionManager::KeyDown`:

- Only processes TAB key when CTRL and ALT are NOT pressed
- If focused composition's control has `GetAcceptTabInput() == true`, TAB is NOT intercepted (returns false to let control handle it)
- Otherwise, calls `GetNextFocusControl` with offset based on SHIFT key state
- If next control found: calls `next->SetFocused()` and sets `supressTabOnce = true` to prevent TAB character insertion
- Returns true to indicate key was handled

Character suppression in `GuiTabActionManager::Char`:

- Suppresses the TAB character (`\t`) if `supressTabOnce` is true
- Resets `supressTabOnce` to false after checking

## ALT Key Navigation

### Architecture Components

ALT navigation is managed by `GuiAltActionManager`, which is created and owned by `GuiGraphicsHost`.

#### IGuiAltAction Interface

Controls implement `IGuiAltAction` service to have ALT shortcuts:

- `GetAlt()`: Returns the ALT key string (e.g., "F" for ALT+F)
- `IsAltEnabled()`: Returns whether ALT action is enabled (checks visible and enabled state)
- `IsAltAvailable()`: Returns whether ALT action is available (checks if focusable composition and alt string exist)
- `GetAltComposition()`: Returns the composition to show the ALT key label on
- `GetActivatingAltHost()`: Returns the alt host to enter when this action is activated (null = just activate)
- `OnActiveAlt()`: Called when ALT key is activated (default implementation calls `SetFocused()`)
- `IGuiAltAction::IsLegalAlt`: Validates that ALT string contains only uppercase letters (A-Z) and digits (0-9)

#### IGuiAltActionContainer Interface

Controls can implement this to provide multiple ALT actions:

- `GetAltActionCount()`: Returns the number of ALT actions
- `GetAltAction(index)`: Returns the ALT action at the specified index

#### IGuiAltActionHost Interface

Hosts create a hierarchy of ALT contexts that can be entered/exited:

- `GetAltComposition()`: Returns the composition for this host
- `GetPreviousAltHost()`: Returns the parent host in the hierarchy
- `OnActivatedAltHost(previousHost)` and `OnDeactivatedAltHost()`: Called when entering/leaving
- `CollectAltActions(actions)`: Collects all ALT actions for this host

ALT action collection from controls (`IGuiAltActionHost::CollectAltActionsFromControl`):

- Recursively traverses control tree starting from the specified control
- If control has `IGuiAltActionContainer`: collects all actions from it
- Else if control has `IGuiAltAction` and `IsAltAvailable()` and `IsAltEnabled()`: adds single action
- **Critical behavior**: When a control has an ALT action, executes `continue` which prevents its children from being added to the traversal queue
- This creates a "barrier" effect where children are hidden unless you enter a nested ALT context
- Recursively processes all children only if the control doesn't have its own ALT action

### ALT Mode Lifecycle

#### Activation

Pressing ALT (KEY_MENU) without CTRL or SHIFT:

- `GuiAltActionManager::KeyDown` checks if control host implements `IGuiAltActionHost`
- Calls `EnterAltHost` to enter ALT mode

`EnterAltHost` process:

- Calls `ClearAltHost` to clean up previous state
- Calls `host->CollectAltActions(actions)` to get all available actions
- If no actions available: calls `CloseAltHost` and exits
- Calls `host->OnActivatedAltHost(currentAltHost)` with previous host
- Updates `currentAltHost` to the new host
- Calls `CreateAltTitles` to create visual labels

#### Visual Label Creation (`CreateAltTitles`)

Creating ALT key labels:

- For each ALT action key (grouped by alt string):
  - If single action and non-empty key: uses key as-is
  - If multiple actions with same key: appends numeric suffix (0-999) with zero-padding
  - Creates `currentActiveAltActions` dictionary mapping full key (e.g., "F", "F00", "F01") to action
- For each action in `currentActiveAltActions`:
  - Creates a `GuiLabel` with `ThemeName::ShortcutKey` theme
  - Sets label text to the key string
  - Adds label to the action's composition
  - Stores label in `currentActiveAltTitles` dictionary
- Calls `FilterTitles` to update visibility

#### Key Input Handling (`EnterAltKey`)

Processing typed characters in ALT mode:

- Appends typed character to `currentAltPrefix`
- Checks if `currentAltPrefix` matches any action key in `currentActiveAltActions`
- If no match: calls `FilterTitles` and removes last character if no visible titles remain
- If exact match found:
  - If action has `GetActivatingAltHost()`: calls `EnterAltHost` to enter nested ALT host
  - Otherwise: calls `CloseAltHost` to exit ALT mode
  - Calls `action->OnActiveAlt()` to activate the action (usually focuses the control)
  - Sets `supressAltKey` to prevent key from being processed further
  - Returns true

#### Label Filtering (`FilterTitles`)

Updating label visibility based on current prefix:

- Iterates through all labels in `currentActiveAltTitles`
- If label's key starts with `currentAltPrefix`: shows label and formats text with brackets around next character (e.g., "F[0]0")
- Otherwise: hides label
- Returns count of visible labels

#### Exiting ALT Mode

Ways to exit ALT mode:

- Press ESCAPE: calls `LeaveAltHost` to exit current host and restore previous
- Press BACKSPACE: calls `LeaveAltKey` to remove last character from prefix
- Clicking or any other key: depends on whether key matches an action
- `CloseAltHost`: clears all state, deletes all labels, and exits all hosts in the hierarchy

#### Character and Key Suppression

Input suppression while in ALT mode:

- `GuiAltActionManager::Char` returns true to suppress all character input while in ALT mode or if `supressAltKey` is set
- `GuiAltActionManager::KeyUp` suppresses the key-up event for the key stored in `supressAltKey`

### Nested ALT Hosts

#### Why Nested ALT Hosts Are Needed

The `continue` statement in `CollectAltActionsFromControl` creates a "barrier" when a control has its own ALT action. This prevents the control's children from being collected at the parent level. Nested ALT hosts provide a mechanism to enter the control's context and collect children's ALT actions at a nested level.

**Design Rationales for Custom `GetActivatingAltHost` Implementations:**

1. **Non-Child Control Relationships** (`GuiMenuButton`):
   - Problem: A menu button's submenu is a separate popup window, NOT a child control
   - Default collection only traverses child controls, cannot reach submenu items
   - Solution: Returns `subMenu->QueryTypedService<IGuiAltActionHost>()` to switch context to submenu window
   - Result: Pressing ALT+[key] on menu button enters submenu's ALT context

2. **Intentional Blocking** (`GuiComboBoxBase`):
   - Problem: UX design requires ALT key to just open dropdown, NOT enter nested navigation
   - Default would collect ALT actions from dropdown's controls
   - Solution: Explicitly returns `GuiSelectableButton::GetActivatingAltHost()` (usually null)
   - Result: ALT key only opens dropdown without entering nested mode

3. **Dynamic/Temporary Content** (`GuiVirtualDataGrid`):
   - Problem: Cell editor is created on-demand, not a permanent child
   - Default collection only sees permanent children, misses temporary editor
   - Solution: When `currentEditor` exists and has ALT action, calls `SetAltComposition(currentEditor->GetTemplate())` and `SetAltControl(focusControl, true)`, returns `this`
   - Result: Can navigate within cell editor using ALT keys

4. **Scoped Navigation for Dense Control Groups** (`GuiRibbonGroup`):
   - Problem: Ribbon groups contain many buttons, exposing all at window level creates too many conflicts
   - Default would collect all buttons at same level as the group (if group didn't have its own ALT action)
   - But: `GuiRibbonGroup` has its own ALT action (from `GuiControl` base), which blocks children via `continue`
   - Solution: Returns `this` when `IsAltAvailable()` is true, creating two-level navigation
   - Result: First press ALT+[group-key] to enter group, then press ALT+[button-key] to select button
   - Benefit: Reduces conflicts and creates logical grouping

5. **Optional Scoped Navigation** (`GuiDatePicker`):
   - Problem: Date picker displays calendar with many clickable date cells, needs optional nested navigation
   - Solution: Returns `this` when `nestedAlt` constructor parameter is true
   - Result: When enabled, pressing ALT+[key] enters calendar's ALT context for date selection

#### The Critical Role of the `continue` Barrier

The `continue` statement in `CollectAltActionsFromControl` serves as a crucial design element:

- **Without nested hosts**: When a control has an ALT action, the `continue` prevents children from being collected, making them unreachable
- **With nested hosts**: `GetActivatingAltHost` provides a way to "un-hide" children by entering a nested context that re-collects them
- **For containers like `GuiRibbonGroup`**: This creates hierarchical navigation instead of flat navigation, reducing ALT key conflicts and improving scalability for interfaces with many controls

## Event Flow Integration

### Key Event Processing Chain

`GuiGraphicsHost::KeyDown` processes native window key events in this order:

1. First tries `GuiAltActionManager::KeyDown`: if ALT manager is active or activates, returns true to consume event
2. Then tries `GuiTabActionManager::KeyDown`: if TAB key is handled, returns true to consume event
3. Then tries shortcut key manager (if exists)
4. Finally delivers to focused composition's event receiver if not consumed

### Character Event Processing Chain

`GuiGraphicsHost::Char` processes character input in this order:

1. First tries `GuiTabActionManager::Char`: suppresses TAB character if just navigated
2. Then tries `GuiAltActionManager::Char`: suppresses all input while in ALT mode
3. Finally delivers to focused composition's event receiver if not suppressed

### Control Visibility and Enable State

`GuiControl::IsControlVisibleAndEnabled` determines if a control can receive focus:

- Traverses up parent chain checking both `GetVisible()` and `GetEnabled()`
- Used by both `IsAltEnabled()` and `IsTabEnabled()` to determine if control can receive focus via ALT or TAB
- Ensures that if a parent is disabled or invisible, all children are excluded from ALT/TAB navigation

## Test Coverage

### TAB Navigation Tests

`TestApplication_Tab.cpp` contains comprehensive TAB navigation tests:

- `TabNavigate`: Tests forward TAB through 3 buttons and backward SHIFT+TAB
- `TabNavigateWithContainer`: Tests TAB through 5 buttons including nested containers (GroupBox)
- `FocusedAndDisable`: Tests that disabling focused control clears focus
- `FocusedAndHide`: Tests hiding focused control (focus behavior noted as unclear in comment)
- `FocusedAndDelete`: Tests deleting focused control clears focus

### ALT Focus Test

`TestControls_CoreApplication_GuiControl.cpp` contains `AltFocus` test:

- Tests ALT key activation in nested control scenarios