XtCreateWidget()XtCreateWidget()NameXtCreateWidget - 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.
DescriptionXtCreateWidget() 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 man‐
age a child widget with XtManageChild(), and you can combine the call
to XtCreateWidget() and XtManageChild() by calling XtCreateManagedWid‐
get(). 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 wid‐
gets 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 XtNameToWidget().
XtCreateWidget() allows you to create child widgets of non-Composite
widgets. If you do this, the child widget will not appear on any chil‐
dren 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.
AlgorithmXtCreateWidget() does the following when creating a widget or an
object:
· 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.
· 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, XtCreateWid‐
get() issues a fatal error.
· Allocates memory for the widget instance.
· If the parent is a member of the class constraintWidgetClass, allo‐
cates memory for the parent's constraints and stores the address of
this memory into the constraints field.
· Initializes the Core nonresource data fields (for example, parent
and visible).
· Initializes the resource fields (for example, background_pixel) by
using the CoreClassPart resource lists specified for this class and
all superclasses.
· If the parent is a member of the class constraintWidgetClass, ini‐
tializes 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.
· Calls the initialize() methods for the widget in superclass-to-sub‐
class order.
· 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.
· 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 count‐
ing, 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 XtNinitialResourcesPersis‐
tent, 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, regard‐
less of how the type converter may have been registered. The effective
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 XtCloseDis‐
play() is called if the conversion was registered as XtCacheByDisplay.
See AlsoXtCreateManagedWidget(1), XtVaCreateWidget(1), XtVaCreateManagedWid‐
get(1).
Xt - Widget Lifecycle XtCreateWidget()
