You must encase the contents of the header file inside a conditional compilation directive like the following:

#ifndef _ExmSimple_h
#define _ExmSimple_h
  ...
#endif /* _ExmSimple_h */

These lines prevent compiler errors by ensuring that the code inside the file will be included only once per compilation.

You must include the public header file for your widget's superclass. The superclass of ExmSimple widget is XmPrimitive. The public header file of the XmPrimitive widget is Xm/Primitive.h. Therefore, Simple.h includes the following declaration:

#include <Xm/Primitive.h>

Now consider the ExmString demonstration widget. The superclass of theExmString widget is ExmSimple widget. Therefore, the ExmString public header file must include the following declaration:

#include <Exm/Simple.h>

You should encase the remainder of the public header file inside the following pair of conditional compilation directives:

#ifdef __cplusplus
extern "C" {
#endif
 ...

#ifdef __cplusplus
}  /* Close scope of 'extern "C"' declaration which encloses file. */
#endif

The preceding code prevents link-time errors when C++ applications use this widget.

When thinking up variable names, try to avoid names that are C++ keywords, such as class and

new. Using such keywords as variable names could prevent C++ compilation.

You must create externally accessible names for the widget and widget class.

For example, the following provides the definition of widget and widget class for the ExmSimple widget:

externalref WidgetClass exmSimpleWidgetClass;
typedef struct _ExmSimpleClassRec *ExmSimpleWidgetClass;
typedef struct _ExmSimpleRec      *ExmSimpleWidget;

The externalref macro encapsulates all system dependencies regarding external data references. Therefore, for portability, you should use the externalref macro instead of the extern keyword in order to make variables externally accessible. You should use extern to make functions externally accessible.

You must define string equivalents for every new resource name created by your widget. However, if your widget is using a resource name already used in the Motif toolkit, you should not define a string equivalent for it. You define the string equivalents with the #define preprocessor directive.

For example, the ExmSimple widget defines a new resource named ExmNsimpleShape. Since this resource name is not defined in the standard Motif widget set, the widget public header file defines the following two string equivalents:

#define ExmNsimpleShape "simpleShape"
#define ExmCSimpleShape "SimpleShape"

The preceding definitions associate a literal string with the new resource name.

In addition to ExmNsimpleShape, the ExmSimple widget specifies two other resources: XmNmarginHeight and XmNmarginWidth. However, the widget public header file does not need to define string equivalents for these resources because these resource names are already used in the standard Motif widget set (for example, by XmLabel ). If you want to determine whether a particular resource name has already been defined by Motif, look in the Xm/XmStrDefs.h file.

You must also define a string equivalent for each new representation type used by your widget. (See Chapter 6 for details on representation types.) For example, the ExmSimple widget creates a representation type named ExmRSimpleShape. Therefore, the widget public header file for ExmSimple defines this string equivalent as follows:

#define ExmRSimpleShape "ExmSimpleShape"

In addition, since the ExmRSimpleShape representation type is an enumerated data type, the widget public header file must also specify all its enumerated constants as follows:

enum { ExmSHAPE_OVAL=0, ExmSHAPE_RECTANGLE=1 };

You should use Motif's representation type facility to register new enumerated types. (See Chapter 6 for details.)

Your widget public header file should define the API for the widget. For example, the following code establishes the API for the ExmSimple widget:

extern Widget ExmCreateSimple(
                              Widget    parent,
                              String    name,
                              Arg      *arglist,
                              Cardinal  argCount
                             );

If your widget contains additional convenience functions, then this is the place to declare them.

You must encase the contents of the file inside a conditional compilation directive, as follows:

#ifndef _ExmSimpleP_h
#define _ExmSimpleP_h
 ...
#endif /* _ExmSimpleP_h */

These lines prevent compiler errors by ensuring that the code inside the file will only be included once per compilation.

You must include the following two header files:

For example, the ExmSimple widget derives from the XmPrimitive class. Therefore, the widget private header file of ExmSimple includes the following two files:

#include <ExmSimple.h>
#include <Xm/PrimitiveP.h>

You should encase the remaining code of the file inside the following pair of conditional compilation directives:

#ifdef __cplusplus
extern "C" {
#endif
 ...

#ifdef __cplusplus
}  /* Close scope of 'extern "C"' declaration which encloses file. */
#endif

If the application program using your widget is written in C++, then allowing for C++ compilation is mandatory. Otherwise, allowing for C++ compilation is merely a good idea.

You must define inheritance class method macros. Once defined, your widget's subclasses can inherit your widget's methods simply by specifying the inheritance macro in the appropriate field of the class record. For example, the ExmSimple widget creates the following eight inheritance macros:

