Input Parent topic: Input

Input Events

Updated: April 19, 2023

Input events can come from different devices, and each has specific properties that pertain to each event type.

Input events are a subset of Screen event types. The following are input events:

In addition to the following properties that are common to all input events, applications must pay attention to specifics of each input event type and handle them accordingly:
SCREEN_PROPERTY_TIMESTAMP
A timestamp of when an input event occurred. Note that Screen uses the realtime clock and not the monotonic clock when calculating the timestamp.
SCREEN_PROPERTY_SEQUENCE_ID
A sequence ID associated with the event. The sequence ID is useful to determine the order in which multitouch input events occurred.
SCREEN_PROPERTY_TYPE
The type of event as defined by the recipient. Once you determine that it's an input event that's been received, you can obtain a handle to the recipient of the input. For example, any of the following can be the focus for the input event:
  • SCREEN_PROPERTY_DISPLAY
  • SCREEN_PROPERTY_WINDOW
  • SCREEN_PROPERTY_SESSION

Keyboard events

Keyboard events can pertain to text entry, navigation, selection, or use of special keys (i.e., keys that have special functions, such as volume up/down).

Properties that are of interest to the application in handling keyboard events are:

SCREEN_PROPERTY_SYM

The output that results from a key being pressed. See sys/keycodes.h.

SCREEN_PROPERTY_FLAGS
Indicator of whether there's logical data that can be used by the application. Use this to determine what sort of input you're receiving from the keyboard. The bits of SCREEN_PROPERTY_FLAGS are set according to Keyboard events. For keyboard events, the following masks are valid:
  • SCREEN_FLAG_KEY_DOWN
  • SCREEN_FLAG_KEY_REPEAT
  • SCREEN_FLAG_SCAN_VALID
  • SCREEN_FLAG_SYM_VALID
  • SCREEN_FLAG_CAP_VALID
SCREEN_PROPERTY_MODIFIERS
Modifiers associated with the keyboard event.
SCREEN_PROPERTY_KEY_CAP
The face value on the key cap that corresponds to the key that was pressed. See sys/keycodes.h.
SCREEN_PROPERTY_SCAN
The scan code (physical key position) associated with the keyboard event. See sys/usbcodes.h.

Pointer events

The recipient of pointer events is based on the position of the cursor on the click of the pointer. That is, input events are focused on the display, window, or session that's active at the position of the cursor when the first pointer event is detected. When there's a click, all subsequent pointer events are sent to the same recipient until the pointer button is released.

Screen automatically draws the cursor so that applications don't have the responsibility of drawing and redrawing the cursor when it moves. The visibility of the cursor can be configured in the graphics.conf by setting the cursor parameter in the display section. The cursor can be configured as always visible, always invisible, or automatically determined by Screen. Screen determines the visibility of the cursor based on the cursor inactivity or if a touch device is attached.

Properties that are of interest to the application in handling pointer events are:

SCREEN_PROPERTY_BUTTONS

A bitmask indicating which buttons of a pointer event are pressed.

The bits of SCREEN_PROPERTY_BUTTONS are set according to Screen mouse button types. An application can determine if the action from a series of pointer events is click, select, move, or drag from the button that was pressed and then released. For example, a click can be tracked by the presence of a left mouse button, then the absence of a left-mouse button within a very short time interval and in relatively the same position.

SCREEN_PROPERTY_FLAGS
Indicator of whether position is relative or absolute. Use this to determine how to calculate the movements of the cursor to establish actions from the user (e.g., click, move, drag, etc.). The bits of SCREEN_PROPERTY_FLAGS are set according to Screen event flags. For pointer events, the following masks are valid:
  • SCREEN_FLAG_DISPLACEMENT_VALID
  • SCREEN_FLAG_POSITION_VALID
  • SCREEN_FLAG_SOURCE_POSITION_VALID
  • SCREEN_FLAG_SIZE_VALID
SCREEN_PROPERTY_POSITION
The x and y positions, in pixels, of the pointer event.
SCREEN_PROPERTY_SOURCE_POSITION
The x and y positions of the pointer event relative to your buffer.
SCREEN_PROPERTY_SIZE
The width and height, in pixels, of the cursor area.
SCREEN_PROPERTY_DISPLACEMENT
The x and y displacement, in pixels, of the cursor since the last event.

Touch events

The focus of touch events is based on the position of each point of contact. Each contact is delivered independently. That is, input events will be focused on the display, window, or session that's active at the position of contact when the first touch event is detected for that contact ID.

A touch event is similar to that of a pointer, except that a touch is direct input (no cursor). That is, there's no position, if there's no touch contact. The support for multitouch (i.e., multiple contacts) is dependent on the support from the hardware. When multi-touch is supported, each contact is handled independently, and touch, move, and release are all separate input events.

Properties that are of interest to the application in handling pointer events are:

SCREEN_PROPERTY_TOUCH_ID

