NAME

XmtCreateChildren(), XmtCreateQueryChildren() XmtCreateQueryListChildren - 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 argument 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 creating 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 Creation. 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 XmtCreateQueryChildren() creates a widget child, it checks the list of child_name arguments, 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 widget'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 xmtChildren. 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 created.
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 XmtCreateQueryListChildren() 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 XtAppMainLoop().

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

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

USAGE

SEE ALSO