#define ExmInheritDrawVisual     ((XtWidgetProc) _XtInherit)
#define ExmInheritDrawShadow     ((XtWidgetProc) _XtInherit)
#define ExmInheritCreateGC       ((XtWidgetProc) _XtInherit)
#define ExmInheritDestroyGC      ((XtWidgetProc) _XtInherit)
#define ExmInheritSelectGC       ((ExmSelectGCProc) _XtInherit)
#define ExmInheritCalcVisualSize ((XtWidgetProc) _XtInherit)
#define ExmInheritCalcWidgetSize ((XtWidgetProc) _XtInherit)
#define ExmInheritReconfigure    ((ExmReconfigureProc) _XtInherit)

If an inheritance macro requires a new data type definition, you must provide it here. For example, ExmInheritSelectGC and ExmInheritReconfigure both require new data type definitions, as follows:

typedef GC   (*ExmSelectGCProc)(
                        Widget);
typedef void (*ExmReconfigureProc)(
                        WidgetClass,
                        Widget,
                        Widget) ;

The inheritance macros should follow Motif naming conventions. The inheritance macro names should begin with the widget set prefix (in this case, Exm) followed by the word Inherit. Similarly, the new data type definitions should begin with the widget set prefix and end with Proc.

The widget class part defines the inheritable methods and data members of the widget. For example, following is the widget class part of the ExmSimple widget:

typedef struct _ExmSimpleClassPart
{
        XtWidgetProc                   draw_visual;
           XtWidgetProc                draw_shadow;
           XtWidgetProc                create_gc;
           XtWidgetProc                destroy_gc;
           ExmSelectGCProc                  select_gc;
        XtWidgetProc                   calc_visual_size;
           XtWidgetProc                calc_widget_size;
   ExmReconfigureProc      reconfigure;
        XtPointer                         extension;
} ExmSimpleClassPart;

Motif strongly recommends specifying an extension field as the last field of every widget class part. Providing an extension field helps implement binary compatibility if you add methods to the widget in future releases. The extension field should have the XtPointer data type.

You must define the widget's full class record. This structure specifies the class parts of all widget classes in the current widget's hierarchy. The first field in the full class record specifies the class part of the top widget in the hierarchy (Core). The next field specifies the class part of the widget below the top widget, and so on. The final field specifies the class part of the current widget.

For example, the ExmSimple widget derives from Core and XmPrimitive. Therefore, the class record structure of ExmSimple is as follows:

typedef struct _ExmSimpleClassRec
{
        CoreClassPart           core_class;
        XmPrimitiveClassPart    primitive_class;
        ExmSimpleClassPart      simple_class;
} ExmSimpleClassRec;

There are a few conventions that you should follow in the full class record:

After defining the data type, you must now declare an externalref variable having this data type; for example:

externalref ExmSimpleClassRec exmSimpleClassRec;

By convention, the variable has the same name as the data type except that the first character of the variable is always lowercase.

All manager widgets derive from Core, Composite, Constraint, and XmManager. Therefore, the class record structure of the sample manager widget ExmGrid is the following:

typedef struct _ExmGridClassRec
{
    CoreClassPart       core_class;
    CompositeClassPart  composite_class;
    ConstraintClassPart constraint_class;
    XmManagerClassPart  manager_class;
    ExmGridClassPart    grid_class;
} ExmGridClassRec;
externalref ExmGridClassRec exmGridClassRec;

Your private header file typically declares a widget instance record. The widget instance record describes the inheritable data members of your widget. The inheritable data members consist of your widget's resources plus those variables that subclasses may need access to. For example, following is the widget instance record for the ExmSimple widget:

typedef struct _ExmSimplePart
{
    unsigned char           simple_shape;
    Dimension               margin_height;
    Dimension               margin_width;
    GC                      normal_gc;
    GC                      insensitive_gc;
    Dimension               pref_width;
    Dimension               pref_height;
    Boolean                 need_to_compute_width;
    Boolean                 need_to_compute_height;
    XRectangle              visual;
    Boolean                 need_to_reconfigure;
    Pixel                   saved_foreground;
} ExmSimplePart;

By convention, the top fields in the widget instance part are declarations of the widget's resources. The ExmSimple widget declares three new resources, so the widget instance part declares them in the top three fields.

The fields below the resource fields declare variables that are accessible to subclasses of ExmSimple. For example, the ExmString widget is a subclass of ExmSimple, so any function in ExmString can access any of these variables. Conversely, a widget that is not a subclass of ExmSimple should not access any of these variables.

You must declare a full instance record for your widget private header file. The full instance record of ExmSimple appears as follows:

typedef struct _ExmSimpleRec
{
    CorePart            core;
    XmPrimitivePart     primitive;
    ExmSimplePart       simple;
} ExmSimpleRec;

