hpux man page for xtdestroywidget

XtDestroyWidget()														 XtDestroyWidget()

Name
  XtDestroyWidget - 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.

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 proce-
  dure 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 XtDestroyWidget().

  XtDestroyWidget() can 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 wid-
  get'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:

  o  If the being_destroyed field of the widget is True, it returns immediately.

  o  Recursively descends the widget tree and sets the being_destroyed field to True for the widget and all normal and popup children.

  o  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 regis-
  tered 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:

  o  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).

  o  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).

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

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

  o  Calls  XDestroyWindow()  if  the  specified  widget  is realized (that is, has an X window).  The server recursively destroys all normal
     descendant windows.

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

See Also
  XtCloseDisplay(1), XtDestroyApplicationContext(1), XtUnrealizeWidget(1).

Xt - Widget Lifecycle														 XtDestroyWidget()