Using focus

Keyboard focus forwards hardware key messages to the correct user interface element in your application. For example, the user can press the arrow keys on the keyboard to move a slider or press the Enter key to click a button. You can use the default keys that Kanzi uses to navigate focus, or set a specific keyboard key. See Default keyboard navigation keys and Setting a specific keyboard key to move focus.

To handle focus in your Kanzi application, you can:

• Set focus to a specific user interface element. See Setting focus.
• Change the appearance of a user interface element when that element has focus. See Showing when a user interface element has focus.
• Set the order in which user interface elements receive focus. See Moving focus in a focus chain.
• Forward the focus from a user interface element to a part of that element. See Setting a focus scope.
• Allow the user to navigate a part of your application. See Setting a focus fence.
• Set a specific keyboard key to move focus. See Setting a specific keyboard key to move focus.

Learn how to use focus by completing a tutorial. See Tutorial: Use keyboard input to navigate your application.

Default keyboard navigation keys

These are the default keyboard keys you can use to navigate the focus in your application:

• Navigate in the forward direction by pressing the Tab key and in the backward direction by pressing the Shift Tab keys.
• Navigate between nodes based on their rendered position using the ← (Left Arrow), → (Right Arrow), ↑ (Up Arrow), and ↓ (Down Arrow) keys.
• When a Button node has focus, it receives input from the keyboard keys Space, Enter, and Enter on the numeric pad.
• When a Toggle Button node has focus, it receives click input from the keyboard keys Space, Enter, and Enter on the numeric pad.

• When a Slider node has focus use:

  • The ← (Left Arrow) and → (Right Arrow) keyboard keys if the slider knob moves in a horizontal direction
  • The ↑ (Up Arrow) and ↓ (Down Arrow) keyboard keys if the slider knob moves in a vertical direction

  To move a slider knob with keyboard keys, in the Properties you need to set the Step Value property for that slider to define how many steps the knob moves each time you press a key.

• When a Scroll View node has focus, you can scroll the contents of that node using the ← (Left Arrow), → (Right Arrow), ↑ (Up Arrow), and ↓ (Down Arrow) keyboard keys.

• When a Grid List Box node has focus use:

  • The ↑ (Up Arrow) and ↓ (Down Arrow) keyboard keys to scroll the list items in a vertical list box
  • The → (Right Arrow) and ← (Left Arrow) keyboard keys to scroll the list items in a horizontal list box
  • The Home keyboard key selects the first list item
  • The End keyboard key selects the last list item
  • The Page Up and Page Down keyboard keys go to the beginning and end of the visible area of a list box

Setting focus

The user can interact with user interface elements using keyboard keys when those elements have focus. By default the Screen node has focus.

To set focus:

1. In the Project select the node to which you want to set focus and in the Node Components add a trigger which you use to set off the action that sets the focus.
   For example, add a Page Activated trigger. The Page Activated trigger is set off when a Page or Page Host node becomes active.
   
2. In the Node Components add to the Page Activated trigger a Set Focus action.
   You set the application to set focus to a node when the Page or Page Host node to which you added the trigger becomes active.
   
3. In the Set Focus action set the Target Item to the node to which you want to set focus.
   For example, set the Target Item to a Slider 2D node to set focus to a slider on the Page or Page Host node when that node becomes active.
   

When you navigate to the Page node to which you added the trigger, you set focus to the node you set in the action. For example, if you set focus to a Slider node, you can by default use the arrow keys on your keyboard to move the slider.

Showing when a user interface element has focus

You can set a user interface element, such as a button or a slider, to change appearance when it has focus. For example, you can highlight a button when that button has focus or change how a slider knob looks when the slider has focus.

To show when a user interface element has focus:

1. In the Project select the node for which you want to create focus visualization and in the State Tools click Create State Manager to create a state manager for that node.
   
   
2. In the State Tools click Create State twice to create two states. Name them, for example, NotFocused and Focused.
   The NotFocused state defines the state of your application when the node is not focused and the Focused state when the node is focused.
   
   
3. In the Project select the node for which you want to create focus visualization and set the value of the property you want to change when that node has focus.
   For example, you can use a different image for the slider knob when the slider has focus.
   
4. In the State Tools click below the state which defines how the node looks when it has focus to save the current property values to that state.
   For example, click below the Focused state.
   
   
5. In the State Tools click the <No Controller Property> dropdown menu and select the Node > Focused property.
   When you set the Focused property as the controller property for the state manager, the state manager transitions to a state based on the value of that property.
   
   
6. In the State Tools under the state which defines how the node looks when it has focus, set the value of the Focused property to True.
   
   
7. In the State Tools click Edit State Manager to deactivate the State Tools.

When you set focus to the slider, the appearance of the slider knob changes.

Moving focus in a focus chain