The contact ID associated with the touch event. This ID is useful in identifying the different points of contact for multitouch.

SCREEN_PROPERTY_FLAGS
Indicator of whether there's logical data that can be used by the application. Use this to determine what sort of input you're receiving from the touch device. The bits of SCREEN_PROPERTY_FLAGS are set according to Screen event flags. For pointer events, the following masks are valid:
  • SCREEN_FLAG_POSITION_VALID
  • SCREEN_FLAG_SOURCE_POSITION_VALID
  • SCREEN_FLAG_SIZE_VALID
SCREEN_PROPERTY_POSITION
The x and y positions, in pixels, of the top left corner of the contact area.
SCREEN_PROPERTY_SOURCE_POSITION
The x and y positions, in pixels, of the contact point relative to your buffer.
SCREEN_PROPERTY_SIZE
The width and height, in pixels, of the contact area.
SCREEN_PROPERTY_SOURCE_SIZE
The width and height, in buffer coordinates, of the contact area.
SCREEN_PROPERTY_TOUCH_TYPE
The touch types associated with touch events. Valid touch types are finger or stylus, as defined in Screen touch types.
SCREEN_PROPERTY_TOUCH_PRESSURE
The pressure associated with touch events.
SCREEN_PROPERTY_TOUCH_ORIENTATION
The orientation associated with touch events.

Jog, Joystick, and Gamepad

Joystick and gamepad events can have both analog and button components. Jog events are essentially analog in one direction only (e.g. the wheel of a mouse).

Properties that are of interest to the application in handling jog, joystick, and gamepad events are:

SCREEN_PROPERTY_BUTTONS

A bitmask indicating which buttons of a gamepad event are pressed.

Note that D-pad, A, B, X, Y, Start, Select, Left, and Right are all considered buttons on gamepads. The bits of SCREEN_PROPERTY_BUTTONS are set according to Screen game button types. Screen game button types are used to map buttons from different controllers to a common game control layout. Typically, you'd create a structure to represent your game controller and then map the buttons to one of the bits in the game button enumeration.

SCREEN_PROPERTY_FLAGS
Indicator of whether values are discrete or analog. The bits of SCREEN_PROPERTY_FLAGS are set according to Screen event flags. For jog events, the SCREEN_FLAG_DISPLACEMENT_VALID is valid.
SCREEN_PROPERTY_ANALOG0
The x, y and z values for one analog controller. For analog controllers that do not have three degrees of freedom, only x and y values are valid; z will have a value of 0. This property is applicable to gamepad and joystick events.
SCREEN_PROPERTY_ANALOG1
The x, y, and z values for a second analog controller. For analog controllers that do not have three degrees of freedom, only x and y values are valid; z will have a value of 0. This property is applicable to gamepad events only.
SCREEN_PROPERTY_DISPLACEMENT
The x and y coordinates of events with relative displacement.
SCREEN_PROPERTY_JOG_COUNT
The jog count, a discrete value, associated with the jog event.
SCREEN_PROPERTY_MODIFIERS
A 32-bit integer that conveys two 16-bit values. The higher order set of 16 bits represents the number of participating contacts and the lower order set of 16 bits represents non-participating contacts. Participating contacts refer to the number of contacts that are actively used to calculate the gesture. The non-participating contacts refer to the number of contacts that are detected, but not considered in the determination of the gesture. For more information, see “Multitouch (touch) sessions” section.

Gesture events

Gesture events can be a result of gesture recognition (a series of input events that make up one gesture), or simply, as a gesture event (e.g., from devices that support gestures). In the case of gesture recognition, the gesture event will be sent in place of the series input event. It is possible to get both raw input and gesture events using sessions with the SCREEN_PROPERTY_EVENT session properties.

Properties that are of interest to the application in handling gesture events are:

SCREEN_PROPERTY_FLAGS
Indicator of whether there's logical data that can be used by the application. Use this to determine how to determine what sort of input you're receiving from the touch device. The bits of SCREEN_PROPERTY_FLAGS are set according to Screen event flags. For pointer events, the following masks are valid:
  • SCREEN_FLAG_DISPLACEMENT_VALID
  • SCREEN_FLAG_POSITION_VALID
  • SCREEN_FLAG_SOURCE_POSITION_VALID
  • SCREEN_FLAG_SIZE_VALID
SCREEN_PROPERTY_POSITION
The x and y positions of the gesture relative to the top left corner of your input recipient.
SCREEN_PROPERTY_SIZE
The width and height, in pixels, of the gesture (e.g., size of swipe).
SCREEN_PROPERTY_DISPLACEMENT
The x and y coordinates of events with relative displacement.
SCREEN_PROPERTY_DURATION
The time duration, in nanoseconds, of the gesture event.
SCREEN_PROPERTY_SYM

A symbol that identifies the gesture event.

SCREEN_PROPERTY_SCAN
The scan code that identifies the gesture event.
Parent topic: Input