# CategoryPen

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:

- [SDL_EVENT_PEN_PROXIMITY_IN](SDL_EVENT_PEN_PROXIMITY_IN),
  [SDL_EVENT_PEN_PROXIMITY_OUT](SDL_EVENT_PEN_PROXIMITY_OUT)
  ([SDL_PenProximityEvent](SDL_PenProximityEvent))
- [SDL_EVENT_PEN_DOWN](SDL_EVENT_PEN_DOWN),
  [SDL_EVENT_PEN_UP](SDL_EVENT_PEN_UP)
  ([SDL_PenTouchEvent](SDL_PenTouchEvent))
- [SDL_EVENT_PEN_MOTION](SDL_EVENT_PEN_MOTION)
  ([SDL_PenMotionEvent](SDL_PenMotionEvent))
- [SDL_EVENT_PEN_BUTTON_DOWN](SDL_EVENT_PEN_BUTTON_DOWN),
  [SDL_EVENT_PEN_BUTTON_UP](SDL_EVENT_PEN_BUTTON_UP)
  ([SDL_PenButtonEvent](SDL_PenButtonEvent))
- [SDL_EVENT_PEN_AXIS](SDL_EVENT_PEN_AXIS)
  ([SDL_PenAxisEvent](SDL_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
[SDL_PenID](SDL_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 [SDL_PenID](SDL_PenID)
should remain consistent. Unplugging the digitizer and reconnecting may
cause future input to have a new [SDL_PenID](SDL_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
like 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.

<!-- END CATEGORY DOCUMENTATION -->

## Functions

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPen, CategoryAPIFunction -->
- [SDL_GetPenDeviceType](SDL_GetPenDeviceType)
<!-- END CATEGORY LIST -->

## Datatypes

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPen, CategoryAPIDatatype -->
- [SDL_PenID](SDL_PenID)
- [SDL_PenInputFlags](SDL_PenInputFlags)
<!-- END CATEGORY LIST -->

## Structs

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPen, CategoryAPIStruct -->
- [SDL_PenAxisEvent](SDL_PenAxisEvent)
- [SDL_PenButtonEvent](SDL_PenButtonEvent)
- [SDL_PenMotionEvent](SDL_PenMotionEvent)
- [SDL_PenProximityEvent](SDL_PenProximityEvent)
- [SDL_PenTouchEvent](SDL_PenTouchEvent)
<!-- END CATEGORY LIST -->

## Enums

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPen, CategoryAPIEnum -->
- [SDL_PenAxis](SDL_PenAxis)
- [SDL_PenDeviceType](SDL_PenDeviceType)
<!-- END CATEGORY LIST -->

## Macros

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryPen, CategoryAPIMacro -->
- [SDL_PEN_MOUSEID](SDL_PEN_MOUSEID)
- [SDL_PEN_TOUCHID](SDL_PEN_TOUCHID)
<!-- END CATEGORY LIST -->


----
[CategoryAPICategory](CategoryAPICategory)


