hpux man page for xtnametowidget

XtNameToWidget()														  XtNameToWidget()

Name
  XtNameToWidget - find a named widget.

Synopsis
  Widget XtNameToWidget(reference, names);
	 Widget reference;
	 String names;

Inputs
  reference Specifies the widget from which the search is to start.  Must be of class Core or any subclass.

  names     Specifies the partially qualified name of the desired widget.

Returns
  A child of reference that matches names.

Description
  XtNameToWidget()  returns a descendant of the reference widget whose name matches the specified names.  The names argument specifies a sim-
  ple 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 XtNameToWidget() uses to find the named child.

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.

  You  can  use XtNameToWidget() to hide the details of 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	vari-
  able,  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 XtNameToWidget() when it is needed.  Because XtNameToWidget() supports  wildcarding,  module  A  can  freely
  change the details of the widget hierarchy it creates as long as the name of the text widget remains unique.

Algorithm
  XtNameToWidget() returns the descendant with the 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):

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

  o  Return  the  first  object in the enumeration that matches the specified names, where each component of names matches exactly the corre-
     sponding component of the qualified object name and an asterisk matches any series of components, including none.

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

See Also
  XtCreateWidget(1), XtName(1).

Xt - Object Information 													  XtNameToWidget()