XtRealizeWidget()XtRealizeWidget()NameXtRealizeWidget - 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.
DescriptionXtRealizeWidget() creates windows for the specified widget and all of
its descendants. If the specified widget is already realized, XtReal‐
izeWidget() simply returns. When a widget is first created, no X win‐
dow is created along with it. Realizing a widget is the term for cre‐
ating this window, and no widget can appear on the screen until it is
realized. The reason widget creation and window creation are handled
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 XtRe‐
alizeWidget().
Usage
Most applications will call XtRealizeWidget() once just prior to call‐
ing 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 real‐
ized because when a widget is created as the child of a realized wid‐
get, it is automatically realized. Popup shells are also automatically
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:
· Binds all action names in the widget's translation table to proce‐
dures.
· Makes a postorder traversal of the widget tree rooted at the speci‐
fied widget and calls each non-NULL change_managed() method of all
composite widgets that have one or more managed children.
· Constructs an XSetWindowAttributes structure filled in with informa‐
tion 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.
· If the widget is not a subclass of compositeWidgetClass, XtReal‐
izeWidget() returns; otherwise it continues and performs the follow‐
ing:
- 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 win‐
dow.
XtCreateWidget(), XtVaCreateWidget(), XtRealizeWidget(), XtManageChil‐
dren(), XtUnmanageChildren(), XtUnrealizeWidget(), XtSetMappedWhenMan‐
aged(), and XtDestroyWidget() maintain the following invariants:
· If a composite widget is realized, then all its managed children are
realized.
· 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, XtReal‐
izeWidget() 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 sub‐
windows being top-to-bottom in the order of appearance on the list, and
the most recently created child will be at the bottom.
See AlsoXtIsRealized(1), XtUnrealizeWidget(1),
realize(4).
Xt - Widget Lifecycle XtRealizeWidget()
