Device: Input

The input device provides access to a pointing device, a scrolling device, a keyboard device, and four gamepads.

Notes

The native cursor of the host system should be hidden.

Ports

Pointer active

Reading from this port will return the value 0xff if a pointer device is active, otherwise the value returned will be zero.

A pointer device is active only while the system is receiving an up-to-date pointer position. If the pointing device is a touchscreen, it will only be active while receiving touch input.

Pointer buttons

Reading from this port will return a byte representing the held state of up to eight buttons associated with a pointing device. Each bit of the value represents a single pointer button, as per the following table. A bit is set only if the associated button is currently being held down.

If the pointing device is a right-handed computer mouse, the primary button is the left mouse button, the secondary button is the right mouse button, and the tertiary button is the middle mouse button. If the pointing device is a left-handed computer mouse, the primary and secondary buttons are switched.

If the pointing device is a touchscreen, the primary button is held only while the screen is receiving touch input.

The button mappings for other classes of pointing device are implementation defined. The mapping of auxillary bits to pointer buttons is implementation defined.

Horizontal scroll

Reading from this port will return the signed cumulative horizontal scroll distance, and then will reset the value to zero. The value increases as the scroll device is scrolled rightward, and decreases as the scroll device is scrolled leftward, saturating at bounds. Scrolling rightward is the action which would slide the screen contents to the left, revealing content to the right. The initial value of this port is zero.

The unit of the returned value is equal to one increment of the scroll device. If the scroll device is continuous, the scroll unit is implementation defined.

Vertical scroll

Reading from this port will return the signed cumulative vertical scroll distance, and then will reset the value to zero. The value increases as the scroll device is scrolled downward, and decreases as the scroll device is scrolled upward, saturating at bounds. Scrolling downward is the action which would slide the screen contents to upward, revealing content below. The initial value of this port is zero.

The unit of the returned value is equal to one increment of the scroll device. If the scroll device is continuous, the scroll unit is implementation defined.

Horizontal position

Reading from this port group will perform a cached read, returning the signed horizontal position of the screen pixel beneath the pointer. The horizontal position of the left-most screen pixel is zero, and increases to the right. The initial value of this port is zero.

Vertical position

Reading from this port group will perform a cached read, returning the signed vertical position of the screen pixel beneath the pointer. The vertical position of the top-most screen pixel is zero, and increases downwards. The initial value of this port is zero.

Keyboard active

Reading from this port will return the byte 0xff if a keyboard device is active, or a zero byte if no keyboard device is active.

A keyboard device is active only while it is ready to receive input. If the keyboard device is a software keyboard, it will be active while it is visible.

Writing to this port will change the visibility of an existing software keyboard. Writing a non-zero value will request that the software keyboard be made visible, and writing a zero value will request that the software keyboard be hidden.

Character input

This port is associated with a first-in first-out byte queue. When a character of text is received from the keyboard device, and if the queue has sufficient remaining capacity, the value of that character will be pushed to the end of the queue as a UTF-8 encoded bytestring. The character will not be modified by the control modifier. The length of the queue is implementation defined.

Reading a byte from this port will return the value of the byte at the front of the queue, and then will remove that byte from the queue. If the queue is empty, the value zero will be returned.

Writing a byte to this port will empty the queue.

When the keyboard button labeled enter or return is pressed, the value of the received character will be the new line character 0x0A, and not the carriage return character 0x0D.

Navigation controls

The value of this port is a byte representing the held state of eight navigation controls. Each bit of this value is associated with a single navigation control, as per the following table. The bit associated with a particular navigation control is set only if the button corresponding with that navigation control is currently held down.

The up, down, left, and right controls will modify the focused user interface element, or will focus the next user interface element in the chosen direction. The confirm control will perform the action associated with the focused user interface element. The cancel control will end the current action, or will exit from the current user interface mode. The next and previous controls will focus the next or previous user interface element in order.

If a keyboard device is available, the up, down, left, and right arrow keys will map to the corresponding navigation controls, the enter or return key will map to the confirm navigation control, the escape key will map to the cancel navigation control, the tab key will map to the next navigation control, and the tab key when the shift modifier is being held will map to the previous navigation control.

If a gamepad is connected to the first gamepad port, the up, down, left, and right gamepad buttons will map to the corresponding navigation controls, the A gamepad button will map to the confirm navigation control, and the B gamepad button will map to the cancel navigation control.

Modifier keys

The value of this port is a byte representing the held state of the modifier keys on a keyboard. Each bit of this value is associated with a single modifier key, as per the following table. The bit associated with a particular modifier key is set only if that modifier key is currently held down.

The mapping of auxillary bits to keyboard modifiers is implementation defined.

Gamepad

The value of each gamepad port is a byte representing the held state of up to eight buttons associated with a gamepad connected to this system. Each bit of this value is associated with a single gamepad button, as per the following table. The bit associated with a particular button is set only if that button is currently held down.

The A button maps to the affirmative gamepad button, the B button maps to the negative gamepad button, the X button maps to the primary action gamepad button, and the Y button maps to the secondary action gamepad button.

On a PlayStation-style gamepad, the cross button is the affirmative button, the circle button is the negative button, the square button is the primary action button, and the triangle button is the secondary action button.

On an XBox-style or Nintendo-style gamepad, the A button is the affirmative button, the B button is the negative button, the X button is the primary action button, and the Y button is the secondary action button.

If a gamepad has an analog stick, the up, down, left, and right directions of the analog stick will map to the corresponding directional buttons.

Each available gamepad will be connected to a gamepad port in order starting from the first gamepad port.

System wake

This device will send a wake event to the system device when the active state of the pointer device or keyboard device changes, or when a pointer button or gamepad button or navigation control or modifier key is pressed or released, or when a character is received from the keyboard device, or when the pointer moves to a new position while the pointer device is active, or when the horizontal or vertical distance travelled by the scroll device changes.