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 documentthis part of ISO/IEC 19775. 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.

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:

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.