If you plan to install a trait in your widget, then your widget source code file must include the appropriate trait header files. Every widget that installs one or more traits must include the general-purpose trait header file TraitP.h. In addition, depending on which traits are being installed, the widget source code file must also include the appropriate trait-specific header file documented in the reference pages of Chapter 19.

For example, the widget source code file (String.c) for the ExmString widget contains the following three declarations:

#include <Xm/TraitP.h>
#include <Xm/AccTextT.h>
#include <Xm/SpecRenderT.h>

The Xm/AccTextT.h header file is included because ExmString installs the XmQTaccessTextual trait. In addition, the Xm/SpecRenderT.h header file is included because ExmString also uses the XmQTspecifyRenderTable trait.

You must declare a trait structure variable for every trait that you plan to install. You should place this declaration in the source code file after the class record declaration but before the first widget method.

The data type of a trait structure variable must be the trait structure associated with the trait. (See Chapter 19 to find the relevant trait structure for your trait.) For example, the trait structure associated with the XmQTaccessTextual trait is XmAccessTextualTraitRec.

Motif recommends giving the trait structure variable a name that consists of the widget name followed by an acronym that symbolizes the trait. For example, ExmString uses the variable name StringATT to identify its XmQTaccessTextual trait structure variable.

All trait structure variable declarations should be prefixed with static XmConst. (See Chapter 2 for details about XmConst.)

For example, the ExmString widget declares a trait structure variable for the XmQTaccessTextual trait as follows:

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

The preceding declaration declares a trait structure variable named StringATT. This variable has data type XmAccessTextualTraitRec. This data type is defined in the AccTextT.h trait header file.

The first field of all trait structure variables is the version field. You must always specify an integer value for this field. At Motif Release 2.0, none of the standard Motif traits make any attempt to interpret the value in the version field. However, at Motif Release 2.0, you must set the version field to 0 since future releases of Motif may use the version field.

The remaining fields following the version field specify the names of the trait methods. By convention, the trait method names in your trait structure variables should correspond to the trait method names documented in the reference pages of Chapter 19. However, your trait method names should eliminate underscores and should capitalize the first letter of every word. For example, we named the second trait method StringSetValue because the trait method name string_set_value is documented in the XmQTaccessTextual trait reference page of Chapter 19.

Some traits allow you to omit certain trait methods. (See the individual reference pages of Chapter 19 for details.) To tell Motif that you are omitting a certain trait method, simply mark the appropriate field in the trait structure record as being NULL. For example, if we did not provide a StringSetValue method in the ExmSimple widget, the preceding declaration would have looked like this:

static XmConst XmAccessTextualTraitRec StringATT = {m
0,                         /* version */m
StringGetValue,            /* trait method */m
NULL,                      /* not providing this trait method */m
StringPreferredFormat,     /* trait method */
};

Call the XmeTraitSet function to install a trait on a widget class. Typically, your widget calls XmeTraitSet from the class_part_initialize method. By so doing, the trait is installed not only on the current widget, but also on all of its subclasses. If you want the trait installed on the current widget class only (and not its subclasses), then you should call XmeTraitSet from the class_initialize method instead of the class_part_initialize method.

For example, ExmString calls XmeTraitSet to install the XmQTaccessTextual trait as follows:

XmeTraitSet((XtPointer) widgetclass, XmQTaccessTextual,
           (XtPointer) &StringATT);

The third argument to XmeTraitSet holds the address of the trait structure variable created in Step 2.

Because the call to XmeTraitSet took place in the class_part_initialize method, Motif installs this trait on ExmString and on all its subclasses.

In some cases, you may not want the widget you are writing to inherit some of the installed traits of its superclasses. For these situations, you can prevent trait inheritance by specifying NULL as the third argument to XmeTraitSet. For example, suppose you are writing a subclass of ExmString, named ExmStringSubclass. If you do not want ExmStringSubclass to install ExmQTaccessTextualTrait, the class_part_initialize method of ExmStringSubclass should call XmeTraitSet as follows:

XmeTraitSet((XtPointer) widgetclass, XmQTaccessTextual, NULL);

A trait method is a function that is callable by another widget, even if that other widget is not a subclass of the current widget. Typically, the caller is either the parent widget or the child widget of the current widget.

For example, the XmQTaccessTextual trait defines three trait methods. The simplest trait method, StringPreferredFormat, is shown as follows:

static int
StringPreferredFormat(
        Widget  w)
{
/* Choose XmFORMAT_XmSTRING because the ExmString widget holds its displayed
   text in XmString format (as opposed to Multibyte or WCS format). */
        return(XmFORMAT_XmSTRING);
}

By convention, you should place your widget's trait methods toward the end of your widget source code file, immediately prior to the publicly accessible functions.

Use the XmeTraitGet function to determine if a specified widget holds a certain trait. This function returns NULL if the specified widget does not hold the trait, and a non-NULL value (a trait record) if the widget does hold the trait. For example, a parent widget can use the following code to determine if its child widget holds the XmQTaccessTextual trait:

if ( XmeTraitGet((XtPointer)a_widget_class, XmQTaccessTextual))
  /* Yes, a_widget_class renders a primary text block. */
else
  /* a_widget_class does not render a primary text block. */

If a widget does hold a trait, the XmeTraitGet function returns a pointer to the appropriate trait structure variable. Another widget can use this returned pointer to call trait methods. For example, suppose that a parent of ExmString needs to determine the preferred string format of ExmString. The following code from the parent does just that:

XmAccessTextualTrait  childs_trait_record;
int                   preferred_string_format_of_child;

 /* Get a pointer to the trait structure variable. */
   childs_trait_record =
                        (XmQTaccessTextual) XmeTraitGet((XtPointer)a_widget_class,                                                                                                                                                                                                                      XmQTaccessTextual);

 /* Use the returned pointer to call the child's
                preferred_format trait method. */
preferred_string_format_of_child =
     childs_trait_record->preferred_format((Widget)parent_widget);

Note that, in some cases, the widget holding the trait has not defined a particular trait method; that is, the trait method is set to NULL. For that reason, the following code is an improvement over the previous example:

/* Does this trait method exist? */
if      (childs_trait_record->preferred_format !=
        (XmAccessTextualTraitRec) NULL)   {
/* It does exist, so call the trait method. */
        preferred_string_format_of_child =
                childs_trait_record->preferred_format((Widget)parent_widget);
        }