Pen Support

SDL pen event handling. More...

Typedefs
using	SDL::PenID = SDL_PenID
	SDL pen instance IDs.
using	SDL::PenInputFlags = Uint32
	Pen input flags, as reported by various pen events' pen_state field.
using	SDL::PenAxis = SDL_PenAxis
	Pen axis indices.
using	SDL::PenDeviceType = SDL_PenDeviceType
	An enum that describes the type of a pen device.

Functions
PenDeviceType	SDL::GetPenDeviceType (PenID instance_id)
	Get the device type of the given pen.

Variables
constexpr MouseID	SDL::PEN_MOUSEID = SDL_PEN_MOUSEID
	The MouseID for mouse events simulated with pen input.
constexpr TouchID	SDL::PEN_TOUCHID = SDL_PEN_TOUCHID
	The TouchID for touch events simulated with pen input.
constexpr PenInputFlags	SDL::PEN_INPUT_DOWN
	pen is pressed down
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_1
	button 1 is pressed
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_2
	button 2 is pressed
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_3
	button 3 is pressed
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_4
	button 4 is pressed
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_5
	button 5 is pressed
constexpr PenInputFlags	SDL::PEN_INPUT_ERASER_TIP
	eraser tip is used
constexpr PenInputFlags	SDL::PEN_INPUT_IN_PROXIMITY
	pen is in proximity (since SDL 3.4.0)
constexpr PenAxis	SDL::PEN_AXIS_PRESSURE
	Pen pressure. Unidirectional: 0 to 1.0.
constexpr PenAxis	SDL::PEN_AXIS_XTILT = SDL_PEN_AXIS_XTILT
	Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right).
constexpr PenAxis	SDL::PEN_AXIS_YTILT = SDL_PEN_AXIS_YTILT
	Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down).
constexpr PenAxis	SDL::PEN_AXIS_DISTANCE = SDL_PEN_AXIS_DISTANCE
	Pen distance to drawing surface. Unidirectional: 0.0 to 1.0.
constexpr PenAxis	SDL::PEN_AXIS_ROTATION = SDL_PEN_AXIS_ROTATION
	Pen barrel rotation.
constexpr PenAxis	SDL::PEN_AXIS_SLIDER = SDL_PEN_AXIS_SLIDER
	Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0.
constexpr PenAxis	SDL::PEN_AXIS_TANGENTIAL_PRESSURE
	Pressure from squeezing the pen ("barrel pressure").
constexpr PenAxis	SDL::PEN_AXIS_COUNT = SDL_PEN_AXIS_COUNT
	Total known pen axis types in this version of SDL.
constexpr PenDeviceType	SDL::PEN_DEVICE_TYPE_INVALID
	Not a valid pen device.
constexpr PenDeviceType	SDL::PEN_DEVICE_TYPE_UNKNOWN
	Don't know specifics of this pen.
constexpr PenDeviceType	SDL::PEN_DEVICE_TYPE_DIRECT
	Pen touches display.
constexpr PenDeviceType	SDL::PEN_DEVICE_TYPE_INDIRECT
	Pen touches something that isn't the display.

Detailed Description

SDL pen event handling.

SDL provides an API for pressure-sensitive pen (stylus and/or eraser) handling, e.g., for input and drawing tablets or suitably equipped mobile / tablet devices.

To get started with pens, simply handle pen events:

• EVENT_PEN_PROXIMITY_IN, EVENT_PEN_PROXIMITY_OUT (PenProximityEvent)
• EVENT_PEN_DOWN, EVENT_PEN_UP (PenTouchEvent)
• EVENT_PEN_MOTION (PenMotionEvent)
• EVENT_PEN_BUTTON_DOWN, EVENT_PEN_BUTTON_UP (PenButtonEvent)
• EVENT_PEN_AXIS (PenAxisEvent)

Pens may provide more than simple touch input; they might have other axes, such as pressure, tilt, rotation, etc.

When a pen starts providing input, SDL will assign it a unique PenID, which will remain for the life of the process, as long as the pen stays connected. A pen leaving proximity (being taken far enough away from the digitizer tablet that it no longer reponds) and then coming back should fire proximity events, but the PenID should remain consistent. Unplugging the digitizer and reconnecting may cause future input to have a new PenID, as SDL may not know that this is the same hardware.

Please note that various platforms vary wildly in how (and how well) they support pen input. If your pen supports some piece of functionality but SDL doesn't seem to, it might actually be the operating system's fault. For example, some platforms can manage multiple devices at the same time, but others will make any connected pens look like a single logical device, much how all USB mice connected to a computer will move the same system cursor. Other platforms might not support pen buttons, or the distance axis, etc. Very few platforms can even report what functionality the pen supports in the first place, so best practices is to either build UI to let the user configure their pens, or be prepared to handle new functionality for a pen the first time an event is reported.

Typedef Documentation

PenAxis

using SDL::PenAxis = SDL_PenAxis

Pen axis indices.

These are the valid values for the axis field in PenAxisEvent. All axes are either normalised to 0..1 or report a (positive or negative) angle in degrees, with 0.0 representing the centre. Not all pens/backends support all axes: unsupported axes are always zero.

To convert angles for tilt and rotation into vector representation, use sin on the XTILT, YTILT, or ROTATION component, for example:

sin(xtilt * PI_F / 180.0).

Since

This enum is available since SDL 3.2.0.

PenDeviceType

using SDL::PenDeviceType = SDL_PenDeviceType

An enum that describes the type of a pen device.

