XtDestroyWidget()XtDestroyWidget()NameXtDestroyWidget - destroy a widget instance.
Synopsis
void XtDestroyWidget(object)
Widget object;
Inputs
object Specifies the object to be destroyed; may be of class Object
or any subclass thereof.
DescriptionXtDestroyWidget() destroys object and all of its normal and popup
descendants. It frees all resources associated with that widget and
its descendants, and calls the Xlib function XDestroyWindow() to
destroy the windows (if any) of the affected objects. The details this
procedure are explained in the "Algorithm" section below.
Usage
Most applications simply exit, causing widgets to be destroyed automat‐
ically. Applications that create and destroy widgets dynamically
should call XtDestroyWidget().
XtDestroyWidget() can be used by widgets that need to destroy them‐
selves. It can be called at any time, including from a callback rou‐
tine of the widget being destroyed.
When an application needs to perform additional processing during the
destruction of a widget, it should register a callback procedure on the
XtNdestroyCallback list of the widget.
Applications that use multiple displays and want to destroy all the
widgets on one of them can simply call XtCloseDisplay(). Applications
that use multiple application contexts and want to destroy all the wid‐
gets in one of them can call XtDestroyApplicationContext(). A widget's
windows can be destroyed without destroying the widget data structures
by calling XtUnrealizeWidget().
Algorithm
Widget destruction occurs in two phases to prevent dangling references
to destroyed widgets.
In phase 1, XtDestroyWidget() performs the following:
· If the being_destroyed field of the widget is True, it returns imme‐
diately.
· Recursively descends the widget tree and sets the being_destroyed
field to True for the widget and all normal and popup children.
· Adds the widget to a list of widgets (the destroy list) that should
be destroyed when it is 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, either nor‐
mal or popup, of w1.
Phase 2 occurs when all procedures that should execute as a result of
the current event have been called, including all procedures registered
with the event and translation managers, that is, when the current
invocation of XtDispatchEvent() is about to return, or immediately if
not in XtDispatchEvent().
In phase 2, XtDestroyWidget() performs the following on each entry in
the destroy list in the order specified:
· Calls the destroy callback procedures registered on the widget and
all normal and popup descendants in postorder (it calls child call‐
backs before parent callbacks).
· If the widget is not a popup child and the widget's parent is a sub‐
class 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.3).
· If the widget is not a popup child and the widget's parent is a sub‐
class of constraintWidgetClass, it calls the ConstraintClassPart
destroy procedure for the parent, then for the parent's superclass,
until finally it calls the ConstraintClassPart destroy procedure for
constraintWidgetClass.
· Calls the destroy procedures for the widget and all normal and popup
descendants in postorder. For each such widget, it calls the Core‐
ClassPart 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 Object class record.
· Calls XDestroyWindow() if the specified widget is realized (that is,
has an X window). The server recursively destroys all normal
descendant windows.
· Recursively descends the tree and destroys the windows for all real‐
ized popup descendants, deallocates all popup descendants, con‐
straint records, callback lists, and if the widget's class is a sub‐
class of compositeWidgetClass, children.
XtCreateWidget() and XtConvertAndStore() automatically register XtCall‐
backReleaseCacheRef() as a destroy callback on all widgets that use
reference-counted resources from the conversion cache. In this way,
destroying a widget also invokes the appropriate resource destructors
when the reference count of a converted resource reaches 0.
See AlsoXtCloseDisplay(1), XtDestroyApplicationContext(1), XtUnrealizeWid‐
get(1).
Xt - Widget Lifecycle XtDestroyWidget()
