XtDestroyWi(3x) — HP-UX ANSI C A.09.00

NAME

XtDestroyWidget − destroy a widget instance.

Synopsis

void XtDestroyWidget(object)

Widget object;

Inputs

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

Description

XtDestroyWidget() 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 automatically. Applications that create and destroy widgets dynamically should call XtDestoyWidget(). XtDestoyWidget() 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. 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 widgets 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 immediately.

•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 normal 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 callbacks before parent callbacks).

•If the widget is not a popup child and 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.3).

•If the widget is not a popup child and the widget’s parent is a subclass 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 CoreClassPart 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 realized popup descendants, deallocates all popup descendants, constraint records, callback lists, and if the widget’s class is a subclass of compositeWidgetClass, children. XtCreateWidget() and XtConvertAndStore() automatically register XtCallbackReleaseCacheRef() 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.

Museum