XtInsertEventTypeHandler(3)

💖 XtInsertEventTypeHandler(3) 💖

okay bestie, gather round, because we're diving into the XT FUNCTIONS section of your friendly neighborhood X Toolkit Intrinsics library and it's giving extremely niche but also kind of iconic?? This is the page for extension event handling, and yes, it's a lot, but you're a main character and you can handle it. ✨

---

🌸 NAME 🌸

XtInsertEventTypeHandler, XtRemoveEventTypeHandler, XtRegisterExtensionSelector, XtSetEventDispatcher, XtDispatchEventToWidget — extension event handling 🦋

---

🎀 SYNTAX 🎀

#include <X11/Intrinsic.h>

void XtInsertEventTypeHandler(Widget widget, int event_type, XtPointer
       select_data, XtEventHandler proc, XtPointer client_data,
       XtListPosition position);

void XtRemoveEventTypeHandler(Widget widget, int event_type, XtPointer
       select_data, XtEventHandler proc, XtPointer client_data);

void XtRegisterExtensionSelector(Display* display, int min_event_type,
       int max_event_type, XtExtensionSelectProc proc, XtPointer
       client_data);

XtEventDispatchProc XtSetEventDispatcher(Display* display, int
       event_type, XtEventDispatchProc proc);

Boolean XtDispatchEventToWidget(Widget widget, XEvent* event);

like, five whole functions, no cap. 💅

---

💜 ARGUMENTS 💜

• widget — bestie this is the widget the event handler is for. It must be of class Core or any subclass of Core, no exceptions, that's the vibe check right there. 👑
• event_type — the event type. that's it, that's the whole thing. ✨
• select_data — the data that gets used to select or deselect events from the server. lowkey important, highkey load-bearing. 🌸
• proc — the proc. yes really, that's the description. iconic minimalism fr fr. 🎀
• client_data — extra data that gets passed along to the event handler. a little gift for your handler, if you will. 🫶
• position — tells us when this handler gets called compared to the other handlers you already registered. order matters, bestie, always. ⭐
• display — the display. (the X display, not your phone screen, we're being technical here 😭)
• min_event_type, max_event_type — the range of event types for this extension. it's giving "we own this whole range" energy. 🌈
• event — a pointer to the event that's about to be dispatched. 👑

---

✨ DESCRIPTION ✨

okay so, let's go function by function because there's a LOT here and we're not skipping a single crumb. 💖

🦋 XtInsertEventTypeHandler 🦋

This one registers a procedure with the dispatch mechanism. That procedure is gonna get called when an event matching the specified event_type is dispatched to the specified widget. simple enough, right? right. slay.

Now here's where it gets spicy. If event_type is one of the core X protocol events, then select_data must be a pointer to a value of type EventMask, indicating the event mask used to select for the desired event. That event mask gets included in the value returned by XtBuildEventMask. And if the widget is realized, XtInsertEventTypeHandler calls XSelectInput if necessary. 👀

Specifying NULL for select_data is equivalent to specifying a pointer to an event mask containing 0. This is similar to the XtInsertRawEventHandler function. cute, right?

If event_type specifies an extension event type, then the semantics of the data pointed to by select_data are defined by the extension selector registered for the specified event type. so basically, not our problem, that's the extension's whole deal.

In either case, the Intrinsics are not required to copy the data pointed to by select_data, so the caller must ensure that it remains valid as long as the event handler remains registered with this value of select_data. bestie please do not let that memory die on us, I'm begging 🙈

The position argument lets the client control the order in which event handlers registered for the same event type get invoked. If the client does not care about the order, it should normally specify XtListTail, which registers this event handler after any previously registered handlers for this event type. easy, default to the tail, done. 💅

🌸 XtRemoveEventTypeHandler 🌸

This one unregisters an event handler that was registered with XtInsertEventTypeHandler for the specified event type. The request is ignored if client_data does not match the value given when the handler was registered. so like, if the data doesn't match, nothing happens. ghosted. 💀

If event_type specifies one of the core X protocol events, select_data must be a pointer to a value of type EventMask, indicating the mask to be used to deselect for the appropriate event. If the widget is realized, XtRemoveEventTypeHandler calls XSelectInput if necessary. Specifying NULL for select_data is equivalent to specifying a pointer to an event mask containing 0. This is similar to the XtRemoveRawEventHandler function.

If event_type specifies an extension event type, then the semantics of the data pointed to by select_data are defined by the extension selector registered for the specified event type. (same deal as before, we hand it off 🫶)

🎀 XtRegisterExtensionSelector 🎀

This function registers a procedure to arrange for the delivery of extension events to widgets. very "let me handle the logistics" of it all.

If min_event_type and max_event_type match the parameters to a previous call to XtRegisterExtensionSelector for the same display, the proc and client_data replace the previously registered values. Replacement era. ✨

BUT. If the range specified by min_event_type and max_event_type overlaps the range of the parameters to a previous call for the same display in any other way, an error results. no overlap allowed, bestie, this is a strict boundary situation. 🚫

⭐ XtSetEventDispatcher ⭐

This one registers the event dispatcher procedure specified by proc for events with the type event_type. The previously registered dispatcher — or the default dispatcher if there was no previously registered dispatcher — is returned. so you get the old one back, like a little trade. 🤝

If proc is NULL, the default procedure is restored for the specified type. reset to factory settings, love that for us. 💖

In the future, when XtDispatchEvent is called with an event of event_type, the specified proc (or the default dispatcher) will be invoked to determine a widget at which to dispatch the event. future you says thanks. 🔮

🌈 XtDispatchEventToWidget 🌈

This function scans the list of registered event handlers for the specified widget and calls each handler that has been registered for the specified event type, subject to the continue_to_dispatch value returned by each handler.

The Intrinsics behave as if event handlers were registered at the head of the list for Expose, NoExpose, GraphicsExpose, and VisibilityNotify events, to invoke the widget's expose procedure according to the exposure compression rules, and to update the widget's visible field if visible_interest is True. These internal event handlers never set continue_to_dispatch to False. periodt. 💅

XtDispatchEventToWidget returns True if any event handler was called and False otherwise. that's the whole return situation, no notes. 👑

---

👑 SEE ALSO 👑

• XtGetKeyboardFocusWidget(3)
• X Toolkit Intrinsics - C Language Interface
• Xlib - C Language Interface

---

and that's the whole page, bestie!! you absolutely ate this one. 🍓

this was X Version 11, from libXt 1.3.1 — written by the X legends themselves, mwah 💋, and honestly? iconic of them. bye bestie, go forth and dispatch those events responsibly!! 💖✨🦋🎀