Query: xtcreatewidget
OS: hpux
Section: 1
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
XtCreateWidget() XtCreateWidget()
Name
XtCreateWidget - create an instance of a widget.
Synopsis
Widget XtCreateWidget(name, object_class, parent, args, num_args)
String name;
WidgetClass object_class;
Widget parent;
ArgList args;
Cardinal num_args;
Inputs
name Specifies the resource name for the created object.
object_class
Specifies the widget class pointer for the created widget; may be objectClass or any subclass.
parent Specifies the parent widget; may be of class objectClass or any subclass thereof.
args Specifies the argument list to override the resource defaults.
num_args Specifies the number of arguments in the argument list.
Returns
An child widget or object of parent of class object_class.
Description
XtCreateWidget() creates a new instance of class object_class named name, as a child of parent. The resource name/resource value pairs in
args are used to set resources in the widget and override resources from the resource database. The details of the widget creation proce-
dure are explained in the "Algorithm" section below.
Usage
A created widget will not be visible until it is managed. You can manage a child widget with XtManageChild(), and you can combine the call
to XtCreateWidget() and XtManageChild() by calling XtCreateManagedWidget(). Note that you cannot manage direct subclasses of Object.
A created and managed widget will not be visible unless it has been realized (i.e., had an X window created). You realize a widget by
calling XtRealizeWidget(), which realizes the specified widget and all of its children. If you create a child of a realized widget, the
child is automatically realized. You will generally call XtRealizeWidget() once in an application, just before entering your main event
loop.
Rather than initialize an ArgList and pass it to XtCreateWidget(), you can call XtVaCreateWidget() or XtVaCreateManagedWidget() which both
accept a NULL-terminated variable length argument list of resource names and resource values.
To create a popup widget, you must use XtCreatePopupShell() rather than XtCreateWidget().
You may give your widgets any name you want, and may give multiple widgets the same name. If two sibling widgets have the same name, how-
ever, they will get the same resources from the resource database, and it is undefined which will be returned by a call to XtNameToWid-
get().
XtCreateWidget() allows you to create child widgets of non-Composite widgets. If you do this, the child widget will not appear on any
children list in the parent and will not be automatically realized when its parent is realized or destroyed when its parent is destroyed.
The only time you should do this is when writing a non-Composite widget that explicitly creates and manages its own children.
Algorithm
XtCreateWidget() does the following when creating a widget or an object:
o Checks to see if the class_initialize() method has been called for this class and for all superclasses and, if not, calls those neces-
sary in a superclass-to-subclass order.
o If the specified class is not coreWidgetClass or a subclass thereof, and the parent's class is a subclass of compositeWidgetClass and
either no extension record in the parent's composite class part extension field exists with the record_type NULLQUARK or the
accepts_objects field in the extension record is False, XtCreateWidget() issues a fatal error.
o Allocates memory for the widget instance.
o If the parent is a member of the class constraintWidgetClass, allocates memory for the parent's constraints and stores the address of
this memory into the constraints field.
o Initializes the Core nonresource data fields (for example, parent and visible).
o Initializes the resource fields (for example, background_pixel) by using the CoreClassPart resource lists specified for this class and
all superclasses.
o If the parent is a member of the class constraintWidgetClass, initializes the resource fields of the constraints record by using the
ConstraintClassPart resource lists specified for the parent's class and all superclasses up to constraintWidgetClass.
o Calls the initialize() methods for the widget in superclass-to-subclass order.
o If the parent is a member of the class compositeWidgetClass, puts the widget into its parent's children list by calling its parent's
insert_child() method.
o If the parent is a member of the class constraintWidgetClass, calls the ConstraintClassPart initialize() methods, in superclass-to-sub-
class order.
XtCreateWidget() converts and caches resources in a way equivalent to XtConvertAndStore() when initializing the object instance. Because
there is extra memory overhead required to implement reference counting, clients may distinguish those objects that are never destroyed
before the application exits from those that may be destroyed and whose resources should be deallocated.
To specify whether reference counting is to be enabled for the resources of a particular object when the object is created, the client can
specify a value for the Boolean resource XtNinitialResourcesPersistent, class XtCInitialResourcesPersistent.
When XtCreateWidget() is called, if this resource is not specified as False in either the arglist or the resource database, then the
resources referenced by this object are not reference-counted, regardless of how the type converter may have been registered. The effec-
tive default value is True; thus clients that expect to destroy one or more objects and want resources deallocated must explicitly specify
False for XtNinitialResourcesPersistent
The resources are still freed and destructors called when XtCloseDisplay() is called if the conversion was registered as XtCacheByDisplay.
See Also
XtCreateManagedWidget(1), XtVaCreateWidget(1), XtVaCreateManagedWidget(1).
Xt - Widget Lifecycle XtCreateWidget()