Keyboard2D

The Keyboard2D node enables you to design interactive keyboards that are able to trigger key events in the system.You can use these keyboards as input interfaces in 2D and 3D.

Platform support

This node is supported on XR-Windows platform only.

Features

The Keyboard2D offers functions for:

• Designing a keyboard layout

• Implementing multiple modes, such as shift and numbers.

• Customizing keyboard and buttons aspect and behavior.

• Triggering key events.

Designing keyboard layout

Each keyboard is based on a grid layout.

The grid is defined by columns, rows, and cellSize. The offset field is used to position the grid relatively to the upper left corner of the keyboard area and can be used to define a margin. Each button will be mapped on the grid using its key_KeyName and buttonPosition field.

Look and feel

Keyboard2D is highly configurable in terms of visual presentation. Use buttonStyle to select among available button styles then set the backgroundColor.

You can customize the appearance of buttons with associated field values.

Drawing button using shape

As an alternative to using the default button styles, you can define a custom button by setting buttonStyle to shape and using the shape field of type dstring.

This method uses a cardinal spline to define the shape. The shape is defined by:

• A set of 2D points in the UV space (0 0) to (1 1). The curve will pass through all these points. Please observe UV space has (0 0) at left top corner.

• A tension that determines the smoothness of the curve. A value of 0 corresponds to a segmented line. In general, values between 0 and 1 are fine; however, it's possible to use any value.

In this example image, the tension of the shape is set to: {tension=0.1}{points=0.5 0,1 1,0 1}

Defining keys

The field keys are used to list all the keys that will be placed on a keyboard. The number of keys should be equal to or less than the number of cells in the grid.

The node will automatically create a set of fields to manage evey key.

Support for modes

Keyboard2D supports multiple modes. This means that while keeping the same layout, the keyboard buttons may vary their use.

You can define an arbitrary list of modes to serve different scenarios, such as lower/upper casing, numeric keys.

The Keyboard2D node will create mode-related fields for every key.

Button customization

Every key has a set of associated fields, such as key_KeyName and buttonSize.

Placing and sizing

In order to design the keyboard layout, each key needs to be placed opportunely.

Use the key_KeyName and buttonPosition to place a button in the grid.

The key_KeyName and buttonSize when set to a value different to 1 1, can be used to span buttons over multiple grid cells.

For example, in the case when you want to implement a space bar, a shift, or an enter buttons.

Button behavior and aspect

Buttons have a set of fields that defines their state and behavior.

The key_KeyName/buttonMode is used to discriminate between push and toggle key buttons. Typically, toggles are used for modifiers, such as shift or control. The Keyboard2D node, like all the 2D nodes in the XR library, support a single point of interaction.

A button can be used to trigger a mode change by assigning its key_KeyName/modeCode to a defined mode. When the button is down, the mode is requested. When the button is released, the mode is removed.

The state of the button can be observed directly using the key_KeyName/buttonState.

Modes

Every key has a set of dedicated fields for each defined mode, such as key_KeyName/ModeName/displayedText. The fields are used to customize the behavior and the aspect of the button for the corresponding mode.

A keyboard button can show different text (key_KeyName/ModeName/displayedText) or image (key_KeyName/ModeName/displayedImage) in any mode. The text is shown, only if the image is not set.

The key_KeyName/ModeName/keyCode represents the actual key code sent down and up when pressing on the button. See InputEventInjector node for the keyCode to use for special keys, such as back, shift, or return.

Due to this approach, the displayed text can differ from the sent key code and allows the keyboard to support any character available in unicode.

You can set keyCode to empty to disable a button in a particular mode.

Switching modes

Changing the state for specific buttons that have a key_KeyName/modeCode set, can trigger the request to switch the mode.

The current mode is shown by the field selectedMode, which can also be used to manage the switch from outside.

Additional modes

Additional modes are also available.

Example scenario

Consider the case where a user has defined the following modes: [base, shift, alt, altshift, control] and specific buttons have been set up to trigger shift, control, and alt modes.

• If shift is the current mode and alt button is pressed, the selectedMode will switch to altshift.

• If instead, control is pressed, when shift is the current mode, the state goes to control.

This mechanism works only if the additional modes are set up in such a way that their names formed by the required modes are sorted alphabetically.

Key Event management

You can use Keyboard2D as a standalone node or integrated with an InputEventInjector node.

The keyDown and keyUp fields can track any button interaction that is happening on the keyboard. At any interaction, the fields will contain the keyCode assigned to the key in the currently selected mode for the interacted button.

When the inputEventInjectorNode field is set, the events will automatically feed values and enter the system like actual keyboards events.

Touch or mouse interaction

Due to the specificity of the Keyboard2D node, two interaction modes (interactionMode field) have been implemented.

• mouse interaction mode is designed for mouse and VR hand interaction.

• touch interaction mode is designed to interact with touch monitors.

Keyboard2D fields

These are the fields for Keyboard2D node. Only the node-specific fields are indicated, not fields obtained by inheritance.

Field inheritance: NodeBase > RectBase2D > Keyboard2D