Name

XtDestroyWidget — destroy a widget instance. 

Synopsis

void XtDestroyWidget(object)

    Widget object;

Arguments

objectSpecifies the object to be destroyed; may be of class Object or any subclass thereof. 

Description

Most applications simply exit, causing widgets to be destroyed automatically.  XtDestroyWidget destroys widgets explicitly.  It can be used by an application to destroy widgets that are no longer needed.  It can also be used by widgets that need to destroy themselves.  It can be called at any time, including from a callback routine of the widget being destroyed. 

Widget destruction occurs in two phases to prevent dangling references to destroyed widgets. 

In phase one, XtDestroyWidget performs the following:

•If the being_destroyed field of the widget is True, it returns immediately;

•Otherwise, it recursively descends the widget tree and sets the being_destroyed field to True for the widget and all children; and

•It adds the widget to a list of widgets (the destroy list) that should be destroyed when it is safe to do so. 

For entries on the destroy list, if w2 occurs after w1 on the destroy list, then w2 is not a descendant of w1.  (A descendant can be either a normal child or a pop-up child.) 

Phase two 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 two, XtDestroyWidget performs the following on each entry in the destroy list:

•Calls the destroy callback procedures registered on the widget (and all descendants).  The calls happen in reverse order (children callbacks before parent callbacks). 

•If the widget’s parent is a subclass of compositeWidgetClass and if the parent is not being destroyed, XtDestroyWidget calls XtUnmanageChild on the widget and then calls the widget’s parent’s delete_child method. 

•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. 

•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. 

•Calls the Xlib function XDestroyWindow if the widget is realized (that is, has an X window).  The server recursively destroys all descendant windows. 

•Recursively descends the tree and deallocates all pop-up widgets, constraint records, callback lists and, if the widget is a subclass of compositeWidgetClass, children. 

When an application needs to perform additional processing during the destruction of a widget, it should register a destroy callback procedure for the widget.  The destroy callback list is identified by the resource name XtNdestroyCallback. 

The following example adds an application-supplied destroy callback procedure called ClientDestroy with client data to a widget:

XtAddCallback(w, XtNdestroyCallback, ClientDestroy, client_data)

Similarly, the following example removes the application-supplied destroy callback procedure ClientDestroy:

XtRemoveCallback(w, XtNdestroyCallback, ClientDestroy, client_data)

A widget’s windows can be removed from the display while leaving the widget data structures intact by calling XtUnrealizeWidget. 

See Also

XtRemoveAllCallbacks(1), XtRemoveCallback(1), XtUnrealizeWidget(1),
XtCallbackProc(2),
Core(3).