Overview
Containers track keyboard focus. By default, any keyboard events are only delivered to the widget in the focused container. The user changes the focused container by using a mouse or delivering configured keyboard shortcuts. If the focused container has a border, its color will change according to the value of the container.FocusedColor option.
Note that widgets can also register for global keyboard events, see the Widget API for more details.
Focus indication
The following diagram shows two containers, the right container has the keyboard focus so its border is highlighted. Refer to Container style for details about border styles and options that customize the colors.
/images/container-api/border_styles.png
Changing which container is focused
Using mouse events
A mouse click delivered to an area within a container moves the keyboard focus to that container.
Using keyboard events
The container offers two options that allow the user to configure keyboard keys that change which container is focused. Using these keys, the user can change the focus to the next or the previous container. The containers are organised in a binary tree.
When changing focus to the next container, the focus will move to the next leaf container (a container that isn't itself split into sub-containers) that comes right after the currently focused container in a DFS (Depth-first search) traversal of the binary tree.
Similarly when changing focus to the previous container, the focus will move to the previous leaf container in that comes right before the currently focused container in a DFS (Depth-first search) traversal of the binary tree.
Note that this ordering applies regardless whether the application uses the Binary tree layout or the Grid layout. Containers are always represented as a binary tree within termdash.
container.KeyFocusNext:
The container.KeyFocusNext option is used to configure a key that will move the focus to the next container. No key will perform this function if not specified.
container.KeyFocusPrevious:
The container.KeyFocusPrevious option is used to configure a key that will move the focus to the previous container. No key will perform this function if not specified.
Delivering keyboard keys to widgets
Even if a key is configured to move the focus, it still gets delivered as a keyboard event to widgets that subscribe to keyboard events. See the Widget API for details about subscribing widgets to keyboard events.
A widget that subscribed with KeyScopeGlobal always get's the key press event. A widget that subscribed with KeyScopeFocused only gets the key press event if it is focused after the focus change.
Using keyboard events within focus groups
In addition to the container.KeyFocusNext and container.KeyFocusPrevious options that allow moving keyboard focus through all leaf containers, the user can also assign containers into separate focus groups.
container.KeyFocusGroups:
The container.KeyFocusGroups assigns a container into focus groups each identified by a number.
container.KeyFocusGroupsNext:
The container.KeyFocusGroupsNext is like the container.KeyFocusNext option, but the keys configured using this option only move the keyboard focus within the specified focus groups. The key only takes effect if the currently focused container is a part of one of the specified focus groups.
container.KeyFocusGroupsPrevious:
The container.KeyFocusGroupsPrevious is like the container.KeyFocusPrevious option, but the keys configured using this option only move the keyboard focus within the specified focus groups. The key only takes effect if the currently focused container is a part of one of the specified focus groups.
