Input device

This specification describes the input device of the Bedrock computer system.

Ports

Horizontal coordinate

Reading from this port group will perform an atomic read, returning the horizontal coordinate of the pointer position.

Vertical coordinate

Reading from this port group will perform an atomic read, returning the vertical coordinate of the pointer position.

Horizontal scroll

Reading from this port will return the horizontal scroll distance, and then will reset the horizontal scroll distance to zero.

Vertical scroll

Reading from this port will return the vertical scroll distance, and then will reset the vertical scroll distance to zero.

Pointer active

A pointer device is active while the pointer is within the screen bounds, or while a pointer button that was pressed while within the screen bounds is still being held down. A touchscreen is only active while touched.

Reading from this port will return 0xFF if a pointer device is active, otherwise it will return zero.

Pointer buttons

Reading from this port will return a button list representing the list of pointer buttons that are held down, mapped as per the following table:

If the pointer device is a right-handed mouse, primary is the left-mouse button, secondary is the right-mouse button, and tertiary is the middle-mouse button. For a left-handed mouse, primary and secondary will be reversed. For a touchscreen, primary is the touchscreen surface.

Keyboard active

A keyboard device is active only while it is available to receive input. An on-screen keyboard is only active while visible.

Reading from this port will return 0xFF if a keyboard device is active, otherwise it will return zero.

Writing a non-zero value to this port will request that an existing software keyboard be made available, and writing a zero value will request that all software keyboards be hidden.

Character

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

Writing to this port will remove all bytes from the character queue.

Modifiers

Reading from this port will return a button list representing the list of keyboard modifiers that are held down, mapped as per the following table:

Navigation

Reading from this port will return a button list representing the list of navigation controls that are held down, mapped as per the following table:

The up, down, left, and right arrow keys of the keyboard device map to the corresponding directional controls. The enter key maps to confirm, the escape key maps to cancel, and the tab key maps to previous while the shift key is held, next otherwise.

The up, down, left, and right buttons of the first gamepad device map to the corresponding directional controls. The A button maps to confirm, the B button maps to cancel, the left bumper maps to previous, and the right bumper maps to next.

Gamepad

Each gamepad port is associated with a gamepad device, in order from least-recently to most-recently connected.

Reading from a gamepad port will return a button list representing the list of buttons on the associated gamepad that are held down, mapped as per the following table:

An analogue stick or directional pad will map to the up, down, left, and right buttons.

The confirm button is the affirmative face button, cancel is the negative face button, primary is the primary action face button, and secondary is the secondary action face button. These map to the controllers of popular consoles as follows:

Data structures

Pointer position

The pointer position is a two-dimensional point that references the position of the screen pixel directly beneath the current position of the pointer. The pointer position shares a coordinate space with the Bedrock screen device.

The pointer position has a horizontal coordinate that increases rightwards, and a vertical coordinate that increases downwards. Each coordinate is stored as a signed 16-bit integer. The origin is the top-left pixel of the Bedrock screen device.

The pointer position should be updated only while the pointer is active.

Scroll distance

A scroll distance is a signed 8-bit value that represents the cumulative distance scrolled along either the horizontal or the vertical scroll axis. The initial distance value for each scroll axis is zero.

The horizontal scroll distance increases when scrolling rightwards (the action that would slide content leftwards) and decreases when scrolling leftwards, and the vertical scroll distance increases when scrolling downwards (the action that would slide content upwards) and decreases when scrolling upwards. Distance values saturate at bounds.

The unit of scroll distance is one screen pixel. The number of pixels that should be scrolled for every line of a line-based scrolling device is implementation defined.

Button list

A button list is an 8-bit value representing a set of held buttons. Each bit of the value corresponds with a different device button, with each bit being set only if the corresponding button is held down.

Character queue

The character queue is a first-in first-out byte queue used to buffer received characters.

When a character is received from a keyboard device, that character is converted to a UTF-8 encoded byte sequence and then pushed byte-by-byte to the back of the character queue if there is sufficient capacity. A newline character is represented by the byte 0x0A on all platforms. The maximum length of the queue is implementation defined.

Implementation

Cursor icons

Any cursor icons should be hidden while the pointer device is within the screen bounds, so that programs can render their own cursor.

Wake

This device will send a wake request to the system device when any of the following events occur:

• A pointer button is pressed or released
• A modifier key is pressed or released
• A navigation control is pressed or released
• A gamepad button is pressed or released
• A character is received from the keyboard device
• The pointer active state changes
• The keyboard active state changes
• The pointer position changes
• The horizontal or vertical scroll distance changes