miniboxtk - focus and keyboard navigation

Each window can have one widget that is focused. Focus is indicated in a style-specific way, usually with a rectangle drawn within the widget frame. When a key is pressed, the focused widget of the active window gets the event.

Each widget has a focus preference value, which is an integer between 0 and 255. If this value is 0, the widget will not take the focus. Other values are used when picking the initial focus in a window: the higher the value, the more chance the widget will get the initial focus.

Setting focus by mouse clicks

Focus is usually changed to a new widget when the user clicks on that widget.

Setting focus by keyboard

Keyboard navigation is possible using the tab key or the arrow keys, unless the currently focused widget uses (some of) these keys for other purposes.

The tab and shift-tab key will move focus to the next/previous focusable widget in the widget tree. The order of iterating through widgets reflects the widget tree structure. When the last widget is reached the next tab press will roll over and focus the first widget. Likewise, when the first widget is reached, the next shift-tab press wil roll over and focus the last widget in the window.

Navigation is also possible using the arrow keys, in which case the geometrically nearest focusable widget (in the given direction) next to the current widget is focused.

Keyboard nav corner cases

Some widgets may use the usual focus navigation keys for its own purposes. The most trivial example is textedit, which uses arrows to move the cursor and tab to insert a tab character in the text that is being edited. This means arriwing at the first textedit widget while navigating through widgets using the keyboard would "trap" focus: pressing tab or arrow keys wouldn't be able to move the focus anymore until the focus is moved away by a mouse click.

To overcome this problem, the textedit widget has a 2-level focus mechanism. When the widget gets focus in keyboard navigation, it does not activate text editing but indicates focus in the usual style-specific way. This is the "outer focus". If enter is pressed, the focus is moved to the "inner focus", which means removing the style-specific focus undication and placing the cursor in the text area. If the user presses shift-tab while editing the text, the widget returns to the "outer focus" mode.

This way using the tab key or arrow keys lets the user iterate through textedit widgets easily. In case the user wants to edit the text, enter needs to be pressed. Escaping text edit is shift-tab.

Mouse click into the text always activates the "inner focus" mode directly.