Focus chain is a sequence of nodes which defines the order in which Kanzi sets focus to those nodes. Kanzi automatically includes in the focus chain all nodes in your project. By default the focus chain moves the active focus from each node to the next child node. When a node has no child node which can receive focus, the focus moves to the next node in the project tree. You can define a custom focus chain or redirect the default focus chain navigation by setting which node receives focus after the currently focused node.

To move focus in a focus chain:

1. In the Project select each node which you want to receive focus and in the Properties add and set to which node you want to move focus:
   • Next Focus Node property sets focus to the node you set in that property when the user navigates in the forward direction.
     For example, set the Next Focus Node property to point to a node which represents a control you show on the same application screen, such as a list box or a button.
   • Previous Focus Node property sets focus to the node you set in that property when the user navigates in the backward direction.

   You can move the focus to the next node in the focus chain by pressing the Tab key and to the previous node by pressing the Shift Tab keys.

   • Left Navigation Node property sets focus to the node you set in that property which is rendered on the left hand side of the currently focused node.
   • Right Navigation Node property sets focus to the node you set in that property which is rendered on the right hand side of the currently focused node.
   • Up Navigation Node property sets focus to the node you set in that property which is rendered above the currently focused node.
   • Down Navigation Node property sets focus to the node you set in that property which is rendered below the currently focused node.

   You can move the focus to the left, right, up, and down navigation nodes by pressing the ← (Left Arrow), → (Right Arrow), ↑ (Up Arrow), and ↓ (Down Arrow) keys.

   

   TIP

   You can define a focus chain using an alias or the path to each node.
   Aliases provide a convenient way to set the nodes in a focus chain. See Using aliases.
   

2. In the Project select each node for which you want to disable focus and in the Properties right-click, select Add Property > Node > Focusable property, and disable that property.

   
   

Setting a focus scope

Use a focus scope to handle navigation in a focus chain. You can set a node to be a focus scope to forward the focus from that node to a child node. When you set focus to a focus scope, Kanzi forwards the focus to the child node of that scope which has logical focus.

To set a focus scope:

1. In the Project select the node which you want to set as a focus scope and in the Properties add and enable the Focus Scope property.
   
2. In the Project select the child node of the focus scope node to which you want to set focus and in the Properties add and enable the Logical Focus property.
   When you set focus to the focus scope node, the child node for which you enable the Logical Focus property receives focus. If the focus scope has several child nodes with the Logical Focus property enabled, the focus manager sets focus to the last child node.
   

Setting a focus fence

Use a focus fence to navigate the focus within a part of an application. A focus fence allows the user to navigate the content within the boundaries of a focus scope. For example, you can use a focus fence to create keyboard navigation for a navigation bar or a popup window.

To set a focus fence:

1. In the Project select the node which you want to set as a focus fence and set that node as a focus scope. See Setting a focus scope.
2. In the Project select the node you set as a focus scope, in the Properties add the Focusable property, and disable the property.
   When you set a focus scope to not receive focus, you cannot navigate to or from the focus scope boundaries.
   

Setting a specific keyboard key to move focus

When creating keyboard navigation for your application, you can set which keyboard keys the user can use to navigate the application. You can override the default focus navigation keys and use a specific key to set focus to a node or move focus in the focus chain.

To set a specific keyboard key to move focus:

1. In the Project select the node from which you want to move focus to another node with a specific keyboard key.
   
2. In the Node Components right-click in the Triggers and add the Keyboard > Key Down trigger.
   You use the Key Down trigger to set off an action which sets focus to a node when the user presses a specific key on the keyboard.
   
   
3. In the Node Components click Trigger Settings and in the Trigger Settings Editor click Add condition. The Trigger Condition Editor opens.
   Trigger conditions enable you to set which conditions must be met for the trigger to set off. You set off the Key Down trigger when the node to which you added that trigger has focus and the user presses a specific key on the keyboard.
   
4. In the Trigger Condition Editor set which keyboard key sets off the Key Down trigger:
   • Value A
     • Value From to Message
       The Key Down trigger intercepts the messages generated when a user presses down a key on their keyboard. The message contains the key code which Kanzi uses to set off the trigger.
   • Operator to =
   • Value B
     • Value From to Fixed
     • Fixed Value to the key code for the key you want to use to set off the trigger.
       For example, use 19. You use the key code for the E key to set off the trigger when the user presses that key on their keyboard. For a list of the keyboard key codes used in Kanzi, see Keyboard input codes reference.

   
   In the Trigger Condition Editor and the Trigger Settings Editor windows click Save.

5. In the Node Components add to the Key Down trigger a Move Focus action.
   
   
6. In the Move Focus action set the Direction property to the direction in the focus chain in which you want to move the focus.
   For example, to move the focus to the next node in the focus chain, set the Direction property to Forward. See Moving focus in a focus chain.
   

When the user presses down the E key, the Key Down trigger sets off the action which moves the focus to the next focusable node in the direction you set in the Move Focus action.

Using focus in the API

For details, see the FocusManager class in the API reference.

See also

Focus

Tutorial: Use keyboard input to navigate your application

Using state managers

Actions reference

Open topic with navigation