Joystick, gamepad, and jog sessions

Updated: May 27, 2022

Joystick, gamepad, and jog sessions are created with the types SCREEN_EVENT_JOYSTICK, SCREEN_EVENT_GAMEPAD, and SCREEN_EVENT_JOG, respectively.

The following session properties are applicable to all these types of sessions:

SCREEN_PROPERTY_ACCELERATION
A set of six integers that represent the linear coefficients for x and y, the quadratic coefficients for x and y, and the minimum and maximum velocity.
SCREEN_PROPERTY_SPEED
The speed for the horizontal and vertical directions for the input device (similar to mouse sensitivity). The speed is given as the ratio between the number of pixels the cursor moves on the display and how far the device is physically moved.
SCREEN_PROPERTY_GESTURE_PARAMETERS
The minimum and maximum distance, in units produced by speed and acceleration, for swipes. This property controls the amount of displacement allowed before a tap becomes a swipe and a threshold displacement, at which point a gesture becomes multiple gestures.
SCREEN_PROPERTY_IDLE_TIMEOUT
The time used to distinguish between a tap, a double tap, and a hold and tap gestures. For example, one touch followed by a release with no further touches within the SCREEN_PROPERTY_IDLE_TIMEOUT period is considered a tap. A touch, release, touch and release again in the same area within the SCREEN_PROPERTY_IDLE_TIMEOUT period is considered a double tap. A hold and tap gesture is when one finger touches and holds while another finger taps within the SCREEN_PROPERTY_IDLE_TIMEOUT period.

Modes

You can set a joystick, gamepad, and jog session's SCREEN_PROPERTY_MODE to one of the following:

SCREEN_INPUT_MODE_RAW
Used when you want minimal filtering. Whatever the device gives, is what your session gets. This is the default mode for these types of sessions.
SCREEN_INPUT_MODE_POINTER

Used in a similar fashion to the navigation mode. The displacement is converted into a pointer event. In this mode, all the pointer movements are clipped to the input region (defined by SCREEN_PROPERTY_SIZE and SCREEN_PROPERTY_POSITION of the session) of your session. It's not recommended that you use this mode if you have other pointer devices on the same system because the interactions can become quite complicated. When in pointer mode, you don't get joystick events. The pointer session or window would instead get those events.

For example, if you have a joystick session in pointer mode and you have both a pointer device, such as a mouse, and a joystick connected to your system. If the mouse is already outside of your joystick session region and the joystick is used, then the joystick can be used to move the cursor back into the region of the joystick session. Once the cursor is within the region of the joystick session, the joystick can't be used to move the cursor outside of the joystick session region.

A cursor will appear only if you're in SCREEN_INPUT_MODE_POINTER mode. While in this mode, the session can control the speed and acceleration of the pointer. The cursor disappears once you exit this mode, or if this session is destroyed. A cursor would remain however, if you have another pointer device on the system.

SCREEN_INPUT_MODE_GESTURE

All input events are converted to SCREEN_EVENT_GESTURE events. A displacement is generated and this displacement is converted into a gesture.

The properties SCREEN_PROPERTY_GESTURE_PARAMETERS and SCREEN_PROPERTY_IDLE_TIMEOUT are used to control how the touch events are converted to gestures.

The converted gesture can be retrieved from the SCREEN_PROPERTY_SCAN property of the SCREEN_EVENT_GESTURE event. The gestures that can be detected are defined by Screen gesture types. Once your application determines the gesture received, it can act accordingly.