NAME
Synopsis
Widget reference;
String names;
Inputs
referenceSpecifies the widget from which the search is to start. Must be of class Core or any subclass.
namesSpecifies the partially qualified name of the desired widget.
Returns
A child of reference that matches names.
Description
reference widget whose name matches the specified names. The names argument specifies a simple 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
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. 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 variable, 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 freely change the details of the widget hierarchy it creates as long as the name of the text widget remains unique.
Algorithm
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 specified names, where each component of names matches exactly the corresponding 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, 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
— X Toolkit Intrinsics Reference Manual © O’Reilly & Associates