Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XmtNameToWidget(3)	   Library Functions Manual	    XmtNameToWidget(3)

       XmtNameToWidget() - find	a descendant or	ancestor widget	by name.

       #include	<Xmt/Xmt.h>

       Widget XmtNameToWidget(Widget ref, String name)


	    ref	   The	``reference'' widget, relative to which	the named wid-
		   get is looked up.

	    name   The name of the widget to look up. This name	may be a hier-
		   archical name, with individual component names separated by
		   periods; it may also	contain	resource file  wildcards,  and
		   other special ``modifiers'',	described below.


	    The	named widget, or NULL if no such widget	was found.

       XmtNameToWidget()  is  similar  to  XtNameToWidget(),  but is much more
       flexible	than that Xt Intrinsics	function. Like XtNameToWidget(),  Xmt-
       NameToWidget()  takes a ``reference'' widget as its first argument, and
       looks up	the named widget (the name is the the second  argument)	 rela-
       tive 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 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.

	      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	super-
	      class 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	refer-
       ence. If	there are no explicit modifiers, then the reference widget may
       be implicitly modified by one of	the following rules.

       o 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 wid-
	 get that matches this name.

       o 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

       o If the	first component	of the name is the name	of a child of the ref-
	 erence	widget,	then the reference widget is not modified.

       o 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  XmtInitializeApplication-
	 Shell(). If so, it uses that shell as the root	 of  the  search.  For
	 applications  that create multiple root shells, each with an indepen-
	 dent widget hierarchy,	this provides way to refer  to	widgets	 in  a
	 separate hierarchy.

       o Finally,  if  there were no modifiers,	and if none of the above rules
	 apply,	then the widget	name is	invalid, and XmtNameToWidget() returns

       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	refer-
       ence widget, using the remain ing components of the name.  Widgets  are
       named exactly as	they would be in a resource file:

       o Each  component  name may be a	widget instance	name or	a widget class

       o A `.' between two components is a  ``tight  binding''	and  indicates
	 that the second component names a direct child	of the first.

       o 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.

       o 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:

       o 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.

       o 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	speci-
	 fied  reference  widget.  If  you specify a name ``button1'', XtName-
	 ToWidget() 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.

       Chapter 9, Looking Up Widgets By	Name, XmtRegisterWidgetConverter(),

Xmt				  Motif	Tools		    XmtNameToWidget(3)


Want to link to this manual page? Use this URL:

home | help