All Motif manager widgets derive from Core, Composite, Constraint, and XmManager. Therefore, the full instance record of the ExmGrid sample manager widget is as follows:

typedef struct _ExmGridRec
{
    CorePart            core;
    CompositePart       composite;
    ConstraintPart      constraint;
    XmManagerPart       manager;
    ExmGridPart         grid;
} ExmGridRec;

---

Note: If you are writing a primitive widget, you can skip this section.

---

If you are writing a manager widget, you should always define the following two structures:

You should define these structures even if the widget does not currently support any constraint resources. Declaring these constraint structures now will prevent source compatibility problems if a future subclass wants to provide constraint resources.

The following subsections detail the two constraint structures.

typedef struct _ExmGridConstraintPart
{
        Dimension      grid_margin_width_within_cell;
        Dimension      grid_margin_height_within_cell;
} ExmGridConstraintPart, * ExmGridConstraint;

typedef struct _ExmGridConstraintRec
{
        XmManagerConstraintPart manager;
        ExmGridConstraintPart   grid;
} ExmGridConstraintRec, *ExmGridConstraintPtr;

#define ExmGridCPart(w) \
  (&((ExmGridConstraintPtr) (w)->core.constraints)->grid)

In the course of writing your own widgets, you can create convenience functions that could help other widget writers (or perhaps yourself when writing a subsequent widget). Prototypes for these convenience functions must appear in the widget private header file.

Think about it this way. If you want a function to be accessible to application programmers, define it in the widget public header file. If you want a function to be inaccessible to application programmers, define it in the widget private header file.

The typical widget source code file begins by including several header files. The order of inclusion is important. You should include

For example, the widget source code file for the ExmSimple widget does not specify any operating system, C, Xlib, or Xt header files. (Actually, a lot of these header files will be automatically included by Motif header files.) Simple.c does require its private header file (SimpleP.h). Simple.c also needs a bunch of other Motif header files in order for Xme calls and traits to work properly. The entire collection of header files included in Simple.c is as follows:

#include <Exm/SimpleP.h>    /* widget private header file for ExmSimple */
#include <Xm/DrawP.h>       /* for Xme drawing functions */
#include <Xm/RepType.h>     /* for representation type facility */
#include <Xm/Screen.h>      /* for screen information */
#include <Xm/TraitP.h>      /* for installing traits */
#include <Xm/CareVisualT.h> /* for XmQTcareParentVisual trait */
#include <Xm/ContItemT.h>   /* for XmQTcontainerItem trait */
#include <Xm/ContainerT.h>  /* for XmQTcontainer trait */

Table 2-1 lists some of the files that are more commonly used by widget writers.

After specifying header files, you can optionally define any macros useful to your widget. Motif makes the following stylistic suggestions regarding your macros:

You should declare all static functions.

We recommend that you use ANSI C style function prototypes when declaring functions.

You should name class methods after their class record field names. For example, if the class record field name is class_initialize, then the class method should be named ClassInitialize. The class method name differs from the class record field name in only two respects:

There is only one exception to these naming rules and it concerns the class record field named expose. The preceding conventions suggest that you should name the associated class method Expose. Unfortunately, Xlib already defines a macro named Expose. Therefore, by convention, you should name this class method Redisplay instead of Expose.

By convention, you should declare the functions in the following order:

Chapter 7 details Motif translations and actions. Motif makes the following stylistic demands on widget writers:

Chapter 6 details resources. For now, you should be aware of the following Motif resource naming conventions:

The fifth field of each resource structure defines an offset. If you want to create a widget that will be a binary compatible with future releases, then you should use the XmPartOffset macro to define the offset. (See Chapter 15 for details on binary compatibility.) If binary compatibility is not a goal, then you should use the XmPartOffset macro to define the offset.

The widget class record is your widget's table of contents. Chapter 3 details the class record for Motif primitive widgets; Chapter 4 details the class record for Motif manager widgets. For now, you should concentrate on a few stylistic points.

Make sure that all fields in the class record are commented with the formal names of the fields. For the portions of the class record defined by the Intrinsics, refer to Intrinsics documentation to find the formal names. For the portions of the class record defined by Motif, refer to Chapters 3 and 4. For example, the following excerpt from ExmSimple shows the proper way to comment the fields:

...
/* class_part_initialize */      ClassPartInitialize,
/* class_inited */               FALSE,
/* initialize */                 Initialize,
/* initialize_hook */            NULL,
/* realize */                    XtInheritRealize,
...

Motif recommends that the last field of every Motif class record be an extension field. An extension field must contain one of the following:

Motif and the Intrinsics provide the following class extension record data types:

Motif strongly recommends that all class extension record variables be declared as static; for example:

static XmPrimitiveClassExtRec  primitiveClassExtRec = ...

