Name

XtNameToWidget — translate a widget name to a widget instance. 

Synopsis

Widget XtNameToWidget(reference, name);

    Widget reference;
    String names;

Arguments

referenceSpecifies the widget from which the search is to start.  May be of class Object or any subclass. 

namesSpecifies the partially qualified name of the desired widget. 

Description

XtNameToWidget searches for a descendant of the 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.  XtNameToWidget returns the descendant with the shortest name that matches the specification according to the following rules (where child is either a pop-up 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, 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. 

Chapter 12, Menus, Gadgets, and Cascaded Pop Ups, in Volume Four, X Toolkit Intrinsics Programming Manual, presents a discussion and an example of XtNameToWidget. 

See Also

XtCreateManagedWidget(1), XtCreatePopupShell(1), XtCreateWidget(1).