A "direct" device is a pen that touches a graphic display (like an Apple Pencil on an iPad's screen). "Indirect" devices touch an external tablet surface that is connected to the machine but is not a display (like a lower-end Wacom tablet connected over USB).

Apps may use this information to decide if they should draw a cursor; if the pen is touching the screen directly, a cursor doesn't make sense and can be in the way, but becomes necessary for indirect devices to know where on the display they are interacting.

Since

This enum is available since SDL 3.4.0.

PenID

using SDL::PenID = SDL_PenID

SDL pen instance IDs.

Zero is used to signify an invalid/null device.

These show up in pen events when SDL sees input from them. They remain consistent as long as SDL can recognize a tool to be the same pen; but if a pen's digitizer table is physically detached from the computer, it might get a new ID when reconnected, as SDL won't know it's the same device.

These IDs are only stable within a single run of a program; the next time a program is run, the pen's ID will likely be different, even if the hardware hasn't been disconnected, etc.

Since

This datatype is available since SDL 3.2.0.

PenInputFlags

using SDL::PenInputFlags = Uint32

Pen input flags, as reported by various pen events' pen_state field.

Since

This datatype is available since SDL 3.2.0.

Function Documentation

GetPenDeviceType()

PenDeviceType SDL::GetPenDeviceType ( PenID instance_id )

inline

Get the device type of the given pen.

Many platforms do not supply this information, so an app must always be prepared to get an PEN_DEVICE_TYPE_UNKNOWN result.

Parameters

instance_id

the pen instance ID.

Returns

the device type of the given pen on success.

Exceptions

Error

on failure.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.4.0.

Variable Documentation

PEN_AXIS_COUNT

PenAxis SDL::PEN_AXIS_COUNT = SDL_PEN_AXIS_COUNT

constexpr

Total known pen axis types in this version of SDL.

This number may grow in future releases!

PEN_AXIS_PRESSURE

PenAxis SDL::PEN_AXIS_PRESSURE

constexpr

Initial value:

                                  =
SDL_PEN_AXIS_PRESSURE

Pen pressure. Unidirectional: 0 to 1.0.

PEN_AXIS_ROTATION

PenAxis SDL::PEN_AXIS_ROTATION = SDL_PEN_AXIS_ROTATION

constexpr

Pen barrel rotation.

Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down).

PEN_AXIS_TANGENTIAL_PRESSURE

PenAxis SDL::PEN_AXIS_TANGENTIAL_PRESSURE

constexpr

Initial value:

                                             =
SDL_PEN_AXIS_TANGENTIAL_PRESSURE

Pressure from squeezing the pen ("barrel pressure").

PEN_DEVICE_TYPE_DIRECT

PenDeviceType SDL::PEN_DEVICE_TYPE_DIRECT

constexpr

Initial value:

                                             =
SDL_PEN_DEVICE_TYPE_DIRECT

Pen touches display.

PEN_DEVICE_TYPE_INDIRECT

PenDeviceType SDL::PEN_DEVICE_TYPE_INDIRECT

constexpr

Initial value:

                                               =
SDL_PEN_DEVICE_TYPE_INDIRECT

Pen touches something that isn't the display.

PEN_DEVICE_TYPE_INVALID

PenDeviceType SDL::PEN_DEVICE_TYPE_INVALID

constexpr

Initial value:

                                              =
SDL_PEN_DEVICE_TYPE_INVALID

Not a valid pen device.

PEN_DEVICE_TYPE_UNKNOWN

PenDeviceType SDL::PEN_DEVICE_TYPE_UNKNOWN

constexpr

Initial value:

                                              =
SDL_PEN_DEVICE_TYPE_UNKNOWN

Don't know specifics of this pen.

PEN_INPUT_BUTTON_1

PenInputFlags SDL::PEN_INPUT_BUTTON_1

constexpr

Initial value:

                                         =
SDL_PEN_INPUT_BUTTON_1

button 1 is pressed

PEN_INPUT_BUTTON_2

PenInputFlags SDL::PEN_INPUT_BUTTON_2

constexpr

Initial value:

                                         =
SDL_PEN_INPUT_BUTTON_2

button 2 is pressed

PEN_INPUT_BUTTON_3

PenInputFlags SDL::PEN_INPUT_BUTTON_3

constexpr

Initial value:

                                         =
SDL_PEN_INPUT_BUTTON_3

button 3 is pressed

PEN_INPUT_BUTTON_4

PenInputFlags SDL::PEN_INPUT_BUTTON_4

constexpr

Initial value:

                                         =
SDL_PEN_INPUT_BUTTON_4

button 4 is pressed

PEN_INPUT_BUTTON_5

PenInputFlags SDL::PEN_INPUT_BUTTON_5

constexpr

Initial value:

                                         =
SDL_PEN_INPUT_BUTTON_5

button 5 is pressed

PEN_INPUT_DOWN

PenInputFlags SDL::PEN_INPUT_DOWN

constexpr

Initial value:

                                     =
SDL_PEN_INPUT_DOWN

pen is pressed down

PEN_INPUT_ERASER_TIP

PenInputFlags SDL::PEN_INPUT_ERASER_TIP

constexpr

Initial value:

                                           =
SDL_PEN_INPUT_ERASER_TIP

eraser tip is used

PEN_INPUT_IN_PROXIMITY

PenInputFlags SDL::PEN_INPUT_IN_PROXIMITY

constexpr

Initial value:

                                             =
SDL_PEN_INPUT_IN_PROXIMITY

pen is in proximity (since SDL 3.4.0)

PEN_MOUSEID

MouseID SDL::PEN_MOUSEID = SDL_PEN_MOUSEID

constexpr

The MouseID for mouse events simulated with pen input.

Since

This constant is available since SDL 3.2.0.

PEN_TOUCHID

TouchID SDL::PEN_TOUCHID = SDL_PEN_TOUCHID

constexpr

The TouchID for touch events simulated with pen input.

Since

This constant is available since SDL 3.2.0.