XtNameToWidget() XtNameToWidget()
Name
XtNameToWidget - find a named widget.
Synopsis
Widget XtNameToWidget(reference, names);
Widget reference;
String names;
Inputs
reference Specifies the widget from which the search is to start. Must be of class Core or any subclass.
names Specifies the partially qualified name of the desired widget.
Returns
A child of reference that matches names.
Description
XtNameToWidget() returns a descendant of the reference widget whose name matches the specified names. The names argument specifies a sim-
ple object name or a series of simple object name components separated by periods or asterisks. Asterisks have the same meaning to this
function as they do in a resource file.
The "Algorithm" section below explains the procedure XtNameToWidget() uses to find the named child.
Usage
If you want to look up an immediate child of a widget, simply pass the widget and the child's unqualified name. If you need to lookup a
descendant, you can provide a fully qualified name to that descendant, or if you don't know the full name, or if you don't even know how
many levels removed that descendant is, you can use an asterisk before the name.
Note that if there is more than one child with the specified name, it is undefined which will be returned.
You can use XtNameToWidget() to hide the details of a user interface and for modular programming. If module A creates an interface which
contains a text widget, and module B need to get the contents of the text widget, module A could export the text widget in a global vari-
able, or instead, it could simply define the name of the text widget as part of the module definition. Then module B, or any other module
could look up that widget with XtNameToWidget() when it is needed. Because XtNameToWidget() supports wildcarding, module A can freely
change the details of the widget hierarchy it creates as long as the name of the text widget remains unique.
Algorithm
XtNameToWidget() returns the descendant with the shortest name that matches the specification according to the following rules (where child
is either a popup child or a normal child if the widget is a subclass of Composite):
o Enumerate the object subtree rooted at reference widget in breadth-first order, qualifying the name of each object with the names of all
its ancestors up to but not including reference. The ordering between children of a common parent is not defined.
o Return the first object in the enumeration that matches the specified names, where each component of names matches exactly the corre-
sponding component of the qualified object name and an asterisk matches any series of components, including none.
o If no match is found, return NULL.
Since breadth-first traversal is specified, the descendant with the shortest matching name (i.e., the fewest number of components), if any,
will always be returned. However, since the order of enumeration of children is undefined and since the Intrinsics do not require that all
children of a widget have unique names, XtNameToWidget() may return any child that matches if there are multiple objects in the subtree
with the same name(s). Consecutive separators (periods or asterisks) that contain at least one asterisk are treated as a single asterisk.
Consecutive periods are treated as a single period.
See Also
XtCreateWidget(1), XtName(1).
Xt - Object Information XtNameToWidget()