Pen Support

SDL pen event handling. More...

Collaboration diagram for Pen Support:

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

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

Variables
constexpr MouseID	SDL::PEN_MOUSEID = SDL_PEN_MOUSEID
	The MouseID for mouse events simulated with pen input. More...
constexpr TouchID	SDL::PEN_TOUCHID = SDL_PEN_TOUCHID
	The TouchID for touch events simulated with pen input. More...
constexpr PenInputFlags	SDL::PEN_INPUT_DOWN
	pen is pressed down More...
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_1
	button 1 is pressed More...
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_2
	button 2 is pressed More...
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_3
	button 3 is pressed More...
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_4
	button 4 is pressed More...
constexpr PenInputFlags	SDL::PEN_INPUT_BUTTON_5
	button 5 is pressed More...
constexpr PenInputFlags	SDL::PEN_INPUT_ERASER_TIP
	eraser tip is used More...
constexpr PenInputFlags	SDL::PEN_INPUT_IN_PROXIMITY
	pen is in proximity (since SDL 3.4.0) More...
constexpr PenAxis	SDL::PEN_AXIS_PRESSURE
	Pen pressure. Unidirectional: 0 to 1.0. More...
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. More...
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"). More...
constexpr PenAxis	SDL::PEN_AXIS_COUNT = SDL_PEN_AXIS_COUNT
	Total known pen axis types in this version of SDL. More...
constexpr PenDeviceType	SDL::PEN_DEVICE_TYPE_INVALID
	Not a valid pen device. More...
constexpr PenDeviceType	SDL::PEN_DEVICE_TYPE_UNKNOWN
	Don't know specifics of this pen. More...
constexpr PenDeviceType	SDL::PEN_DEVICE_TYPE_DIRECT
	Pen touches display. More...
constexpr PenDeviceType	SDL::PEN_DEVICE_TYPE_INDIRECT
	Pen touches something that isn't the display. More...

Detailed Description

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. 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 = typedef SDL_PenAxis

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 = typedef SDL_PenDeviceType

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 = typedef SDL_PenID

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 = typedef Uint32

Since

This datatype is available since SDL 3.2.0.

Function Documentation

GetPenDeviceType()

PenDeviceType SDL::GetPenDeviceType ( PenID  instance_id )

inline

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, or PEN_DEVICE_TYPE_INVALID on failure; call GetError() for more information.

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

constexpr PenAxis SDL::PEN_AXIS_COUNT = SDL_PEN_AXIS_COUNT

constexpr

This number may grow in future releases!

PEN_AXIS_PRESSURE

constexpr PenAxis SDL::PEN_AXIS_PRESSURE

constexpr

Initial value:

=
  SDL_PEN_AXIS_PRESSURE

PEN_AXIS_ROTATION

constexpr PenAxis SDL::PEN_AXIS_ROTATION = SDL_PEN_AXIS_ROTATION

constexpr

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

PEN_AXIS_TANGENTIAL_PRESSURE

constexpr PenAxis SDL::PEN_AXIS_TANGENTIAL_PRESSURE

constexpr

Initial value:

=
  SDL_PEN_AXIS_TANGENTIAL_PRESSURE

PEN_DEVICE_TYPE_DIRECT

constexpr PenDeviceType SDL::PEN_DEVICE_TYPE_DIRECT

constexpr

Initial value:

=
  SDL_PEN_DEVICE_TYPE_DIRECT

PEN_DEVICE_TYPE_INDIRECT

constexpr PenDeviceType SDL::PEN_DEVICE_TYPE_INDIRECT

constexpr

Initial value:

=
  SDL_PEN_DEVICE_TYPE_INDIRECT

PEN_DEVICE_TYPE_INVALID

constexpr PenDeviceType SDL::PEN_DEVICE_TYPE_INVALID

constexpr

Initial value:

=
  SDL_PEN_DEVICE_TYPE_INVALID

PEN_DEVICE_TYPE_UNKNOWN

constexpr PenDeviceType SDL::PEN_DEVICE_TYPE_UNKNOWN

constexpr

Initial value:

=
  SDL_PEN_DEVICE_TYPE_UNKNOWN

PEN_INPUT_BUTTON_1

constexpr PenInputFlags SDL::PEN_INPUT_BUTTON_1

constexpr

Initial value:

=
  SDL_PEN_INPUT_BUTTON_1

PEN_INPUT_BUTTON_2

constexpr PenInputFlags SDL::PEN_INPUT_BUTTON_2

constexpr

Initial value:

=
  SDL_PEN_INPUT_BUTTON_2

PEN_INPUT_BUTTON_3

constexpr PenInputFlags SDL::PEN_INPUT_BUTTON_3

constexpr

Initial value:

=
  SDL_PEN_INPUT_BUTTON_3

PEN_INPUT_BUTTON_4

constexpr PenInputFlags SDL::PEN_INPUT_BUTTON_4

constexpr

Initial value:

=
  SDL_PEN_INPUT_BUTTON_4

PEN_INPUT_BUTTON_5

constexpr PenInputFlags SDL::PEN_INPUT_BUTTON_5

constexpr

Initial value:

=
  SDL_PEN_INPUT_BUTTON_5

PEN_INPUT_DOWN

constexpr PenInputFlags SDL::PEN_INPUT_DOWN

constexpr

Initial value:

=
  SDL_PEN_INPUT_DOWN

PEN_INPUT_ERASER_TIP

constexpr PenInputFlags SDL::PEN_INPUT_ERASER_TIP

constexpr

Initial value:

=
  SDL_PEN_INPUT_ERASER_TIP

PEN_INPUT_IN_PROXIMITY

constexpr PenInputFlags SDL::PEN_INPUT_IN_PROXIMITY

constexpr

Initial value:

=
  SDL_PEN_INPUT_IN_PROXIMITY

PEN_MOUSEID

constexpr MouseID SDL::PEN_MOUSEID = SDL_PEN_MOUSEID

constexpr

Since

This constant is available since SDL 3.2.0.

PEN_TOUCHID

constexpr TouchID SDL::PEN_TOUCHID = SDL_PEN_TOUCHID

constexpr

Since

This constant is available since SDL 3.2.0.