Motif Widget Writer's Guide Migration Version

Motif 2.1 Widget Writer's Guide

Enumerated Representation Types

Suppose you are writing a widget that defines an enumerated resource. In other words, the resource requires an enumerated constant as a value. In picking the representation type, you can do either of the following:

Pick a predefined representation type

The following subsections examine both categories.

Predefined Enumerated Representation Types

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:

XmRArrowDirection defines the following registered constants: XmARROW_UP, XmARROW_DOWN,XmARROW_LEFT, and XmARROW_RIGHT. For information on these constants, see the description of XmNarrowDirection in XmArrowButton(3).

XmRAlignment defines the following registered constants: XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER, and XmALIGNMENT_END. For information on these constants, see the description of XmNalignment in XmLabel(3).

XmRDirection defines the following registered constants: XmRIGHT_TO_LEFT_TOP_TO_BOTTOM, XmLEFT_TO_RIGHT_TOP_TO_BOTTOM, XmRIGHT_TO_LEFT_BOTTOM_TO_TOP, XmLEFT_TO_RIGHT_BOTTOM_TO_TOP, XmTOP_TO_BOTTOM_RIGHT_TO_LEFT, XmTOP_TO_BOTTOM_LEFT_TO_RIGHT, XmBOTTOM_TO_TOP_RIGHT_TO_LEFT, and XmBOTTOM_TO_TOP_LEFT_TO_RIGHT. For information on these constants, see the description of XmRDirection in XmLabel(3)

XmRIndicatorType defines the following registered constants: XmINDICATOR_NONE, XmINDICATOR_FILL, Xm_INDICATOR_BOX, XmINDICATOR_CHECK, XmINDICATOR_CHECK_BOX, XmINDICATOR_CROSS, and XmINDICATOR_CROSS_BOX. For information on these constants, see the description of XmRIndicator in XmToggleButton(3).

XmRMultiClick defines the following registered constants: XmMULTICLICK_KEEP and XmMULTICLICK_DISCARD. For information on these constants, see the description of XmPushButton in XmNmultiClick(3)

XmRNavigationType defines the following registered constants: XmNONE, XmTAB_GROUP, XmSTICKY_TAB_GROUP, and XmEXCLUSIVE_TAB_GROUP. For information on these constants, see the description of XmNnavigationType in XmPrimitive(3) or XmManager(3).

XmROrientation defines the following registered constants: XmVERTICAL and XmHORIZONTAL. For information on these constants, see the description of XmNorientation in XmScrollBar(3).

XmRSelectionMode defines the following registered constants: XmNORMAL_MODE and XmADD_MODE. For information on these constants, see the description of XmNselectionMode in XmList(3).

XmRSeparatorType defines the following registered constants: XmSINGLE_LINE, XmDOUBLE_LINE, XmSINGLE_DASHED_LINE, XmDOUBLE_DASHED_LINE, XmNO_LINE XmSHADOW_ETCHED_IN, XmSHADOW_ETCHED_OUT, XmSHADOW_ETCHED_IN_DASH, and XmSHADOW_ETCHED_OUT_DASH. For information on these constants, see the description of XmNseparatorType in XmSeparator(3).

XmRShadowType defines the following registered constants: XmSHADOW_IN, XmSHADOW_OUT, XmSHADOW_ETCHED_IN and XmSHADOW_ETCHED_OUT. For information on these constants, see the description of XmNshadowType in XmFrame(3).

XmRUnitType defines the following registered constants: XmPIXELS, Xm100TH_MILLIMETERS, Xm1000TH_INCHES, Xm100TH_POINTS, Xm100TH_FONT_UNITS, XmINCHES, XmCENTIMETERS, XmMILLIMETERS, XmPOINTS, and XmFONT_UNITS. For information on these constants, see the description of XmNunitType in XmPrimitive(3)or XmManager(3).

XmRVisualEmphasis defines the following registed constants: XmSELECTED and XmNOT_SELECTED. For information on these constants, see the description of XmNvisualEmphasis in XmIconGadeget(3).

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:

Call the XmRepTypeGetId function to get the identification number of the representation type.

Call the XmRepTypeValidValue function to check the validity of the resource's value.

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 */

Defining Your Own Enumerated Representation Types

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:

In the widget source code file, you must declare an array variable to hold the normalized names of the possible values of the resource.

In the widget source code file, you must declare a global variable of type XmRepTypeId.

In the widget source code file (probably in the class_initialize or class_part_initialize method), you must call the XmRepTypeRegister routine.

In the widget public header file, you must define a string equivalent for the new representation type.

In the widget public header file, you must specify enumerated constants for the possible values of the new representation type.

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 Size of Enumerated Representation Types

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)