Extensible 3D (X3D)
Part 1: Architecture and base components

21 Key device sensor component

# 21.1 Introduction

## 21.1.1 Name

The name of this component is "KeyDeviceSensor". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.3.4 Component statement).

## 21.1.2 Overview

This clause describes the Key Device Sensor component of this document. This includes how individual keystrokes and a series of keystrokes are inserted into an X3D world. Table 21.1 provides links to the major topics in this clause.

Table 21.1 — Topics

21.1 Introduction 21.1.1 Name 21.1.2 Overview 21.2 Concepts 21.3 Abstract types 21.3.1 X3DKeyDeviceSensorNode 21.4 Node reference 21.4.1 KeySensor 21.4.2 StringSensor 21.5 Support levels Table 21.1 — Topics Table 21.2 — Action key values Table 21.3 — Key Device Sensor component support levels

# 21.2 Concepts

The following node types are keydevice sensors:

- KeySensor
- StringSensor

KeySensors generate an event whenever the state of a key associated with the physical key device changes while the KeySensor is active. The identification of the key whose state has changed is returned by the event.

StringSensors generate an event whenever the termination string specified for the StringSensor is identified. The UTF-8 characters preceding the termination string are returned by the event. StringSensors also generate interim events whenever the string under construction changes. This allows prompting of the string during construction.

One keyboard-style key device is assumed to be available either as a physical device or through emulation whenever the sensor component is supported. For a key device to generate input to a key device sensor, the key device shall be active. Key devices are active when:

1. The X3D world has focus in the supporting user interface; and
2. The key device sensor has its isActive field set to TRUE.

The isActive event generated by a change of the state of the isActive field can be used for prompting.

A key device sensor is enabled when its enabled field is set to TRUE. This causes the isActive field of the keydevice sensor to be set to TRUE. Also, any other key device sensor which may be active will be sent an enabled event with value FALSE. Only one key device sensor may be active at a time

# 21.3 Abstract types

## 21.3.1 X3DKeyDeviceSensorNode

    X3DKeyDeviceSensorNode : X3DSensorNode {
      SFString [in,out] description ""
      SFBool   [in,out] enabled     TRUE
      SFNode   [in,out] metadata    NULL [X3DMetadataObject]
      SFBool   [out]    isActive
    }

This abstract node type is the base type for all sensor node types that operate using key devices.

# 21.4 Node reference

## 21.4.1 KeySensor

    KeySensor : X3DKeyDeviceSensorNode {
      SFString [in,out] description      ""
      SFBool   [in,out] enabled          TRUE
      SFNode   [in,out] metadata         NULL [X3DMetadataObject]
      SFInt32  [out]    actionKeyPress
      SFInt32  [out]    actionKeyRelease
      SFBool   [out]    altKey
      SFBool   [out]    controlKey
      SFBool   [out]    isActive
      SFString [out]    keyPress
      SFString [out]    keyRelease
      SFBool   [out]    shiftKey
    }

A KeySensor node generates events when the user presses keys on the keyboard. A KeySensor node can be enabled or disabled by sending it an enabled event with a value of TRUE or FALSE. If the KeySensor node is disabled, it does not track keyboard input or send events.

keyPress and keyRelease events are generated as keys which produce characters are pressed and released on the keyboard. The value of these events is a string of length 1 containing the single UTF-8 character associated with the key pressed. The set of UTF-8 characters that can be generated will vary between different keyboards and different implementations.

actionKeyPress and actionKeyRelease events are generated as 'action' keys are pressed and released on the keyboard. The value of these events are in Table 21.2:

Table 21.2 — Action key values

KEY | VALUE | KEY | VALUE | KEY | VALUE
--- | --- | --- | --- | --- | ---
HOME | 13 | END | 14 | PGUP | 15
PGDN | 16 | UP | 17 | DOWN | 18
LEFT | 19 | RIGHT | 20 | F1-F12 | 1-12

shiftKey, controlKey, and altKey events are generated as each of the shift, control, and alt keys on the keyboard is respectively pressed and released. Their value is TRUE when the key is pressed and FALSE when the key is released.

When a key is pressed, the KeySensor sends an isActive event with value TRUE. Once the key is released, the KeySensor sends an isActive event with value FALSE.

The KeySensor is not affected by its position in the transformation hierarchy.

Recommended default key mappings for navigation are described in Annex G Recommended navigation behaviours.

## 21.4.2 StringSensor

    StringSensor  : X3DKeyDeviceSensorNode {
      SFBool   [in,out] deletionAllowed TRUE
      SFString [in,out] description     ""
      SFBool   [in,out] enabled         TRUE
      SFNode   [in,out] metadata        NULL [X3DMetadataObject]
      SFString [out]    enteredText
      SFString [out]    finalText
      SFBool   [out]    isActive
    }

A StringSensor node generates events as the user presses keys on the keyboard. A StringSensor node can be enabled or disabled by sending it an enabled event with a value of TRUE or FALSE. If the StringSensor node is disabled, it does not track keyboard input or send events.

enteredText events are generated as keys which produce characters are pressed on the keyboard. The value of this event is the UTF-8 string entered including the latest character struck. The set of UTF-8 characters that can be generated will vary between different keyboards and different implementations.

If a deletionAllowed has value TRUE, the previously entered character in the enteredText is removed when the X3D browser-recognized value for deleting the preceding character of a string is entered. Typically, this value is defined by the local operating system. If deletionAllowed has value FALSE, characters may only be added to the string; deletion of characters shall not be allowed. Should the X3D browser-recognized value for deleting the preceding character is entered, it shall be ignored.

The finalText event is generated whenever the X3D browser-recognized value for terminating a string is entered. Typically, this value is defined by the local operating system. When this recognition occurs, the finalText field generates an event with value equal to that of enteredText. After the finalText field event has been generated, the enteredText field is set to the empty string but no event is generated.

When the user begins typing, the StringSensor sends an isActive event with value TRUE. When the string is terminated, the StringSensor sends an isActive event with value FALSE.

The StringSensor is not affected by its position in the transformation hierarchy.

# 21.5 Support levels

The Key Device Sensor component provides 2 levels of support as specified in Table 21.3.

Table 21.3 — Key device sensor component support levels

Level | Prerequisites | Nodes/Features | Support
--- | --- | --- | ---
1 | Core 1 |  |
|  | X3DKeyDeviceSensorNode (abstract) | n/a
|  | KeySensor | All fields fully supported.
2 | Core 1 |  |
|  | All Level 1 Key Device Sensor nodes | All fields as supported in Level 1.
|  | StringSensor | All fields fully supported.