Touch Support

SDL offers touch input, on platforms that support it. More...

Classes
struct	SDL::Finger
	Data about a single finger in a multitouch event. More...

Typedefs
using	SDL::FingerRaw = SDL_Finger
	Alias to raw representation for Finger.
using	SDL::TouchID = SDL_TouchID
	A unique ID for a touch device.
using	SDL::FingerID = SDL_FingerID
	A unique ID for a single finger on a touch device.
using	SDL::TouchDeviceType = SDL_TouchDeviceType
	An enum that describes the type of a touch device.

Functions
OwnArray< TouchID >	SDL::GetTouchDevices ()
	Get a list of registered touch devices.
const char *	SDL::GetTouchDeviceName (TouchID touchID)
	Get the touch device name as reported from the driver.
TouchDeviceType	SDL::GetTouchDeviceType (TouchID touchID)
	Get the type of the given touch device.
OwnArray< Finger * >	SDL::GetTouchFingers (TouchID touchID)
	Get a list of active fingers for a given touch device.

Variables
constexpr TouchDeviceType	SDL::TOUCH_DEVICE_INVALID
	TOUCH_DEVICE_INVALID.
constexpr TouchDeviceType	SDL::TOUCH_DEVICE_DIRECT
	touch screen with window-relative coordinates
constexpr TouchDeviceType	SDL::TOUCH_DEVICE_INDIRECT_ABSOLUTE
	trackpad with absolute device coordinates
constexpr TouchDeviceType	SDL::TOUCH_DEVICE_INDIRECT_RELATIVE
	trackpad with screen cursor-relative coordinates
constexpr MouseID	SDL::TOUCH_MOUSEID = SDL_TOUCH_MOUSEID
	The MouseID for mouse events simulated with touch input.
constexpr TouchID	SDL::MOUSE_TOUCHID = SDL_MOUSE_TOUCHID
	The TouchID for touch events simulated with mouse input.

Detailed Description

SDL offers touch input, on platforms that support it.

It can manage multiple touch devices and track multiple fingers on those devices.

Touches are mostly dealt with through the event system, in the EVENT_FINGER_DOWN, EVENT_FINGER_MOTION, and EVENT_FINGER_UP events, but there are also functions to query for hardware details, etc.

The touch system, by default, will also send virtual mouse events; this can be useful for making a some desktop apps work on a phone without significant changes. For apps that care about mouse and touch input separately, they should ignore mouse events that have a which field of TOUCH_MOUSEID.

Typedef Documentation

FingerID

using SDL::FingerID = SDL_FingerID

A unique ID for a single finger on a touch device.

This ID is valid for the time the finger (stylus, etc) is touching and will be unique for all fingers currently in contact, so this ID tracks the lifetime of a single continuous touch. This value may represent an index, a pointer, or some other unique ID, depending on the platform.

The value 0 is an invalid ID.

Since

This datatype is available since SDL 3.2.0.

TouchDeviceType

using SDL::TouchDeviceType = SDL_TouchDeviceType

An enum that describes the type of a touch device.

Since

This enum is available since SDL 3.2.0.

TouchID

using SDL::TouchID = SDL_TouchID

A unique ID for a touch device.

This ID is valid for the time the device is connected to the system, and is never reused for the lifetime of the application.

The value 0 is an invalid ID.

Since

This datatype is available since SDL 3.2.0.

Function Documentation

GetTouchDeviceName()

const char * SDL::GetTouchDeviceName ( TouchID touchID )

inline

Get the touch device name as reported from the driver.

Parameters

touchID

the touch device instance ID.

Returns

touch device name on success.

Exceptions

Error

on failure.

Since

This function is available since SDL 3.2.0.

GetTouchDevices()

OwnArray< TouchID > SDL::GetTouchDevices ( )

inline

Get a list of registered touch devices.

On some platforms SDL first sees the touch device if it was actually used. Therefore the returned list might be empty, although devices are available. After using all devices at least once the number will be correct.

Returns

a 0 terminated array of touch device IDs or nullptr on failure; call GetError() for more information.

Since

This function is available since SDL 3.2.0.

GetTouchDeviceType()

TouchDeviceType SDL::GetTouchDeviceType ( TouchID touchID )

inline

Get the type of the given touch device.

Parameters

touchID

the ID of a touch device.

Returns

touch device type.

Since

This function is available since SDL 3.2.0.

GetTouchFingers()

OwnArray< Finger * > SDL::GetTouchFingers ( TouchID touchID )

inline

Get a list of active fingers for a given touch device.

Parameters

touchID

the ID of a touch device.

Returns

a nullptr terminated array of Finger pointers or nullptr on failure; call GetError() for more information.

Since

This function is available since SDL 3.2.0.

Variable Documentation

MOUSE_TOUCHID

TouchID SDL::MOUSE_TOUCHID = SDL_MOUSE_TOUCHID

constexpr

The TouchID for touch events simulated with mouse input.

Since

This constant is available since SDL 3.2.0.

TOUCH_DEVICE_DIRECT

TouchDeviceType SDL::TOUCH_DEVICE_DIRECT

constexpr

Initial value:

                                            =
SDL_TOUCH_DEVICE_DIRECT

touch screen with window-relative coordinates

TOUCH_DEVICE_INDIRECT_ABSOLUTE

TouchDeviceType SDL::TOUCH_DEVICE_INDIRECT_ABSOLUTE

constexpr

Initial value:

                                                       =
SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE

trackpad with absolute device coordinates

TOUCH_DEVICE_INDIRECT_RELATIVE

TouchDeviceType SDL::TOUCH_DEVICE_INDIRECT_RELATIVE

constexpr

Initial value:

                                                       =
SDL_TOUCH_DEVICE_INDIRECT_RELATIVE

trackpad with screen cursor-relative coordinates

TOUCH_DEVICE_INVALID

TouchDeviceType SDL::TOUCH_DEVICE_INVALID

constexpr

Initial value:

                                             =
SDL_TOUCH_DEVICE_INVALID

TOUCH_DEVICE_INVALID.

TOUCH_MOUSEID

MouseID SDL::TOUCH_MOUSEID = SDL_TOUCH_MOUSEID

constexpr

The MouseID for mouse events simulated with touch input.

Since

This constant is available since SDL 3.2.0.