Name
initialize — Core method for initializing instance variables.
Synopsis
typedef void (∗XtInitProc)(Widget);
Widget request, new;
Arguments
requestSpecifies the widget with resource values as requested by the argument list, the resource database, and the widget defaults.
newSpecifies a widget with the new values, both resource and nonresource, as modified by the initialize method.
Description
The initialize method performs the following:
•Allocates space for and copies any resources that are referenced by address. For example, if a widget has a field that is a String, it cannot depend on the characters at that address remaining constant but must dynamically allocate space for the string and copy it to the new space. (Note that you should neither allocate space for nor copy callback lists.)
•Computes values for unspecified resource fields. For example, if width and height are zero, the widget should compute an appropriate width and height based on other resources. This is the only time that a widget should ever directly assign its own width and height. Note that a widget may only directly assign its own width and height within the initialize, set_values, and set_values_hook methods.
•Computes values for uninitialized nonresource fields that are derived from resource fields. For example, graphics contexts (GCs) that the widget uses are derived from resources such as background, foreground, and font.
•Supersedes values in the superclass. initialize methods are called in superclass-to-subclass order. The main purpose of a subclass may be to change nonresource data in a superclass, since the subclass has direct access to the instance record. In particular, size calculations of a superclass are often incorrect for a subclass, and the subclass must modify or recalculate fields declared and computed by its superclass.
•Checks certain fields for internal consistency. For example, it makes no sense to specify a colormap and a visual together when the colormap was not created with the given visual.
initialize methods are called in superclass-to-subclass order after all fields specified in the resource lists have been initialized. The initialize method does not need to examine the arguments if all public resources are declared in the resource list. Most of the initialization code for a specific widget class deals with fields defined in that class, not with fields defined in its superclasses.
If a subclass does not need an initialize method because it does not need to perform any of the above operations, it can specify NULL for the initialize field in the class record.
Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, size calculations of a superclass are often incorrect for a subclass and in this case, the subclass must modify or recalculate fields declared and computed by its superclass.
As an example, a subclass can visually surround its superclass display. In this case, the width and height calculated by the superclass’s initialize method are too small and need to be incremented by the size of the surround. The subclass needs to know whether its superclass’s size was calculated by the superclass or specified explicitly. All widgets must place themselves into whatever size is explicitly given, but they should compute a reasonable size if no size is requested.
The request and new arguments provide the necessary information for a subclass to determine the difference between a specified size and a size computed by a superclass. The request widget is the widget as originally requested. The new widget starts with the values in the request, but it has been updated by all the superclass’s initialize methods called so far. A subclass’s initialize method can compare these two to resolve any potential conflicts.
In the above example, the subclass with the visual surround can see if the width and height in the request widget are zero. If so, it adds its surround size to the width and height fields in the new widget. If not, it must make do with the size originally specified.
The new widget becomes the actual widget instance record. Therefore, the initialize method should change only the new widget (the request widget is for reading only), and if the method needs to call any routines that operate on a widget, it should specify new as the widget instance.
At a minimum, the initialize method must compute values for Core width and height, if they have not been computed by a superclass. This is the only time that a widget should ever directly assign its own width and height.
Examples
Here is the initialize method from Label:
/∗ ARGSUSED ∗/
static void Initialize(request, new)
Widget request, new;
{
LabelWidget lw = (LabelWidget) new;
if (lw->label.label == NULL)
lw->label.label = XtNewString(lw->core.name);
else {
lw->label.label = XtNewString(lw->label.label);
}
GetnormalGC(lw);
GetgrayGC(lw);
SetTextWidthAndHeight(lw);
if (lw->core.width == 0)
lw->core.width = lw->label.label_width + 2 ∗ lw->label.internal_width;
if (lw->core.height == 0)
lw->core.height = lw->label.label_height + 2∗lw->label.internal_height;
lw->label.label_x = lw->label.label_y = 0;
(∗XtClass(new)->core_class.resize) ((Widget)lw);
}