Overriding the default of an inherited resource is straightforward. The subclass simply needs to redefine the resource. For example, the XmPrimitive widget defines the XmNhighlightThickness resource and sets its default value to 2. However, the ExmString widget needs to change its default value from 2 to 0. Therefore, the resource table of ExmString contains the following code:

static XtResource resources[] =
{
  {
   XmNhighlightThickness,
   XmCHighlightThickness,
   XmRHorizontalDimension,
   sizeof(Dimension),
   XtOffsetOf( XmPrimitiveRec, primitive.highlight_thickness),
   XmRImmediate,
   (XtPointer) 0  /* new default value */
  },
}

The sixth field of most resource records is set to XmRImmediate, meaning that the seventh field holds the resource's default value. However, you may wish to have Motif calculate the resource's default value at runtime. In order to do so, you must do the following:

For example, consider the following definition of the XmNrenderTable resource from the ExmString demonstration widget:

{
      XmNrenderTable,
      XmCRenderTable,
      XmRRenderTable,
      sizeof(XmRenderTable),
      XtOffsetOf( ExmStringRec,string.render_table),
      XtRCallProc,
      (XtPointer) DefaultFont
},

The function specified in the seventh field must take three arguments:

For example, the DefaultFont function is coded as follows:

static void
DefaultFont (
        Widget w,
        int offset,
        XrmValue *value)
{
 ExmStringWidgetClass wc = (ExmStringWidgetClass)XtClass(w);
 static XmRenderTable  f1;

 /* Find the default render table associated with the default
    render table type. */
  f1 = XmeGetDefaultRenderTable (w,
                                 wc->string_class.default_render_table_type);

   value->addr = (XtPointer)&f1;
   value->size = sizeof(f1);
}

The XmeGetDefaultPixel function is particularly useful for dynamic resource defaulting. This function returns the default background, foreground, top shadow, bottom shadow, or select colors for a given widget. For example, suppose you are creating a widget that displays a graph. Further suppose that your widget defines a new resource called XmNgraphSelectColor, which holds the select color of the new widget. Suppose you want the XmNgraphSelectColor resource to have a default value equal to the default select color of the widget. To do this, you must first define the resource record to take an XmRCallProc as follows:

{
 XmNgraphSelectColor,
 XmCGraphSelectColor,
 XmRPixel,
 sizeof(Pixel),
 XtOffsetOf(MyGraphRec, graph.graph_select_color),
 XmRCallProc,
 (XtPointer) GetDefaultSelectColor
},

Then, you have to write a function that calls XmeGetDefaultPixel; for example:

static void
GetDefaultSelectColor(
      Widget widget,
      int offset,
      XrmValue *value)
{
   XmeGetDefaultPixel (widget, XmSELECT, offset, value);
}

Defining a synthetic resource is a four-step process:

static XtResource resources[] =
{
    ...
    {
        XmNsomething,
        XmCSomething,
        XmRHorizontalDimension,
        sizeof (Dimension),
        XtOffsetOf(WidgetRec, widget.something),
        XmRImmediate,
        (XtPointer)42
    },
    ...
}

static XmSyntheticResource syn_resources[] =
  {
   /* one or more synthetic resource records */
  }

static XmSyntheticResource syn_resources[] =
{
  ...
  {  /* Here is a synthetic resource record. */
   XmNsomething,
   sizeof (ResourceDatatype),
   XtOffsetOf(WidgetRec, widget.something),
   FromInternalToExternalFormat,
   FromExternalToInternalFormat
  }, /* End of synthetic resource record. */
  ...
};

/* syn_resources */              syn_resources,
/* num_syn_resources */          XtNumber(syn_resources),

void MyExportProcConversionRoutine(
        Widget     wid,
        int           offset,
           XtArgVal     *value)

XmImportOperator MyImportProcConversionRoutine(
   Widget        wid,
           int      offset,
           XtArgVal      *value)

The synthetic resource implementation is particularly helpful for converting resource values from real-world units (like millimeters) to pixels and back again.

The Xlib and Xme drawing routines all expect pixel arguments. Unfortunately, pixels are not always a very handy unit for widget users to work in. One important problem with pixel units is that a pixel's size depends on the resolution of the screen.

To solve this problem the Motif base classes XmPrimitive and XmManager both provide the XmNunitType resource. This resource holds the kind of units that a given distance or position is measured in. By default, the unit type is pixels. However, the application may specify a unit type of some real-world unit, like millimeters, instead. Any resource whose value symbolizes a size, position, or distance must be able to convert these real-world units to and from pixels.

The synthetic resource mechanism provides a way to do these conversions. In fact, you do not even have to write conversion routines because Motif provides four unit conversion routines for you:

For example, the ExmSimple widget uses all four of these routines in its syn_resources array as follows:

static XmSyntheticResource syn_resources[] =
{
    {
         XmNmarginWidth,
               sizeof (Dimension),
               XtOffsetOf( ExmSimpleRec, simple.margin_width),
               XmeFromHorizontalPixels,
               XmeToHorizontalPixels
    },
    {
               XmNmarginHeight,
               sizeof (Dimension),
         XtOffsetOf( ExmSimpleRec, simple.margin_height),
         XmeFromVerticalPixels,
               XmeToVerticalPixels
    },
};

