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

FreeBSD Manual Pages

  
 
  

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

NAME
       XmtCreateChildren(),  XmtCreateQueryChildren()  XmtCreateQueryListChil-
       dren - create the descendants of	a widget  described  in	 the  resource
       file.

SYNOPSIS
       #include	<Xmt/Create.h>
       void XmtCreateChildren(Widget parent)

       #include	<Xmt/Create.h>
       void XmtCreateQueryChildren(Widget parent,
		      {	String child_name, Widget *child_address, }
		      NULL)

       Widget XmtCreateQueryListChildren(Widget	parent,	XmtWidgetList *	names,
		      Cardinal num_names)

       typedef struct {
		      XrmQuark nameq;
		      Widget *widgetp;
       } XmtWidgetList;

ARGUMENTS
       INPUTS

	    parent The widget that is to have its descendants created.

	    child_name
		   The name of a widget	to be returned.	May  be	 repeated  any
		   number  of times in a NULL-terminated variable-length argu-
		   ment	list.

	    names  An array containing num_names entries.

	    num_names
		   The number of entries in the	namesP lilst.

       OUTPUTS

	    child_address
		   The address at which	the widget specified by	child_name  is
		   to  be  stored.  May	 be  repeated any number of times in a
		   NULL-terminated variable length argument list.

DESCRIPTION
       XmtCreateChildren() and XmtCreateQueryChildren()	reads the  xmtChildren
       ``pseudo-resource'' of the specified parent widget from the application
       resource	database and create the	children specified by  that  resource.
       They repeat this	process	for each newly created child, recursively cre-
       ating an	entire widget tree.

       A typical xmtChildren resource in a resource database might  look  like
       the following:

	    saveas.xmtChildren:	XmLabel	prompt;\
	    XmTextField	input;\
	    XmSeparator	sep;\
	    XmPushButton okay, cancel, help;

       The formal definition of	the xmtChildren	grammar	is the following:

	    xmtChildren::   { declaration }
	    declaration::   { modifier } type child {"," child}	";"
	    modifier::	    "managed" |	"unmanaged" | registered style name
	    type::	    registered widget type | registered	template name
	    child::	    name of child to be	created

       The grammar is explained	in detail in Chapter 11, Automatic Widget Cre-
       ation. Note that	in order for widgets to	be  described  in  a  resource
       file,  their  types must	first be registered in your C code. You	can do
       this with XmtRegisterWidgetClass(), XmtRegisterWidgetConstructor(),  or
       related	functions  such	 as XmtRegisterMotifWidgets(). The xmtChildren
       syntax also supports named styles and  templates.  These	 are  reusable
       sets  of	 widget	 resources  and	pre-defined widget subtrees.  They are
       explained in Chapter 11.

       XmtCreateQueryChildren()	works like  XmtCreateChildren(),  but  it  can
       optionally  return pointers to some of the widgets it creates. It takes
       a NULL-terminated, variable-length argument list	 of  pairs  of	widget
       names  and addresses of widget variables. Each time XmtCreateQueryChil-
       dren() creates a	widget child, it checks	the list of  child_name	 argu-
       ments,  and if the name of the newly created child matches one of those
       names, then the pointer to that widget is stored	at  the	 corresponding
       child_address.

       Also  like  XmtCreateQueryListChild(), XmtCreateQueryListChildren() can
       return the widgets it creates via the names array argument. Each	 entry
       in  this	array has two values: a	XrmQuark nameq and a Widget * widgetp.
       The nameq must be initialized to	the Quark corresponding	 to  the  wid-
       get's name (typically by	calling	XrmQuarkToString); the widgetp must be
       initialized to point to a Widget	variable. The address  pointed	to  by
       widgetp	will be	set to the address of the last widget created with the
       given name, or NULL if no such widget was created.

       These functions also read other ``pseudo-resources''  besides  xmtChil-
       dren.  The xmtRequires resource specifies resource files	to be included
       before widgets are created, and three different	``creation  callback''
       resources  specify  procedures to be invoked at different points	in the
       widget creation process.	These other resources  are  summarized	below,
       and explained in	detail in Chapter 11.

       xmtRequires
	      Specifies	 one  or  more files to	be looked up and read into the
	      resource database. This resource works like #include in C	 code.
	      It is read and processed for the specified parent	widget and for
	      each child widget, just before the child is created.

       xmtCreationCallback
	      This resource is read for	each child that	is  created,  but  not
	      for  the	parent widget. It specifies a list of procedures to be
	      invoked directly after the child is created.

       xmtChildrenCreationCallback
	      This resource is read for	each child that	is  created,  but  not
	      for  the	parent widget. It specifies a list of procedures to be
	      invoked for the child after that child's own children  are  cre-
	      ated.

       xmtManagedCreationCallback
	      This  resource  is  read for each	child that is created, but not
	      for the parent widget. It	specifies a list of procedures	to  be
	      invoked  for  the	 child	after it and its descendents have been
	      created and after	it has been managed.

USAGE
       Creating	widgets	one-by-one by calling widget constructor functions  is
       often one of the	most tedious parts of GUI programming. Describing your
       widget hierarchy	in a resource file with	the  xmtChildren  resource  is
       easier,	especially  while  prototyping.	 In most Xmt applications, you
       will call XmtCreateChildren(), XmtCreateQueryChildren()	or  XmtCreate-
       QueryListChildren()  as	part of	your initialization code in main(). It
       is common to pass your root shell widget	as parent, and to call one  of
       these functions immediately before calling XtRealizeWidget() and	XtApp-
       MainLoop().

       There are a number of variants on these	functions.   XmtCreateChild(),
       XmtCreateQueryChild()  and  XmtCreateQueryListChild()  create  a	single
       named child of a	widget,	and then proceed to create all the descendants
       of  that	 child.	 XmtBuildDialog()  and XmtBuildQueryDialog() create an
       XmDialogShell widget, and then create all the descendants of that  dia-
       log.  This  is  useful for deferring the	creation of dialog boxes until
       they are	needed.	Similar	functions exist	for creating TopLevelShell and
       Application Shell widgets and their children.

SEE ALSO
       Chapter 11, Automatic Widget Creation,
       XmtBuild[Query]Application(), XmtBuild[Query]Dialog(),
       XmtBuild[Query]Toplevel(), XmtCreateChild(), XmtCreateQueryChild(),
       XmtCreateQueryListChild(), XmtRegisterMotifWidgets(),
       XmtRegisterPopupClass(),	XmtRegisterPopupConstructor(),
       Xmt[Va]RegisterWidgetClass(), Xmt[Va]RegisterWidgetConstructor(),
       XmtRegisterWidgetTypes(), XmtRegisterXmtWidgets().

Xmt				  Motif	Tools		  XmtCreateChildren(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | USAGE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmtCreateChildren&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help