XtRealizeWidget()														 XtRealizeWidget()

Name
  XtRealizeWidget - realize a widget instance.

Synopsis
  void XtRealizeWidget(w)
	 Widget w;

Inputs
  w	    Specifies the widget to be realized.  Must be of class Core or any subclass thereof.

Description
  XtRealizeWidget()  creates windows for the specified widget and all of its descendants.  If the specified widget is already realized, XtRe-
  alizeWidget() simply returns.  When a widget is first created, no X window is created along with it.	Realizing a widget is  the  term  for
  creating this window, and no widget can appear on the screen until it is realized.  The reason widget creation and window creation are han-
  dled separately is one of efficiency: when an interface is first created, there is an initial process of negotiating geometry and assigning
  a layout to each widget.  If the widgets had windows at this point, the geometry negotiation would require many XConfigureWindow() calls to
  the X server, which would significantly slow down application startup time.

  The "Algorithm" section below describes the procedure followed by XtRealizeWidget().

Usage
  Most applications will call XtRealizeWidget() once just prior to calling XtAppMainLoop() to process events.  The argument to	XtRealizeWid-
  get()  is  usually  the top-level widget returned from XtAppInitialize().  If more widgets are subsequently created, they do not need to be
  realized because when a widget is created as the child of a realized widget, it is automatically realized.  Popup shells are also automati-
  cally realized, if necessary, when they are popped up.

  You can test whether a widget is realized with XtIsRealized().  Until a widget is realized, certain functions will not operate as expected.
  XtWindow(), for example will not return a valid window if called with an unrealized widget.

  You can unrealize a widget (destroy its window) but leave the widget structure intact with XtUnrealizeWidget().

Algorithm
  If the widget is already realized, XtRealizeWidget() simply returns.	Otherwise it performs the following:

  o  Binds all action names in the widget's translation table to procedures.

  o  Makes a postorder traversal of the widget tree rooted at the specified widget and calls each non-NULL  change_managed()  method  of  all
     composite widgets that have one or more managed children.

  o  Constructs  an  XSetWindowAttributes  structure  filled  in with information derived from the Core widget fields and calls the realize()
     method for the widget, which adds any widget-specific attributes and creates the X window.

  o  If the widget is not a subclass of compositeWidgetClass, XtRealizeWidget() returns; otherwise it continues and performs the following:

     -	Descends recursively to each of the widget's managed children and calls the realize() methods.	Primitive  widgets  that  instantiate
	children are responsible for realizing those children themselves.

     -	Maps  all  of  the  managed  children  windows that have mapped_when_managed True.  If a widget is managed but mapped_when_managed is
	False, the widget is allocated visual space but is not displayed.

  If the widget is a top-level shell widget (that is, it has no parent), and mapped_when_managed is True, XtRealizeWidget() maps  the  widget
  window.

  XtCreateWidget(), XtVaCreateWidget(), XtRealizeWidget(), XtManageChildren(), XtUnmanageChildren(), XtUnrealizeWidget(), XtSetMappedWhenMan-
  aged(), and XtDestroyWidget() maintain the following invariants:

  o  If a composite widget is realized, then all its managed children are realized.

  o  If a composite widget is realized, then all its managed children that have mapped_when_managed True are mapped.

  All Intrinsics functions and all widget routines should accept either realized or  unrealized  widgets.   When  calling  the	realize()  or
  change_managed()  methods  for children of a composite widget, XtRealizeWidget() calls the procedures in reverse order of appearance in the
  CompositePart children list.	By default, this ordering of the realize procedures will result in the stacking order of  any  newly  created
  subwindows being top-to-bottom in the order of appearance on the list, and the most recently created child will be at the bottom.

See Also
  XtIsRealized(1), XtUnrealizeWidget(1),
  realize(4).

Xt - Widget Lifecycle														 XtRealizeWidget()