The synthetic resource mechanism is completely transparent to the widget writer. This is because the Motif base classes, XmPrimitive and XmManager, call the appropriate conversion routines at the appropriate times.

For example, the class_part_initialize method of XmPrimitive and XmManager both contain code that initializes the synthetic resource. In other words, both base classes call the routine that converts all the synthetic resource values from external to internal format Similarly, both base classes contain code in their set_values routines to call the external to internal format conversion routine whenever one of the resource values is changed. Finally, both base classes contain code in their get_values_hook routines to call the internal-to-external format conversion routine whenever an application requests the resource value.

Since the class_part_initialize, set_values, and get_values_hook methods are all chained, these conversion routines are automatically called for all primitive and manager widgets.

If you are defining a new enumerated resource that serves a similar purpose to an existing Motif enumerated resource, then you should probably pick an existing Motif enumerated representation type rather than creating your own. Motif predefines the following enumerated representation types:

For example, the previous list shows that Motif predefines the representation type XmRAlignment. The only legal values that can be assigned to a resource having this representation type are XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER, and XmALIGNMENT_END. For details on what these three constants symbolize, see the description of the XmNalignment resource in the XmLabel reference page. This reference page appears in the Motif Programmer's Reference. When defining a resource with similar requirements to XmNalignment, you should specify a representation type of XmRAlignment. For example, the ExmString widget defines a resource named XmNalignment that controls the alignment of text within the widget. The wise choice for the data type of XmNalignment is XmRAlignment, as shown in the following resource record:

...
{
 XmNalignment,
 XmCAlignment,
 XmRAlignment,
 sizeof(unsigned char),
 XtOffsetOf( ExmStringRec,string.alignment),
 XmRImmediate,
 (XtPointer) XmALIGNMENT_CENTER
},
...

One of the primary responsibilities of a widget is to check for valid resource values. Using predefined representation types simplifies this chore by turning it into an easy two-step process:

For example, the class_initialize method of the ExmString widget gets the identification number with the following code:

static XmRepTypeId alignmentId;
  alignmentId = XmRepTypeGetId(XmRAlignment);

The initialize and set_values methods of the ExmString widget check resource values as follows:

Boolean   ValidValue;
  ValidValue = XmRepTypeValidValue(alignmentId,
                                    my_widget->string.alignment,
                                    my_widget);
  if (!ValidValue)
    /* take appropriate corrective response */

If none of the predefined representation types match the needs of your resource, then you can create a new representation type. Registering a new representation type is a five-step process:

For example, the ExmSimple widget defines a representation type named ExmRSimpleShape. The following is the declaration of the array variable (Step 1):

static String SimpleShapeNames[] = {
        "simple_oval",
        "simple_rectangle"
};

And following is the declaration of the XmRepTypeId variable (Step 2):

static XmRepTypeId simpleShapeId;

The class_initialize method calls XmRepTypeRegister as follows (Step 3):

simpleShapeId = XmRepTypeRegister (ExmRSimpleShape, SimpleShapeNames,
                                   NULL, XtNumber(SimpleShapeNames));

Notice how the array variable created in Step 1 is passed as an argument to XmRepTypeRegister. Furthermore, note that the XmRepTypeId variable is assigned the return value.

The public header file declares a string equivalent of the new representation type as follows (Step 4):

#define ExmRSimpleShape "ExmSimpleShape"

The public header file also specifies the appropriate enumerated constants (Step 5):

enum { ExmSHAPE_OVAL=0, ExmSHAPE_RECTANGLE=1 };

The fourth field of all resource records holds the size of the resource value. If the resource has an enumerated representation type, then the fourth field should be set as follows:

sizeof(unsigned char)

To support the automatic scaling of Pixmaps, the following representation types are available:

The converters for these representation types ignore the scaling ratio that might be present in their print shell hierarchy and behave normally; that is, they convert XBM and XPM files to Pixmap. These are used when Pixmap is employed for tiling, rather than when it is used for images and icons.

The semantics of the XmRBitmap and XmRDynamic representation type converters apply a scaling ratio to the resulting Pixmap that is equal to the print shell resolution divided by the value of the XmNdefaultPixmapResolution of their XmPrintShell. No scaling is applied if the widget for which a Pixmap resource is being converted is not a descendant of XmPrintShell. See Chapter 16 for more information on XmPrintShell.

Resources whose values symbolize dimensions or positions should use the following representation types:

For example, the ExmSimple widget associates the XmRHorizontalDimension representation type with the XmNmarginWidth resource. Similarly, the XNmarginHeight resource is associated with the XmRVerticalDimension representation type. The unit type conversion functions (XmeFromHorizontalPixels, XmeFromVerticalPixels, XmeToHorizontalPixels, and XmeToVerticalPixels) depend on these representation types.

Motif provides the following three representation types for converting bitmaps and pixmaps.