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()