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:
- SCREEN_EVENT_JOG
- SCREEN_EVENT_POINTER
- SCREEN_EVENT_KEYBOARD
- SCREEN_EVENT_GAMEPAD
- SCREEN_EVENT_JOYSTICK
- SCREEN_EVENT_GESTURE
- SCREEN_EVENT_MTOUCH_PRETOUCH
- SCREEN_EVENT_MTOUCH_TOUCH
- SCREEN_EVENT_MTOUCH_MOVE
- SCREEN_EVENT_MTOUCH_RELEASE
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 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
when 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 how 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 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.