You should not declare the class record as a constant.

Your widget must provide an external definition of the widget class record and the widget class. For example, the external definition of the widget class record for the ExmSimple widget is as follows:

externaldef (exmsimpleclassrec) ExmSimpleClassRec exmSimpleClassRec = {

and the external definition of the widget class pointer is as follows:

externaldef (exmsimplewidgetclass) WidgetClass exmSimpleWidgetClass =
                                                         (WidgetClass) &exmSimpleClassRec;

Motif recommends using the externaldef macro instead of the extern keyword when declaring variables. The externaldef macro handles a few portability problems.

If your source code file requires any static (file scope) variables, declare them next. For instance, if your widget uses representation types, you will probably have to declare at least one static representation type variable. For example, the ExmSimple widget creates a new representation type. Therefore, it provides the following static variables:

/* The SimpleShapeNames variable holds some normalized values.
   The XmRepTypeRegister function will use these values to determine the
   legal values for a given representation type. */
static String SimpleShapeNames[] = {
        "simple_oval",
        "simple_rectangle"
};
/* Declare a representation type variable. */
static XmRepTypeId simpleShapeId;

If your widget installs any traits, you should declare the trait record variable(s) here. (See Chapter 5 for details about traits. For example, the ExmString widget installs the XmQTaccessTextual trait, so it requires the following trait record variable declaration:

static XmConst XmAccessTextualTraitRec StringATT = {
  0,                            /* version */
  StringGetValue,
  StringSetValue,
  StringPreferredFormat,
};

Notice that the variable declaration contained the XmConst macro. If your C compiler supports the const keyword, then XmConst resolves to const. If your C compiler does not support the const keyword, then XmConst resolves to nothing.

The majority of code in most widget source code files is taken up by the code for the widget's methods. Place the widget's methods in the following order:

Table 2-2 lists all the methods of the Simple.c source code file in the order in which they appear in the file:

You should precede each widget method with a comment describing the purpose of the method. Following is a conventional Motif method comment:

/************************************************************************
 *
 *  ClassPartInitialize
 *      Processes the class fields which need to be inherited.
 *
 ************************************************************************/

The Xt library in Release-6 of the X-Window system (X11R6) is MT-safe. A brief description of the MT-safety provided by Xt follows.

Motif uses the same locking strategies implemented in Xt:

Dimension XmFooBar(Widget w)
{
        .....
 return w->core.width;
}

Dimension XmFooBar(Widget w)
{
      int return_value;
      XtAppContext app = XtWidgetToApplicationContext(w);
      XtAppLock(app);
      ......
      return_value = w->core.width;
      XtAppUnlock(app);
            return return_value;
}

{
      WidgetClass wc; Widget w;
      (*wc->core_class.resize)(w);

}

{
      WidgetClass wc; Widget w;
      XtWidgetProc resize;
      XtProcessLock();
      resize = wc->core_class.resize;
      XtProcessUnlock();
      (*resize)(w);
}

while (XtAppGetExitFlag(app) == False)  {
        XEvent event;
#ifndef MT_SAFE
        XtAppNextEvent(app, &event);
        XtDispatchEvent(&event);  /* Process it */
#else  /* MT_SAFE version ...  */
        XtInputMask mask;
        while (!(mask = XtAppPending(app)))
      /* EMPTY */;  /* Busy waiting - so that we don't lose our Lock! */
        if (mask & XtIMXEvent) {  /* We have a XEvent */
       /* Get the XEvent - we know its there! Note that XtAppNextEvent would also process timers/alternate inputs */
                XtAppNextEvent(app, &event); /* No blocking, since an event is ready */
             XtDispatchEvent(&event);  /* Process it */
        }
        else /* Not a XEvent, its an alternate input/timer event - Process it.
            XtAppProcessEvent(app, mask); /* No blocking, since an event is ready */
  }

Some of the C library functions are inherently MT unsafe. A MT-safe libc implementation will provide alternatives to those functions. This section lists the common libc functions that are MT-unsafe along with their safe POSIX equivalents.

The following Motif library functions are MT-safe:

Occasionally, one might end up using globals to communicate state information across functions. The only way to retain the proper semantics in this case might be to use thread specific storage. The Xthreads.h header file in X11R6 provides a set of wrapper functions to support thread_specific storage.

The sequence of steps to creating and using Thread Specific Storage are:

Thread specific storage can be expensive, hence it should be utilized as a last resort.

For MT-safety, widget resources should be designed so that XtGetValues returns a copy of the resource value (in the heap). The GetValuesHook method or the XmSyntheticResource export_proc can be used to achieve this.

If a live pointer to the actual instance field has to be returned, flag this situation as a MT-unsafe usage so that the application programmer is aware of it.

Following is a summary of the discussions in this section: