Handling user input

You can set how and which elements in your application react to user input. In Kanzi, to handle user input you can:

• Enable gesture recognition for nodes. See Using input manipulators.
• Define which nodes receive user input. See Defining which node receives user input.
• Set the size of the input area of nodes. See Setting the size of the input area.
• Set how and which nodes react to keyboard input. See Handling keyboard input.

For these Kanzi nodes you do not have to create input manipulators manually, because they handle input by default:

• Button nodes. See Using the Button nodes.
• Toggle Button nodes. See Using the Toggle Button nodes.
• List Box nodes. See List Box nodes.
• List Box Item Container prefabs. See Using the List Box Item Container prefabs.
• Scroll View nodes. See Using the Scroll View nodes.
• Slider nodes. See Using the Slider nodes.

Use triggers and actions to create interactions based on user input. See Using triggers.

Using input manipulators

Kanzi provides low and high-level access to input:

• The high-level system provides input in terms of gestures, such as click, pan, pinch, and so on. It is recommended to use the high-level system to bind gestures to the UI components or application functionality.
• The low-level input system reports raw touch events as they happen in nodes.

Kanzi provides input manipulators to enable gesture recognition for nodes in your Kanzi project. You can assign the manipulators through the API.

Kanzi provides these input manipulators:

• Use the click manipulator to enable users to click or tap nodes in your Kanzi application. See Using the click manipulator.
• Use the long-press manipulator to enable users to long-press nodes in your Kanzi application. See Using the long-press manipulator.
• Use the multi-click manipulator to enable users to double-click or double-tap nodes in your Kanzi application. See Using the multi-click manipulator.
• Use the drag-and-drop manipulator to enable users to drag and drop nodes in your Kanzi application. See Using the drag-and-drop manipulator.
• Use the pan manipulator to enable users to move nodes in your Kanzi application. See Using the pan manipulator.
• Use the pinch manipulator to enable users to zoom and rotate nodes in your Kanzi application. See Using the pinch manipulator.

InputManipulator is the base class for manipulators, and functions such as ClickManipulator::create and PanManipulator::create create input manipulators responsible for the corresponding gesture recognition.

When you create an input manipulator, to recognize the gesture, attach it to the node with Node::addInputManipulator. This attaches all the children of the node too.

Attached manipulator generates messages in response to user actions. Each manipulator uses messages to report different events during gesture recognition, such as PanManipulator::StartedMessage, PanManipulator::MovedMessage, PanManipulator::FinishedMessage for the pan manipulator and so on.

Defining which node receives user input

Since only one node receives user input at a time, when creating your user interface take special care how your application handles user input. For example, define whether a click is handled by the node in the front or by the one behind it.

Kanzi uses hit testing to determine the nodes that receive input. In practice, hit testing projects a ray from the camera towards the 3D scene based on the screen coordinates of the input event.

By default hit testing is disabled. To enable hit testing for a node, add the Hit Testable property, and enable it.

The first node from the Camera node whose bounding box is intersected and has the Hit Testable property enabled, receives the input, consumes the event and generates set actions, such as sending a click message.

For example, if you place two boxes so that BoxFront is in front of BoxRear and occludes it completely:

• BoxFront always receives the input when:
  • BoxFront Hit Testable property is enabled
  • BoxRear Hit Testable property is enabled
• BoxRear receives the input even though it is occluded by BoxFront when:
  • BoxFront Hit Testable property is disabled
  • BoxRear Hit Testable property is enabled

Setting the size of the input area

When you want to change the input area of a node use the Hit Testable Container property, which takes into consideration the layout size rather than the bounding volume of the node. Hit testing of all nodes is by default based on their layout size.

To define the size of the input area, add and enable the Hit Testable Container property in the node. If the node is not a button, you also have to add and enable the Hit Testable property.

For example, if you want to set the area of a button to be larger than the mesh in the button:

1. Create a Button 3D, add and enable the Hit Testable Container property, and add an action to the Button: Click message.
2. Create a Box inside the Button 3D, and add and set the Layout Height, Layout Width, and Layout Depth properties to the area where you want your button to respond to clicks or taps.
   The Button 3D receives the click input from the area set by the Layout Height, Layout Width, and Layout Depth properties of the Box inside the Button 3D.

See also

Handling keyboard input

Using the click manipulator

Using the long-press manipulator

Using the multi-click manipulator

Using the drag-and-drop manipulator

Using the pan manipulator

Using the pinch manipulator

Using the Button nodes

Using the Toggle Button nodes

List Box nodes

Using the List Box Item Container prefabs

Using the Scroll View nodes

Using the Slider nodes

Using triggers

Open topic with navigation