Using the Key Manipulator

Use the Key Manipulator to set the keyboard keys that the user can use to navigate your application.

For example, you can override the default focus navigation keys and use a specific key to set focus to a node, set a key to open or close a popup-type window, or move focus in the focus chain.

Default keyboard navigation keys

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

• Navigate in the forward direction by pressing the Tab key and in the backward direction by pressing the BackTab key or Shift Tab keys.

• The Button nodes have the Focusable property enabled by default. This means that the Button nodes can receive focus. When a Button node has focus, to press that button, you can use the default keyboard keys Space, Enter, and Enter on the numeric pad.

• The Toggle Button nodes have the Focusable property enabled by default. This means that the Toggle Button nodes can receive focus. When a Toggle Button node has focus, to press that button, you can use the default keyboard keys Space, Enter, and Enter on the numeric pad.

• The Slider nodes have the Focusable property enabled and are focusable by default. When a Slider node has focus, to move the knob of that slider, you can use these default keyboard keys:

  • Home to move the slider knob to the beginning of the rail

  • End to move the slider knob to the end of the rail

  • ← and → to move the knob of a horizontal slider

  • ↑ and ↓ to move the knob of a vertical slider

  To move a slider knob with the arrow keyboard keys, in that Slider node set the amount that the knob moves for each key press with the Step Value property.

• The Scroll View nodes have the Focusable property enabled and are focusable by default. When a Scroll View node has focus, to scroll that node, you can use the default keyboard keys ←, →, ↑, and ↓.

• When a Grid List Box node has focus use these keyboard keys:

  • ↑ and ↓ to scroll the list items in a vertical list box

  • → and ← to scroll the list items in a horizontal list box

  • Home to select the first list item

  • End to select the last list item

  • Page Up and Page Down to go to the beginning and end of the visible area of a list box

• When a Text Box node is in the editing state, to move the cursor in that text box, you can use these default keyboard keys:

  • ← to move the cursor one character backward.

  • → to move the cursor one character forward.

  • Ctrl ← to move the cursor to the word boundary that precedes the cursor.

  • Ctrl → to move the cursor to the word boundary that follows the cursor.

  • Home to move the cursor to the beginning of the text content.

  • End to move the cursor to the end of the text content.

  When a Text Box node is in the editing state, to modify the text selection in that text box, you can use these default keyboard keys:

  • Shift ← to move the active cursor in the text selection one character backward.

  • Shift Ctrl to move the active cursor in the text selection to the word boundary that precedes the current position.

  • Shift Home to move the active cursor in the text selection to the beginning of the text content.

  • Shift → to move the active cursor in the text selection one character forward.

  • Shift Ctrl → to move the active cursor in the text selection to the word boundary that follows the current position.

  • Shift End to move the active cursor in the text selection to the end of the text content.

  • Ctrl A to select all text.

Using the Key Manipulator triggers

Use the Key Manipulator triggers to react when the user presses or releases a keyboard key. For example, you can override the default focus navigation keys and use a specific key to set focus to a node, open or close a popup-type window, or move focus in the focus chain. See Default keyboard navigation keys.

The Key Manipulator has these triggers:

• Key Pressed trigger is set off when the user presses a specific key on their keyboard.

• Key Released trigger is set off when the user releases a specific key on their keyboard.

• Key Canceled trigger is set off when the user cancels a key press gesture.

To use the Key Manipulator triggers:

1. Add and configure a Key Manipulator:

   1. In the Node Tree select a node that you want to receive input from a specific keyboard key.

      For example, to close a popup-type window with a specific keyboard key, select the node which represents that popup-type window. When the popup-type window closes, you move the focus to the previously focused node. See Using focus.

      

   2. In the Node Components press Alt and right-click Input Manipulators, and select the Key Manipulator.

      You use the Key Manipulator to set a node to react to input from a keyboard key.

      

   3. In the Key Manipulator that you created in the previous step set the Logical Key property to the keyboard key to which you want the node to react.

      For example, to close a popup-type window when the user presses the Enter key, set the Logical Key to the Enter key.

      

2. In the Node Components add one of the Key Manipulator triggers.

   For example, in the Node Components press Alt and right-click Triggers, and select Message Trigger > Key Pressed.

   To close a popup-type window when the user presses the Enter key, in the Key Pressed trigger create a Send Scope To Back action.

   To set how the popup-type window closes, use a Scope Sent To Back trigger with an action that sets how the window closes. See Creating a popup-type window.

   

3. (Optional) To set how the Key Pressed trigger handles key press repeats, in the trigger define a trigger condition for the value of the Is Repeat message argument. The Is Repeat message argument indicates whether the key press is a repeat caused by the user holding down a keyboard key.

   For example, if you set a popup-type window to both open and close when the user presses the same keyboard key, in the Key Pressed trigger create a Trigger Condition, and in the condition set:

   • A

     • Type of A to Message argument

     • Message Argument to Is Repeat

   • Operation to =

   • B

     • Type of B to Fixed

     • Fixed Value to disabled

   With this condition you set the trigger to handle the first key press. This way if the application user holds the key down, the popup does not open and close repeatedly.

   

When the user presses the key that you set in the Key Manipulator (Enter), the Key Pressed trigger sets off the action which closes the popup-type window and sets the focus to the previously focused user interface element.

Using the key manipulator in the API

For details, see the KeyManipulator class in the Kanzi Engine API reference.

See also

Handling user input

Using focus

Using the Navigation Manipulator

Using triggers

Tutorial: Move focus in an application