TabFocus

ceramic.Entityelements.TabFocus (Class)
Implements: ceramic.Component

Component for managing keyboard-based focus navigation using Tab key.

TabFocus provides automatic Tab/Shift+Tab navigation between TabFocusable elements within a visual hierarchy. It handles focus traversal in both forward and backward directions, and supports Escape key handling for focus escape behavior.

The component automatically finds focusable elements and manages focus transitions based on their position in the visual hierarchy. It respects the focusRoot boundary when specified, limiting focus navigation to a specific visual subtree.

Key features:

  • Tab key navigation (forward focus)
  • Shift+Tab navigation (backward focus)
  • Escape key handling for focus escape
  • Configurable focus root for bounded navigation
  • Automatic detection of TabFocusable elements
  • Circular navigation (wraps to beginning/end)

Usage example:

var tabFocus = new TabFocus();
tabFocus.focusRoot = myFormContainer; // Optional: limit to this subtree
myWindow.component('tabFocus', tabFocus);

Instance Members

elements
entity: ceramic.Visual

The visual entity this component is attached to


elements
focusRoot: ceramic.Visual

Optional root visual that limits the scope of focus navigation.

When set, tab navigation will only consider TabFocusable elements within this visual's hierarchy. If null, the entire entity hierarchy is considered.


elements
initializerName: String

elements
new(): Void

Private Members

elements
leftShiftPressed: Bool

Whether the left Shift key is currently pressed


elements
rightShiftPressed: Bool

Whether the right Shift key is currently pressed


elements
findingWithFocused: ceramic.Visual

Reference to the currently focused visual during navigation search.

Used internally to track position in the hierarchy when finding the next/previous focusable element.


elements
bindAsComponent(): Void

Called when the component is bound to its entity.

Sets up keyboard event listeners for Tab navigation and Escape handling.


elements
handleKeyDown(key: ceramic.Key): Void

Handles key down events for focus navigation.

Processes Tab (forward), Shift+Tab (backward), and Escape key events when the current focus is within the managed visual hierarchy.

Name Type Description
key ceramic.Key The key event information

elements
handleKeyUp(key: ceramic.Key): Void

Handles key up events to track Shift key state.

Updates the shift key pressed state which determines navigation direction.

Name Type Description
key ceramic.Key The key event information

elements
focusNextField(): Void

Moves focus to the next focusable element in the hierarchy.

Searches forward from the currently focused element. If no focusable element is found after the current one, wraps around to search from the beginning.


elements
focusPrevField(): Void

Moves focus to the previous focusable element in the hierarchy.

Searches backward from the currently focused element. If no focusable element is found before the current one, wraps around to search from the end.


elements
findNextFocusable(walkVisual: ceramic.Visual): TabFocusable

Recursively searches for the next TabFocusable element in the visual hierarchy.

Performs a depth-first search starting from the given visual. When findingWithFocused is set, skips elements until that visual is found, then returns the next focusable element.

Name Type Description
walkVisual ceramic.Visual The visual to start searching from
Returns Description
TabFocusable The next TabFocusable element, or null if none found

elements
findPrevFocusable(walkVisual: ceramic.Visual): TabFocusable

Recursively searches for the previous TabFocusable element in the visual hierarchy.

Performs a reverse depth-first search starting from the given visual. When findingWithFocused is set, skips elements until that visual is found, then returns the previous focusable element.

Name Type Description
walkVisual ceramic.Visual The visual to start searching from
Returns Description
TabFocusable The previous TabFocusable element, or null if none found

elements
findCurrentFocusable(): TabFocusable

Finds the currently focused TabFocusable element.

Checks if the currently focused visual implements TabFocusable, or searches up the parent hierarchy to find a TabFocusable ancestor.

Returns Description
TabFocusable The currently focused TabFocusable element, or null if none

elements
setEntity(entity: ceramic.Entity): Void
Name Type
entity ceramic.Entity

elements
getEntity(): ceramic.Entity
Returns
ceramic.Entity

Metadata

Name Parameters
:build ceramic.macros.ComponentMacro.build()
:autoBuild ceramic.macros.ComponentMacro.build()
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()