NAME

SYNOPSIS

ARGUMENTS

RETURNS

DESCRIPTION

Explicit Modifiers

XmtNameToWidget() also supports special ``modifiers'' at the beginning of a widget name that change the reference widget and start the search from an ancestor widget. Multiple modifiers can be used; they act as unary operators, and are evaluated from right-to-left. The modifiers are the following:

^

This operator changes the reference widget to the parent of the current reference widget.

~

This operator changes the reference widget to the near est shell ancestor of the reference widget.

^{name}

This operator changes the reference widget to the near est ancestor widget with the instance name name, or if no such ancestor is found, the nearest ancestor with a class or superclass name name.

Implicit Modifiers

If there are modifiers at the beginning of the specified name, those modifiers explicitly specify which widget is to be used as the reference. If there are no explicit modifiers, then the reference widget may be implicitly modified by one of the following rules.

• If the name begins with a `*' wildcard, then the reference widget is not used, and the search is performed relative to the root application shell widget of the specified refer ence. This provides the same semantics as a name beginning with `*' in a resource file.

  If the name does not begin with a modifier or the `*' wildcard, then it must begin with a widget component name. Thus the remaining implicit modification rules rules all describe ways of finding a widget that matches this name.

• If the first component of the name is the name of a sibling of the reference widget, then the reference widget is implicitly changed to the parent of the reference widget so that the sibling will be found. This is a useful behavior when XmtNameToWidget() is invoked through the String-to-Widget converter-when using the XmForm widget, for example, this makes it easy to refer to sibling widgets for form attachments.
• If the first component of the name is the name of a child of the reference widget, then the reference widget is not modified.
• If the first component of the name does not match a sibling or a child of the specified reference widget, then XmtNameToWidget() checks to see if it matches the name of any of the root application shells that have been registered with XmtInitializeApplicationShell(). If so, it uses that shell as the root of the search. For applications that create multiple root shells, each with an independent widget hierarchy, this provides way to refer to widgets in a separate hierarchy.
• Finally, if there were no modifiers, and if none of the above rules apply, then the widget name is invalid, and XmtNameToWidget() returns NULL.

Widget Naming

Once the reference widget has been determined by parsing either the modifiers or by examining the first component of the widget name, the search for a matching widget is started with the children of the reference widget, using the remain ing components of the name. Widgets are named exactly as they would be in a resource file:

• Each component name may be a widget instance name or a widget class name.
• A `.' between two components is a ``tight binding'' and indicates that the second component names a direct child of the first.
• A `*' between two components is a ``loose binding'' and indicates that the second component names any descendant of the first, with zero or more intervening ``generations'' of widgets.
• A `?' in place of a component name is a wildcard that matches any single widget, but does not elide any number of generations as the `*' modifier does.

The Search

The search is conducted breadth-first, which means that if several children match the specified name (because of wildcards, for example) then the one with the shortest name (i.e. the closest descendant of the reference widget) will be returned. If there are multiple matches the same number of generations removed from the reference widget, the one returned is arbitrary.

Special Cases

There are also a few special cases in this search:

• If there is no name, or if the name consists only of modifiers, then the reference widget, or the modified reference widget is returned. This means that a widget name like ``^^'', is legal, and returns the grandparent of the specified reference widget. This special case means that it is possible to search up the tree for ancestor widgets (especially using the ^{} modifier syntax) rather than only searching down the tree for descendants.
• The name ``self'' is a special case. The name ``self'' by itself, with no modifiers, will always match the reference widget. This is often useful in resource files with the String-to-Widget converter. Also, you can use ``self'' (again, only when there are no modifiers) as a way to force XtNameToWidget() to start its search at the specified reference widget. If you specify a name ``button1'', XtNameToWidget() will find a sibling with that name in preference to a child with that name. To disambiguate this case you can explicitly use ``self.button1'' when searching for a child and ``^button1'' when looking for a sibling.

SEE ALSO