Tutorial: Implementing Focus to navigate and select controls without touch events

Focus is an available parameter for indexing multiple table cells and controls. Utilizing focus is a great way to navigate around a list of objects, whether or not touch-based events are present in the project. This tutorial will walkthrough a typical use case for focus indexes and focus events by using keyboard keys to navigate and select through a set of controls.

Here is an application showing 3 controls with a unique animal image on each. The goal is to be able to highlight and select these controls without using any touch events.

The first step is to assign a focus index for each animal in ascending order, Camel – 1, Moose – 2, Rhino – 3. The focus index tells Storyboard in what order these controls will be selected, every non-zero focus index is considered a focusable control. Focus indexes can be set using the grd_findex variable, or in a control’s properties under Advanced and OpenGL:


This particular application uses the left and right arrow keys as the trigger events to move through the focus order, but this effect can be achieved with any other event. For example, if there are hard buttons on a product, you can connect those inputs to custom Storyboard IO events to drive navigation.

When this application receives a gre.keydown event, it calls out to Lua to unpack the key code and handle sending the correct event. If the key code received is mapped to the right arrow, it sends an event to trigger the  Screen Focus Next action, which will select the control with the next focus index on the current screen.

On startup, Camel(1) is selected by default. When Screen Focus Next is called, Moose(2) will then be selected, the Rhino(3) after, and it will wrap around back to Camel after Rhino. Screen Focus Previous selects the controls in descending order. Similarly, Screen Focus Set and gre.set_focus can be used to directly focus a specific control using its fully qualified name (fqn).

Each control can then react to its focused state in the form of a trigger event with gre.gotfocus and gre.lostfocus. For this application, a Data Change action is called on a control to hide/show a selection rectangle render extension:


If the Lua receives an event from the Space bar or Enter key, it will send a targeted event to change the visual layout of the screen for the selected animal. gre.get_focus is used here to retrieve the fully qualified name of the control that is currently in focus.

if key == 32 or key == 13 then -- Space Bar or Enter




Utilization of focus in an application is a great way to manage navigation and selection states in a set of controls. This is a helpful feature for projects that might use outside inputs such as hard buttons or voice commands to navigate through the user interface for accessibility.

An important note is that focus can still be used along with touch to track selection state. When a focusable control (findex > 0) receives a gre.touch event, it is automatically updated as the focused control on a screen. This means if the UI has multiple input options like SBIO, voice, keyboard or touch, focus will still be able to manage selection state across all inputs.

Feel free to download this example project and test it out yourself: FocusSelection.zip




Please sign in to leave a comment.

Didn't find what you were looking for?

New post