XtCreateWidget(3)

🎀 NAME 🎀

XtCreateWidget, XtVaCreateWidget, XtCreateManagedWidget, XtVaCreateManagedWidget, XtDestroyWidget — create and destroy widgets 💖 (yes bestie, this is the page from the XT FUNCTIONS chapter, and we're making widgets fr fr)

---

✨ SYNTAX ✨

First things first, you gotta bring in the header, no cap:

#include <X11/Intrinsic.h>

Then the whole squad, exactly as they are:

Widget XtCreateWidget(const char *name, WidgetClass widget_class, Widget
       parent, ArgList args, Cardinal num_args);

Widget XtVaCreateWidget(const char *name, WidgetClass widget_class,
       Widget parent, ...);

Widget XtCreateManagedWidget(const char *name, WidgetClass widget_class,
       Widget parent, ArgList args, Cardinal num_args);

Widget XtVaCreateManagedWidget(const char *name, WidgetClass
       widget_class, Widget parent, ...);

void XtDestroyWidget(Widget w);

---

🫶 ARGUMENTS 🫶

• args — the argument list that overrides the resource defaults. it's giving "here's my custom vibe" energy 💅
• name — the resource name for the widget you're creating. it's used for retrieving resources, so do not name it the same as any other widget that's a child of the same parent. like, that's the one rule okay 😭
• num_args — how many arguments are in that argument list, bestie. count them. fr.
• parent — the parent widget. every main character needs a supporting cast 🫶
• w — the widget. just... the widget.
• widget_class — the widget class pointer for the widget you're creating 👑
• ... — the variable argument list that overrides the resource defaults. the mysterious one. the icon ✨

---

💅 DESCRIPTION 💅

So XtCreateWidget does a whole bunch of the boilerplate widget-creation chores for you, and honestly? it ate. here's the rundown:

• It checks whether the class_initialize procedure has been called for this class and for all its superclasses, and if not, it calls the ones that are necessary in a superclass-to-subclass order. like, hierarchy first, always 💅
• It allocates memory for the widget instance.
• If the parent is a subclass of constraintWidgetClass, it allocates memory for the parent's constraints and stores the address of that memory into the constraints field.
• It initializes the core nonresource data fields — for example, parent and visible.
• It initializes the resource fields — for example, background_pixel — by using the resource lists specified for this class and all its superclasses.
• If the parent is a subclass of constraintWidgetClass, it initializes the resource fields of the constraints record by using the constraint resource list specified for the parent's class and all superclasses up to constraintWidgetClass.
• It calls the initialize procedures for the widget, starting at the Core initialize procedure and going on down to the widget's own initialize procedure.
• If the parent is a subclass of compositeWidgetClass, it puts the widget into its parent's children list by calling its parent's insert_child procedure. for further information, see Section 3.5.
• If the parent is a subclass of constraintWidgetClass, it calls the constraint initialize procedures, starting at constraintWidgetClass and going on down to the parent's constraint initialize procedure.

Note that you can figure out the number of arguments in an argument list by using the XtNumber macro. for further information, see Section 11.1. (macro girlies stay winning ✨)

XtCreateManagedWidget is the convenience routine bestie — it calls XtCreateWidget and XtManageChild. one call, two jobs, slay 🎀

---

💀 XtDestroyWidget — the destroy arc 💀

XtDestroyWidget is the only method of destroying a widget, including widgets that need to destroy themselves. it can be called at any time, including from an application callback routine of the widget that's being destroyed. and the reason it can do that is a two-phase destroy process, because dangling references to destroyed widgets are NOT the vibe. we simply do not do those.

Phase one 🌸

In phase one, XtDestroyWidget does this:

• If the being_destroyed field of the widget is True, it returns immediately. bye 👋
• It recursively descends the widget tree and sets the being_destroyed field to True for the widget and all its children.
• It adds the widget to a list of widgets (the destroy list) that should be destroyed when it's safe to do so.

Entries on the destroy list satisfy the invariant that if w2 occurs after w1 on the destroy list, then w2 is not a descendent of w1. (and just so we're clear, "a descendant" here refers to both normal and pop-up children, okay? both kinds 😌)

Phase two 🌈

Phase two happens when all procedures that should execute as a result of the current event have been called — that includes all procedures registered with the event and translation managers — that is, when the current invocation of XtDispatchEvent is about to return, or immediately if you're not in XtDispatchEvent.

In phase two, XtDestroyWidget performs the following on each entry in the destroy list:

• It calls the destroy callback procedures registered on the widget (and all descendants) in post-order — meaning it calls children callbacks before parent callbacks. children first, always 🫶
• If the widget's parent is a subclass of compositeWidgetClass and if the parent is not being destroyed, it calls XtUnmanageChild on the widget and then calls the widget's parent's delete_child procedure (see Section 3.4).
• If the widget's parent is a subclass of constraintWidgetClass, it calls the constraint destroy procedure for the parent, then the parent's superclass, until finally it calls the constraint destroy procedure for constraintWidgetClass.
• It calls the destroy methods for the widget (and all descendants) in post-order. for each such widget, it calls the destroy procedure declared in the widget class, then the destroy procedure declared in its superclass, until finally it calls the destroy procedure declared in the Core class record.
• It calls XDestroyWindow if the widget is realized (that is, it has an X window). and the server recursively destroys all descendant windows. cascade queen 💅
• It recursively descends the tree and deallocates all pop-up widgets, constraint records, callback lists and, if the widget is a subclass of compositeWidgetClass, children.

---

🌈 SEE ALSO 🌈

• XtAppCreateShell(3), XtCreatePopupShell(3)
• X Toolkit Intrinsics - C Language Interface
• Xlib - C Language X Interface

---

okay that's the whole page bestie, go forth and build widgets responsibly 💖✨

X Version 11 · libXt 1.3.1 · and yeah, this was XtCreateWidget(3) the whole time 🎀🦋 no cap, mwah 💅