SDL_PenProximityEvent(3type)

💖 SDL_PenProximityEvent 💖

okay bestie, welcome to the SDL3 DATATYPES corner of the manual, where we're talking about SDL_PenProximityEvent — that's the pressure-sensitive pen proximity event structure, aka event.pproximity.* ✨

---

✨ NAME ✨

SDL_PenProximityEvent — the pressure-sensitive pen proximity event structure, living its best life at event.pproximity.* 🖊️

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_events.h>

typedef struct SDL_PenProximityEvent
{
    SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */
    Uint32 reserved;
    Uint64 timestamp;   /**< In nanoseconds, populated using SDL_GetTicksNS() */
    SDL_WindowID windowID; /**< The window with pen focus, if any */
    SDL_PenID which;        /**< The pen instance id */
    SDL_PenInputFlags pen_state;   /**< Complete pen input state at time of event (added in 3.4.16). */
    SDL_PenDeviceType device_type; /**< the device type of the pen, if known (added in 3.4.18). */
} SDL_PenProximityEvent;

no cap, that's the whole struct. let's break it down 🫶

---

🦋 DESCRIPTION 🦋

so here's the vibe: when a pen becomes visible to the system — like, it's close enough to a tablet, etc — SDL is gonna send an SDL_EVENT_PEN_PROXIMITY_IN event with the new pen's ID. 🎀

that ID stays valid until the pen leaves proximity again (removed from the tablet's area, tablet got unplugged, etc). and if the same pen reenters proximity later? it gets a brand new ID. new era, new identity, main character reboot 💅

lowkey important: "proximity" here just means "close enough for the tablet to know the tool is there." the pen actually touching down and lifting off while it never leaves the area is a whole different situation — that's handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP. don't mix them up bestie 😭

also, not all platforms have a window associated with the pen during proximity events. some of them wait until motion/button/etc events to offer up that info. so like, it's giving "sometimes the windowID is just not there yet" 🙈

---

🌈 AVAILABILITY 🌈

this struct has been available since SDL 3.2.0. iconic behavior honestly 👑

---

and that's the whole page!! ✨ written up in the Simple Directmedia Layer docs, SDL version 3.4.18, dated with the same SDL 3.4.18 stamp on the footer — mwah, tysm for reading, go forth and track your pens 🖊️💜