XtNameToWidget()XtNameToWidget()NameXtNameToWidget - 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.
DescriptionXtNameToWidget() 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 func‐
tion 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.
AlgorithmXtNameToWidget() 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):
· 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.
· Return the first object in the enumeration that matches the speci‐
fied 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.
· 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. Con‐
secutive periods are treated as a single period.
See AlsoXtCreateWidget(1), XtName(1).
Xt - Object Information XtNameToWidget()
