FreeBSD Manual Pages
XmtNameToWidget(3) Library Functions Manual XmtNameToWidget(3) NAME XmtNameToWidget() - find a descendant or ancestor widget by name. SYNOPSIS #include <Xmt/Xmt.h> Widget XmtNameToWidget(Widget ref, String name) ARGUMENTS INPUTS ref The ``reference'' widget, relative to which the named widget is looked up. name The name of the widget to look up. This name may be a hierar- chical name, with individual component names separated by peri- ods; it may also contain resource file wildcards, and other special ``modifiers'', described below. RETURNS The named widget, or NULL if no such widget was found. DESCRIPTION XmtNameToWidget() is similar to XtNameToWidget(), but is much more flexible than that Xt Intrinsics function. Like XtNameToWidget(), XmtNameToWidget() takes a ``reference'' widget as its first argument, and looks up the named widget (the name is the the second argument) relative to that reference widget. Hierarchical widget names are specified as the are in resource files; the `*' and `?' wildcards are supported, and widget class names may be used in place of widget instance names. 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 opera- tors, and are evaluated from right-to-left. The modifiers are the follow- ing: ^ This operator changes the reference widget to the parent of the cur- rent reference widget. ~ This operator changes the reference widget to the near est shell an- cestor 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 modi- fiers explicitly specify which widget is to be used as the reference. If there are no explicit modifiers, then the reference widget may be implic- itly 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 mod- ification 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 refer- ence widget, then the reference widget is implicitly changed to the par- ent 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 refer- ence 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 ap- ply, then the widget name is invalid, and XmtNameToWidget() returns NULL. Widget Naming Once the reference widget has been determined by parsing either the modi- fiers 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 wid- get) will be returned. If there are multiple matches the same number of generations removed from the reference widget, the one returned is arbi- trary. 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 grandpar- ent 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 descen- dants. * 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 Chapter 9, Looking Up Widgets By Name, XmtRegisterWidgetConverter(), XtNameToWidget(). Xmt Motif Tools XmtNameToWidget(3)
NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtNameToWidget&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>