Panel Graphics Hot Zones

These routines define interactive touch zones on a panel surface. You call XPLMAccumulateTouchZone during your drawing callback to declare rectangular regions that respond to mouse clicks or touches. Each zone can either fire an X-Plane command automatically or deliver raw touch events to a callback you register with XPLMAvionicsSetTouchEventHandler.

XPLMTouchZone

enum

This enumeration specifies how a touch zone responds to user interaction.

Name	Value	Description
xplm_TouchZone_Nothing	0	The zone is registered but takes no action when touched.
xplm_TouchZone_Command	1	The zone fires an XPLMCommandRef when touched (begin on mouse-down, end on mouse-up).
xplm_TouchZone_Identifier	2	The zone delivers touch events to the callback registered via XPLMAvionicsSetTouchEventHandler, identified by the zone's identifier field.

XPLMTouchEvent_f

callback

Your touch event callback is invoked when the user interacts with a touch zone whose type is xplm_TouchZone_Identifier. You receive the zone's identifier, the mouse status, the current position, the delta from the initial click point, and the mouse button involved.

typedef void (* XPLMTouchEvent_f)(
                         int                  identifier,
                         XPLMMouseStatus      status,
                         int                  x,
                         int                  y,
                         int                  dx,
                         int                  dy,
                         int                  button,
                         void *               ref
                    );

XPLMTouchZoneSpec_t

struct

XPLMTouchZoneSpec_t describes a single interactive touch zone on the panel. Pass a pointer to this struct to XPLMAccumulateTouchZone during your drawing callback. The structure may be expanded in future SDKs - always set structSize to the size of your structure in bytes.

typedef struct {
     int                       structSize;
     XPLMTouchZone             type;
     XPLMCommandRef            command;
     int                       identifier;
     int                       left;
     int                       top;
     int                       right;
     int                       bottom;
} XPLMTouchZoneSpec_t;

XPLMAccumulateTouchZone

function

This function registers a touch zone for the current frame. Call this during your avionics drawing callback each frame for every interactive region on your panel. Zones registered later take priority over earlier ones when they overlap.

Returns true if the zone is currently being clicked or held by the user, false otherwise. You can use this to provide visual feedback (for example, drawing a button in its pressed state).

XPLM_API int        XPLMAccumulateTouchZone(
                         XPLMTouchZoneSpec_t * inSpec
                    );

XPLMAvionicsSetTouchEventHandler

function

This function registers a callback to receive touch events for zones of type xplm_TouchZone_Identifier on a specific avionics device. When the user interacts with an identifier-type zone, your callback is invoked with the zone's identifier and the mouse event details.

avionic: the avionics device handle (from XPLMRegisterAvionicsCallbacksEx or XPLMCreateAvionicsEx).
handler: your XPLMTouchEvent_f callback.
ref: a reference pointer passed through to your callback.

XPLM_API void       XPLMAvionicsSetTouchEventHandler(
                         XPLMAvionicsID       avionic,
                         XPLMTouchEvent_f     handler,    /* Can be NULL */
                         void *               ref
                    );

XPLMWindowSetTouchEventHandler

function

XPLM_API void       XPLMWindowSetTouchEventHandler(
                         XPLMWindowID         window,
                         XPLMTouchEvent_f     handler,    /* Can be NULL */
                         void *               ref
                    );