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;
Arguments
nameSpecifies the resource name for the created widget, or non-widget object, which is used for retrieving resources and, for that reason, should not be the same as any other widget that is a child of same parent.
object_class
Specifies the widget class pointer for the created widget; may be of class objectClass or any subclass thereof.
parentSpecifies the parent widget.
argsSpecifies the argument list to override the resource defaults.
num_argsSpecifies the number of arguments in the argument list. (Note that you can determine the number of arguments in a static argument list using the XtNumber macro.)
Description
XtCreateWidget creates a new instance of class object_class. The usual way to access XtCreateWidget is to combine creation and management with XtCreateManagedWidget; you will normally use XtCreateWidget and XtManageChild only in cases where you wish to create a number of interrelated widgets, and bring them under parental management at the same time.
XtCreateWidget creates a new widget instance structure and invokes the widget’s initialization method. XtCreateWidget resolves conflicts between values for the arguments supplied in the environment with those supplied in args in the new widget instance structure.
XtCreateWidget performs many of the boilerplate operations of widget creation:
•XtCreateWidget checks to see whether the XtProc method has been called for this class and for all superclasses and, if not, calls those necessary, in a superclass-to-subclass order.
•XtCreateWidget issues a fatal error if all of the following conditions occur:
—The specified class is not coreWidgetClass or a subclass thereof.
—The parent is a subclass of compositeWidgetClass.
—Either no extension record in the parent’s composite class part extension field exists with the record_type of NULLQUARK, or the accepts_objects field in the extension record is False.
•XtCreateWidget allocates memory for the widget instance.
•If the parent is a subclass of constraintWidgetClass, memory is allocated for the parent’s constraints, and stores the address of this memory into the constraints field of the widget.
•XtCreateWidget initializes the core nonresource data fields (for example, parent and visible).
•XtCreateWidget initializes the resource fields (for example, background_pixel) by using the resource lists specified for this class and all superclasses.
•If the parent is a subclass of constraintWidgetClass, XtCreateWidget initializes the resource fields of the constraint record by using the constraint resource list specified for the parent’s class and all superclasses up to constraintWidgetClass.
•XtCreateWidget calls the initialize procedures for the widget starting at the Core initialize procedure and descending to the widget’s initialize procedure.
•If the parent is a subclass of compositeWidgetClass, XtCreateWidget puts the widget into its parent’s children list by calling its parent’s insert_child method.
•If the parent is a subclass of constraintWidgetClass, XtCreateWidget calls the constraint initialize methods, starting at constraintWidgetClass and descending to the parent’s constraint initialize method.
Note that the XtCreateWidget function gets resources as a superclass-to-subclass operation. That is, the resources specified in the Core resource list are fetched, then those in the subclass, and so on down to the resources specified for this widget’s class. Within a class, resources are fetched in the order they are declared.
In general, if a widget resource field is declared in a superclass, that field is included in the superclass’s resource list and need not be included in the subclass’s resource list. For example, the Core class contains a resource entry for background_pixel. Consequently, the implementation of Label need not also have a resource entry for background_pixel. However, a subclass, by specifying a resource entry for that field in its own resource list, can override the resource entry for any field declared in a superclass. This is most often done to override the defaults provided in the superclass with new ones.
At class initialization time, resource lists for that class are scanned from the superclass down to the class to look for resources with the same offset. A matching resource in a subclass will be reordered to override the superclass entry. (A copy of the superclass resource list is made to avoid affecting other subclasses of the superclass.) Also at class initialization time, the Intrinsics produce an internal representation of the resource list to optimize access time when creating widgets. To save memory, the Intrinsics may overwrite the storage allocated for the resource list in the class record; therefore, widgets must allocate resource lists in writable storage and must not access the list contents directly after the XtProc method has returned.
The Intrinsics-supplied classes are described in Object(3), RectObj(3), Core(3), Constraint(3), and Composite(3).