Motif Widget Writer's Guide Migration Version

Motif 2.1 Widget Writer's Guide

The Primitive Class Extension Record

Nearly every primitive widget should define a primitive class extension record. The primitive class extension record currently consists of seven fields. Future releases may add more fields.

The following is the primitive class extension record for the ExmString widget:

/* Here is the primitive class extension record. */
static XmPrimitiveClassExtRec primClassExtRec = {
   /* next_extension */             NULL,
   /* record_type */                NULLQUARK,
   /* version */                    XmPrimitiveClassExtVersion,
   /* record_size */                sizeof(XmPrimitiveClassExtRec),
   /* widget_baseline */            WidgetBaselines,
   /* widget_display_rect */        WidgetDisplayRect,
   /* widget_margins */             NULL,
};

The following subsections detail each of the fields in this structure.

The next_extension Field

Your widget should always set the next_extension field to NULL.

The record_type Field

Your widget should always set the record_type field to NULLQUARK.

The version Field

Your widget must set the version field to XmPrimitiveClassExtVersion.

The record_size Field

The record_size field holds the size of the primitive class extension record. You should set it as follows:

/* record_size */                
sizeof(XmPrimitiveClassExtRec),

The widget_baseline Field

Your widget must set the widget_baseline field to one of the following:

NULL, to indicate the absence of a widget_baseline method. Set the field to NULL if your widget does not render text to the screen.

XmInheritBaselineProc, to inherit the widget_baseline method of your widget's superclass. XmPrimitive does not provide a widget_baseline method, so you cannot inherit from it.

The name of your widget's widget_baseline method.

If your widget renders text, it must provide or inherit a widget_baseline method. The purpose of this method is to create a table of text baselines. That is, each entry in the table must hold the baseline of a different line of text. For example, a widget that displays six lines of text would require a six-entry baseline table. The baseline of any given line of text is a vertical offset in pixels from the origin of the widget's bounding box to the given baseline.

Several manager widgets use baseline tables. The RowColumn widget, for example, uses the information in the baseline tables of its children widgets to align text properly. The baseline tables are also used by the XmWidgetGetBaselines and XmTextGetBaseline functions.

In order to be compatible with other Motif widgets and functions, your widget_baseline method must have the following prototype:

Boolean WidgetBaseline(
        Widget          w,
        Dimension       **baselines,
        int             *line_count)

Upon the function's completion, the following must occur:

The baselines variable must return a pointer to an array that contains the value of each baseline of text in the widget. Note that your widget's widget_baseline method must call XtMalloc to allocate space to hold the baselines. Conversely, the caller of the widget_baseline method must call XtFree to free the allocated space.

The line_count variable must return the number of lines in the widget. You may want to use the XmStringLineCount function to determine the line count.

The method itself must return a Boolean value that indicates whether the widget contains a baseline. If the value is True, the function returns a value for each baseline of text. If it is False, the function was unable to return a baseline value.

(See the ExmString demonstration widget for an example of a widget_baseline method.)

Several standard Motif widgets, including XmText, XmTextField, XmLabel, and XmIconGadget provide a widget_baseline method.

The widget_display_rect Field

Your widget must set the widget_display_rect field to one of the following:

NULL, to indicate the absence of a widget_display_rect method. Set the field to NULL if your widget does not render any graphics, pixmaps, or text to the screen.

XmInheritDisplayRectProc, to inherit the widget_display_rect method of your widget's superclass. XmPrimitive does not provide a widget_display_rect method, so you cannot inherit from it.

The name of your widget's widget_display_rect method.

If your widget does render graphics, pixmaps, or text, then it should provide a widget_display_rect method. The purpose of this method is to define the bounding rectangle of the visible information inside the widget. The bounding rectangle is stored in an XRectangle structure. The x and y coordinates that are stored inside this structure represent offsets from the upper left of the widget.

If a widget displays a pixmap, then the bounding rectangle defines the perimeter of the pixmap. If the widget displays text, then the first text character marks the upper left of the bounding rectangle. The coordinates of the lower right of the bounding rectangle are defined by the last line of text and the longest line of any text in the widget. If the widget displays graphics, then the bounding rectangle is undefined. However, if the graphics area spans a clearly defined rectangle, then this rectangle should mark the range of the bounding box.

Several Motif managers use the widget_display_rect method to determine how to align their children. In addition, Motif applications can access the widget_display_rect method by calling the XmWidgetGetDisplayRect function.

Your widget_display_rect method must have the following prototype:

Boolean WidgetDisplayRect(
        Widget  w,
        XRectangle      *displayrect)

Upon the function's completion, the displayrect variable must describe the dimensions of the bounding rectangle. (See the XmWidgetGetDisplayRect(3) reference page of the Motif Programmer's Reference for details on the returned bounding rectangle.)

For an example of a complete widget_display_rect method, see the demonstration widgets ExmSimple or ExmString.

Several standard Motif widgets provide a widget_display_rect method, including XmText, XmTextField, XmLabel, and XmIconGadget.

The widget_margins Method

You should set the widget_margins field to NULL.