# Common Desktop Environment Motif Widgets

The Common Desktop Environment includes the Motif toolkit.
In addition, the Common Desktop Environment provides four custom widgets you can use to provide certain
OPEN LOOK™ and
Microsoft® Windows functionality. This chapter describes these Motif custom widgets.

PG.widgs.mkr.2 PG.widgs.mkr.2
PG.widgs.mkr.3
PG.widgs.mkr.8
PG.widgs.mkr.13
PG.widgs.mkr.17

The
widget library, `libDtWidget`, contains two widgets that have now been superseded by Motif 2.1 widgets, and two widgets that enhance functionality of Motif 2.1 widgets:

- `
  DtSpinBox` combines a text field and arrow buttons in a control that can increment or decrement numeric or text values. It has been superseded by `XmSimpleSpinBox`.

- `
  DtComboBox` combines a text field and a list box in a control that displays one of the many valid choices for the text field. It has been superseded by `XmComboBox`

- `
  DtMenuButton` provides
  menu-cascading functionality outside of the menu bar.

- `
  DtEditor` incorporates such single text editor functions as cut and paste.

These widgets provide common functionality across all Common Desktop Environment applications. None of these widgets support subclassing.

The Custom Widgets library depends directly on the following libraries:

- `Xm` library for the Motif superclass support

- `Xt` library for creation and manipulation of widgets

- `X11` Library for the base X Window System

- `DtSvc` for desktop support utilized by `DtEditor`

## Using Motif in the Common Desktop Environment

The
The Common Desktop Environment includes Motif 2.1, plus four custom widgets. The custom widgets are described in detail in this chapter.

The Common Desktop Environment is source and binary compatible with Motif 1.2 applications. Existing Motif 1.2 applications will compile using Motif 2.1 include files. Existing Motif 1.2 binaries will run without modification using Motif 2.1 libraries.

### Motif Libraries

Use the Motif 2.1 and X11R6.2 libraries to develop a Common Desktop Environment Motif-compliant application for the X Window System.

#### Motif Library (libXm)

Common Desktop Environment provides all the
Motif 2.1 header files.

#### Motif UIL Library (libUil)

The Motif User Interface Language (UIL) is a specification language for describing the initial state of a Motif application's user interface.

Include the
`uil/UilDef.h` header file to access UIL.

#### Motif Resource Manager Library (libMrm)

The Motif Resource Manager (MRM) creates widgets based on definitions contained in User Interface Definition (UID) files created by the UIL compiler. MRM interprets the output of the UIL compiler and generates the appropriate argument lists for widget creation functions. Use `libMrm` to access the Motif Resource Manager.

Include the
`Mrm/MrmPublic.h` header files to access `libMrm` in your application.

### Usability Enhancements

Motif 2.1 contains minor enhancements to enable better usability by OPEN LOOK and Microsoft Windows users. The usability enhancements include:

- Enabling button two on a three-button mouse to be used to extend the current selection. This functionality is equivalent to the
  OPEN LOOK ADJUST mouse button.

- Enabling
  Tab to be used to move through a group of `PushButton` widgets and gadgets, `ArrowButton` widgets and gadgets, and `DrawnButton` widgets.

- Enabling button 3 to activate a `CascadeButton` menu.

- Providing three new resources (`pathMode, fileFilterStyle,` and `dirTextLabelString`) for the `
  XmFileSelectionBox` widget, which gives it a new look and feel. See the Common Desktop Environment: Programmer's Overview for details about the new `XmFileSelectionBox` resources.

- Enabling interoperability with Microsoft Windows and OPEN LOOK by providing multiple key bindings for Motif virtual keys.

Each of the preceding enhancements can be controlled by a resource: either a widget resource (for `XmFileSelectionBox`) or an application-wide resource (all other cases). The default values for this resource provide behavior and an API that is identical to that of Motif 1.2. For information on these enhancements and resources, see the `XmDisplay(3x)` and `XmFileSelectionBox(3x)` man pages.

### Visual Enhancements

Common Desktop Environment changes the default Motif look in the following ways:

- `RadioBox` fill color is changed to show state more clearly.

- `RadioBox` shape is changed from diamond to circular.

- A check glyph is added to the `CheckBox` to show state more clearly.

- `CascadeButtons` and menu items are changed to have an etched-in border when active.

- Thumb is removed from the read-only Scale to distinguish it from the Scale.

- Default shadow thickness is changed to 1 pixel.

- Default highlight thickness is changed to 1 pixel.

- Default `PushButton` visual draws the highlight inside the button's default shadow.

An application-wide resource can control each of these enhancements. The default Motif 2.1 values for these resources provide behavior and an API that is identical to that of Motif 1.2.

For information on these enhancements, see the `XmDisplay`(3), `XmPushButton`(3), `XmPushButtonGadget`(3), `XmToggleButton`(3), `XmToggleButtonGadget`(3), and `XmScale`(3) man pages.

## Text Field and Arrow Button Widget (DtSpinBox`)`

Use the `DtSpinBox` for
cycling through a list of text items or incrementing and decrementing a numeric entry. `DtSpinBox` is a subclass of the `XmManager` class and is used to display a text field and two arrows.

The `DtSpinBox` widget is a user interface control used to
increment and decrement an arbitrary text or numeric field. You can use it, for example, to cycle through the months of the year or days of the month. PG.widgs.mkr.4 shows examples of the `DtSpinBox` widget.

### Examples of the DtSpinBox widget

### Library and Header Files

The `DtSpinBox` widget is in the `
libDtWidget` library. The header file is `Dt/SpinBox.h`.

### Demo Program

A demo containing an example of the `DtSpinBox` widget is in `/usr/dt/examples/dtwidget/controls.c`.

### Moving to XmSimpleSpinBox

To use the Motif 2.1 `DtSimpleSpinBox` widget, change the `Dt` names for the class, types, and creation routines to `Xm`, and change `SpinBox` to `SimpleSpinBox`. For example, change all occurrences of `DtSpinBox` to `XmSimpleSpinBox` in your code. Alternatively, you can compile your existing code with -DDT_USE_XM_SSPINBOX. This information is supplied in case you choose to revise your CDE 1.0 application to use the Motif 2.1 widget.

### Convenience Functions

PG.widgs.mkr.5 lists the convenience functions for the `DtSpinBox` widget. See the `DtSpinBox`(3) man page for more information.

### DtSpinBox Convenience Functions

`Function` | `Description`
`DtCreateSpinBox()` | Creates a SpinBox widget.
`DtSpinBoxAddItem()` | Adds an item into a `DtSpinBox` widget at a specified location.
`DtSpinBoxDeletePos()` | Deletes a specified item from a `DtSpinBox` widget.
`DtSpinBoxSetItem()` | Sets the current item in a `DtSpinBox` widget.

### Classes

`DtSpinBoxWidget` inherits behavior and resources from the `Core`, `Composite`, `Constraint`, and `XmManager` classes.

The class pointer is `dtSpinBoxWidgetClass`.

The class name is `DtSpinBoxWidget`.

`DtSpinBoxWidget` does not support subclassing.

### Resources

The `DtSpinBox` widget defines the following set of widget resources. PG.widgs.mkr.6 lists the class, type, default, and access for each resource.

- `DtNarrowLayout` specifies the style and position of the `DtSpinBox` arrows.

- `DtNarrowSensitivity` specifies the sensitivity of the arrows in the `DtSpinBox`.

- `DtNspinBoxChildType` specifies the style of the `DtSpinBox`.

- `DtNdecimalPoints` specifies the position of the decimal point within the integer value when the child type is numeric.

- `DtNincrementValue` specifies the amount to increment or decrement the position when the child type is numeric.

- `DtNinitialDelay` specifies the amount of time in milliseconds before the arrow buttons begin to spin continuously.

- `DtNnumValues` specifies the number of items in the `DtNvalues` list when the child type is a string.

- `DtNvalues` supplies the list of strings to cycle through when the child type resource is a string.

- `DtNmaximumValue` specifies the upper bound on the `DtSpinBox` range when the child type is numeric.

- `DtNminimumValue` specifies the lower bound on the `DtSpinBox` range when the child type is numeric.

- `DtNmodifyVerifyCallback` is called just before the `DtSpinBox` position changes. The application can use this callback to implement new application-related logic, including setting a new position, spinning to, or canceling the impending action.

- `DtNposition` has a different value based on the child type resource. When the child type is a string, `DtNposition` is the index into the `DtNvalues` list for the current item. When the child type is numeric, `DtNposition` is the integer value of the `DtSpinBox` that falls within the maximum and minimum value range.

- `DtNrepeatDelay` is the number of milliseconds between repeated calls to the `DtNvalueChangedCallback` while the user is spinning the `DtSpinBox`.

- `DtNvalueChangedCallback` is called whenever the value of the `DtNposition` resource is changed through the use of the spinner arrows.

See the `DtSpinBox`(3) man page for more information.

### `DtSpinBoxWidget` Resources

`Name` | `Class` | `Type` | `Default` | `Access`
`DtNarrowLayout` | `DtCArrowLayout` | `unsigned char` | `DtARROWS_END` | CSG
`DtNarrowSensitivity` | `DtCArrowSensitivity` | `unsigned char` | `DtARROWS_SENSITIVE` | CSG
`DtNspinBoxChildType` | `DtCSpinBoxChildType` | `unsigned char` | `DtSTRING` | CG
`DtNdecimalPoints` | `DtCDecimalPoints` | `short` | `0` | CSG
`DtNincrementValue` | `DtCIncrementValue` | `int` | `1` | CSG
`DtNinitialDelay` | `DtCInitialDelay` | `unsigned int` | `250 ms` | CSG
`DtNnumValues` | `DtCNumValues` | `int` | `0` | CSG
`DtNvalues` | `DtCValues` | `XmStringTable` | `NULL` | CSG
`DtNmaximumValue` | `DtCMaximumValue` | `int` | `10` | CSG
`DtNminimumValue` | `DtCMinimumValue` | `int` | `0` | CSG
`DtNmodifyVerifyCallback` | `DtCCallback` | `XtCallbackList` | `NULL` | C
`DtNposition` | `DtCPosition` | `int` | `0` | CSG
`DtNrepeatDelay` | `DtCRepeatDelay` | `unsigned int` | `200 ms` | CSG
`DtNvalueChangedCallback` | `DtCCallback` | `XtCallbackList` | `NULL` | C

### Callback Structures

The callback structure follows and is described in PG.widgs.mkr.7.

    typedef struct {
     int  reason;
     XEvent *event;
     Widget widget;
     Boolean doit;
     int position;
     XmString value;
     Boolean crossed_boundary;
    } DtSpinBoxCallbackStruct;

### ``DtSpinBox Callbacks

`Callback` | `Description`
reason | Use this callback for three possible reasons. For the first call to the callback at the beginning of a spin, or for a single activation of the spin arrows, `DtCR_OK` is the reason. If the `DtSpinBox` is being continuously spun, the reason is `DtCR_SPIN_NEXT` or `DtCR_SPIN_PRIOR`, depending on the arrow that is spinning.
event | A pointer to the event that caused this callback to be invoked. It can be `NULL` when the `DtSpinBox` is continuously spinning.
widget | The widget identifier for the text widget that is affected by the spin.
doit | Sets this value only when the `call_data` comes from the `DtNmodifyVerifyCallback`. For a modifyVerify callback, the setting of this field by an application determines whether the action that initiated the callback should be performed. When this field is set to `False`, the action is not performed.
position | The new value of the `DtNposition` resource that results from the spin.
value | The new `XmString` value displayed in the Text widget that results from the spin. This string must be copied if it is used beyond the scope of the `call_data` structure.
crossed_boundary | This Boolean is True when the spinbox cycles, and/or `DtNspinBoxChildType` of `XmSTRING` wraps from the first item to the last or the last item to the first. When the `DtNspinBoxChildType` is `XmNUMERIC`, the boundary is crossed when the `DtSpinBox` cycles from the maximum value to the minimum value or vice versa.

### Example of DtSpinBox Widget

The following example shows how to create and use a `DtSpinBox` widget. You can find this code as part of the `controls.c` demo in the `/usr/dt/examples/dtwidget` directory.

    /*
     * Example code for SpinBox
     */

    #include <Dt/SpinBox.h>

    static char *spinValueStrings[] = {
     “alpha”, “beta”, “gamma”, “delta”,
     “epsilon”, “zeta”, “eta”, “theta”,
     “iota”, “kappa”, “lambda”, “mu”,
     “nu”, “xi”, “omicron”, “pi”,
     “rho”, “sigma”, “tau”, “upsilon”,
     “phi”, “chi”, “psi”, “omega”
    };

    static void ModifyVerifyCb(Widget, XtPointer, XtPointer);

    static void CreateSpinBoxes(Widget parent)
    {
        Widget titleLabel, spinBox;
        XmString *valueXmstrings;
        int numValueStrings;
        XmString labelString;
        Arg args[20];
        int i, n;

        /* Create value compound strings */

        numValueStrings = XtNumber(spinValueStrings);
     valueXmstrings = (XmString *)XtMalloc(numValueStrings
     sizeof(XmString*));
     for (i = 0; i < numValueStrings; i++) {
      valueXmstrings[i] =
       XmStringCreateLocalized(spinValueStrings[i]);
        }

        /* Create title label */

        labelString = XmStringCreateLocalized(“SpinBox Widget”);
        n = 0;
        XtSetArg(args[n], XmNlabelString, labelString); n++;
        titleLabel = XmCreateLabel(parent, “title”, args, n);
        XtManageChild(titleLabel);
        XmStringFree(labelString);

     /*
     * Create a SpinBox containing string values.
     */

        n = 0;
        XtSetArg(args[n], DtNvalues, valueXmstrings); n++;
        XtSetArg(args[n], DtNnumValues, numValueStrings); n++;
        XtSetArg(args[n], DtNcolumns, 10); n++;
        spinBox = DtCreateSpinBox(parent, “spinBox1”, args, n);
        XtManageChild(spinBox);

        /*
      * Create a SpinBox containing numeric values to 3 decimal places.
      * Position the arrows on either side of the displayed value.
      */

        n = 0;
        XtSetArg(args[n], DtNspinBoxChildType, DtNUMERIC); n++;
        XtSetArg(args[n], DtNminimumValue, 1000); n++;
        XtSetArg(args[n], DtNmaximumValue, 100000); n++;
        XtSetArg(args[n], DtNincrementValue,1000); n++;
        XtSetArg(args[n], DtNdecimalPoints,3); n++;
        XtSetArg(args[n], DtNposition,1000); n++;
        XtSetArg(args[n], DtNarrowLayout,DtARROWS_SPLIT); n++;
        XtSetArg(args[n], DtNcolumns, 10); n++;
        spinBox = DtCreateSpinBox(parent, “spinBox2”, args, n);
        XtManageChild(spinBox);

        /*
    * Create a SpinBox containing numeric values to 2 decimal places.
    * Position the arrows on the left of the displayed value.
    * Disallow alternate user changes by adding a modify/verify
     callback.
        */

        n = 0;
        XtSetArg(args[n], DtNspinBoxChildType, DtNUMERIC); n++;
        XtSetArg(args[n], DtNminimumValue, 1500); n++;
        XtSetArg(args[n], DtNmaximumValue, 60500); n++;
        XtSetArg(args[n], DtNincrementValue,1500); n++;
        XtSetArg(args[n], DtNdecimalPoints,2); n++;
        XtSetArg(args[n], DtNposition,7500); n++
     XtSetArg(args[n], DtNarrowLayout,DtARROWS_FLAT_BEGINNING); n++;
        XtSetArg(args[n], DtNcolumns, 10); n++;
        spinBox = DtCreateSpinBox(parent, “spinBox3”, args, n);
        XtManageChild(spinBox);

        XtAddCallback(spinBox, DtNmodifyVerifyCallback, ModifyVerifyCb,
     NULL);

     /*
     * Create a SpinBox containing string values.
     * Position the arrows on the left of the display value
     */

        n = 0;
        XtSetArg(args[n], DtNvalues, valueXmstrings); n++;
        XtSetArg(args[n], DtNnumValues, numValueStrings); n++;
        XtSetArg(args[n], DtNarrowLayout, DtARROWS_BEGINNING); n++;
        XtSetArg(args[n], DtNcolumns, 10); n++;
        spinBox = DtCreateSpinBox(parent, “spinBox4”, args, n);
        XtManageChild(spinBox);

       /*
       * Create a SpinBox containing numeric values to 3 decimal places.
       * Position the arrows on the right of the displayed value.
       */

        n = 0;
        XtSetArg(args[n], DtNspinBoxChildType, DtNUMERIC); n++;
        XtSetArg(args[n], DtNminimumValue, 1000); n++;
        XtSetArg(args[n], DtNmaximumValue, 100000); n++;
        XtSetArg(args[n], DtNincrementValue,1000); n++;
        XtSetArg(args[n], DtNdecimalPoints,3); n++;
        XtSetArg(args[n], DtNposition,1000); n++;
        XtSetArg(args[n], DtNarrowLayout, DtARROWS_FLAT_END); n++;
        XtSetArg(args[n], DtNcolumns, 10); n++;
        spinBox = DtCreateSpinBox(parent, “spinBox5”, args, n);
        XtManageChild(spinBox);

        /*
         * Free value strings, SpinBox has taken a copy.
         */

        for (i = 0; i < numValueStrings; i++) {
      XmStringFree(valueXmstrings[i]);
        }
        XtFree((char*)valueXmstrings);

    }

     /*
     * modify/verify callback.
     *
      * Allow/disallow alternate user changes
      */

    static void ModifyVerifyCb(Widget w, XtPointer cd, XtPointer cb)
    {
        DtSpinBoxCallbackStruct *scb= (DtSpinBoxCallbackStruct*)cb;
        static Boolean allowChange = True;

        scb->doit = allowChange;

        if (allowChange == False) {
     printf(“DtSpinBox: DtNmodifyVerifyCallback.
    Change disallowed.\n”);
     XBell(XtDisplay(w), 0);
        }

        allowChange = (allowChange == True) ? False: True;
    }

## Text Field and List Box Widget (DtComboBox)

Use the `DtComboBox` widget to display a list and the current selection from the list. You can use this widget for display only, or as a selectable control.

The `DtComboBox` widget is a combination of a text field and a list widget that provides a list of valid choices for the text field. Selecting an item from this list automatically fills in the text field with that list item. PG.widgs.mkr.14 shows examples of a `DtComboBox` widget.

### Examples of text field and list box widget (DtComboBox)

### Library and Header Files

The `DtComboBox` widget is in the `libDtWidget` library. The header file is `Dt/ComboBox.h`.

### Demo Program

A demo containing an example of the `DtComboBox` widget is in `/usr/dt/examples/dtwidget/controls.c`.

### Moving to XmComboBox

To use the Motif 2.1 `XmComboBox` widget, change the `Dt` names for the class, type, and creation routines to `Xm`. For example, change all occurrences of `DtComboBox` to `XmComboBox` in your code. Alternatively, you can compile your existing code with -DDT_USE_XM_COMBOBOX. This information is supplied in case you choose to revise your CDE 1.0 application to use the Motif 2.1 widget.

### Convenience Functions

The `DtComboBox` widget provides the following convenience functions, described in more detail in PG.widgs.mkr.10.

See the `DtComboBox`(3) man page for more information.

### DtComboBox Widget Convenience Functions

`Function` | `Description`
`DtCreateComboBox()` | Creates a `DtComboBox` widget.
`DtComboBoxAddItem()` | Adds an item into a `DtComboBox` widget at a specified position.
`DtComboBoxDeletePos()` | Deletes a specified item from a `DtComboBox` widget.
`DtComboBoxSetItem()` | Selects an item in the `XmList` of a `DtComboBox` widget and makes it the first visible item in the list.
`DtComboBoxSelectItem()` | Selects an item in the `XmList` of the `DtComboBox` widget.

`DtComboBox` is a subclass of the `XmManager` class that is used to display `XmList` or `XmScrolledList`.

### Classes

`DtComboBox` inherits behavior and resources from `Core`, `Composite`, `Constraints`, and `XmManager` classes.

The class pointer is `dtComboBoxWidgetClass`.

The class name is `DtComboBoxWidget`.

`DtComboBoxWidget` does not support subclassing.

### Resources

`DtComboBox` provides the following resources. PG.widgs.mkr.11 shows the class, type, default, and access for these resources.

- `DtNmarginHeight` specifies the number of pixels added between the top and bottom of the text widget and the start of the shadow.

- `DtNmarginWidth` specifies the number of pixels added between the right and left sides of the text widget and the start of the shadow.

- `DtNselectedItem` is passed through to the `XmList` to set the `XmNselectedItemCount` and `XmNselectedItems` as the single item in the `DtNitems` that matches this specified `XmString` in the list.

- `DtNselectedPosition` is passed through to the `XmList` to set the `XmNselectedItemCount` and `XmNselectedItems` as the single item at this specified position in the list.

- `DtNselectionCallback` is issued when an item is selected from the `DtComboBox` widget list.

- `DtNcomboBoxType` determines the style type of the `DtComboBox`.

The list widget ID is accessible using the `XtNameToWidget()` function. The resources of these widgets can be set. See the `DtComboBox`(3) man page for more information.

The codes in the access column show if you can:

- Set the resource at creation time (C)

- Set by using `XtSetValues` (S)

- Retrieve by using `XtGetValues` (G)

### DtComboBox Widget Resources

`Name` | `Class` | `Type` | `Default` | `Access`
`DtNmarginHeight` | `DtCMarginHeight` | `Dimension` | `2` | `CSG`
`DtNmarginWidth` | `DtCMarginWidth` | `Dimension` | `2` | `CSG`
`DtNselectedItem` | `DtCSelectedItem` | `XmString` | `Dimension` | `CSG`
`DtNselectedPosition` | `DtCSelectedPosition` | `int` | `Dimension` | `CSG`
`DtNselectionCallback` | `DtCCallback` | `XtCallbackList` | `XmString` | `C`
`DtNcomboBoxType` | `DtCComboBoxType` | `unsigned char` | `int` | `CG`

### Callback Structures

The callback structure follows and is described in PG.widgs.mkr.12.

    typedef struct {
     int  reason;
     XEvent *event;
     XmString item_or_text;
     int item_position;
    } DtComboBoxCallbackStruct;

### DtComboBox Callback Structures

`Structure` | `Description`
reason | The only reason to issue this callback is `XmCR_SELECT`.
event | A pointer to the event that caused this callback to be invoked. It can be NULL.
item_or_text | The contents of the text widget at the time the event invoked the callback. This data is only valid within the scope of the `call_data` structure, so it must be copied when it is used outside of this scope.
item_position | The new value of the `DtNposition` resource in the `DtComboBox` list. If the value is 0, the user entered a value in the `XmTextField` widget.

### Example of DtComboBox Widget

The following example shows how to create and use a `DtComboBox` widget. You can find this code as part of the `controls.c` demo in the `/usr/dt/examples/dtwidget` directory.

    /*
     * Example code for DtComboBox
     */

    #include <Dt/ComboBox.h>

    static char *comboValueStrings[] = {
     “alpha”, “beta”, “gamma”, “delta”,
     “epsilon”, “zeta”, “eta”, “theta”,
     “iota”, “kappa”, “lambda”, “mu”,
     “nu”, “xi”, “omicron”, “pi”,
     “rho”, “sigma”, “tau”, “upsilon”,
     “phi”, “chi”, “psi”, “omega”
    };

    static char *colorStrings[] = { “Red”, “Yellow”, “Green”, “Brown”,
    “Blue” };

    static void CreateComboBoxes(Widget parent)
    {
        Widget titleLabel, comboBox, list;
        XmString *valueXmstrings, *colorXmstrings;
        int numValueStrings, numColorStrings;
        XmString labelString, xmString;
        Arg args[20];
        int i, n;

        /* Create value compound strings */

        numValueStrings = XtNumber(comboValueStrings);
        valueXmstrings = (XmString *)XtMalloc(numValueStrings *
      sizeof(XmString*));
        for (i = 0; i < numValueStrings; i++) {
      valueXmstrings[i] =

      XmStringCreateLocalized(comboValueStrings[i]);
        }

        /* Create color compound strings */

     numColorStrings = XtNumber(colorStrings);
     colorXmstrings = (XmString *)XtMalloc(numColorStrings *
     sizeof(XmString*));
      for (i = 0; i < numColorStrings; i++) {
      colorXmstrings[i] =

      XmStringCreateLocalized(colorStrings[i]);
        }

        /* Create title label */

        labelString = XmStringCreateLocalized(“ComboBox Widget”);
        n = 0;
        XtSetArg(args[n], XmNlabelString, labelString); n++;
        titleLabel = XmCreateLabel(parent, “title”, args, n);
        XtManageChild(titleLabel);
        XmStringFree(labelString);

        /*
         * Create an editable ComboBox containing the color strings.
         * Get the widget id of the drop down list, add some greek
         * letter names to it, and make more items visible.
         */

        n = 0;
        XtSetArg(args[n], DtNcomboBoxType, DtDROP_DOWN_COMBO_BOX); n++;
        XtSetArg(args[n], DtNitems, colorXmstrings); n++;
        XtSetArg(args[n], DtNitemCount, numColorStrings); n++;
        XtSetArg(args[n], DtNvisibleItemCount, 5); n++;
        XtSetArg(args[n], DtNcolumns, 10); n++;
        comboBox = DtCreateComboBox(parent, “comboBox1”, args, n);
        XtManageChild(comboBox);

        list = XtNameToWidget(comboBox, “*List”);
        XmListAddItems(list, valueXmstrings, 10, 0);
        XtVaSetValues(list, XmNvisibleItemCount, 10, NULL);

        /*
         * Create an editable ComboBox with no entries.
         * Get the widget id of the drop down list, add some greek
         * letter names to it and select the third item in the list.
         */

        n = 0;
        XtSetArg(args[n], DtNcomboBoxType, DtDROP_DOWN_COMBO_BOX); n++;
        XtSetArg(args[n], DtNorientation, DtLEFT); n++;
        XtSetArg(args[n], DtNcolumns, 10); n++;
        comboBox = DtCreateComboBox(parent, “comboBox2”, args, n);
        XtManageChild(comboBox);

        list = XtNameToWidget(comboBox, “*List”);
        XmListAddItems(list, valueXmstrings, 7, 0);
        XtVaSetValues(list, XmNvisibleItemCount, 7, NULL);
        XtVaSetValues(comboBox, DtNselectedPosition, 3, NULL);

        /*
         * Create a non-editable ComboBox containing some greek letter

       names.
         * Position the arrow on the left.
         * Select the `gamma' item in the list.
         */

        n = 0;
        XtSetArg(args[n], DtNorientation, DtLEFT); n++;
        XtSetArg(args[n], DtNitems, valueXmstrings); n++;
        XtSetArg(args[n], DtNitemCount, numValueStrings); n++;
        XtSetArg(args[n], DtNvisibleItemCount, 8); n++;
        comboBox = DtCreateComboBox(parent, “comboBox3”, args, n);
        XtManageChild(comboBox);

        xmString = XmStringCreateLocalized(“gamma”);
        XtVaSetValues(comboBox, DtNselectedItem, xmString, NULL);
        XmStringFree(xmString);

        /*
         * Create a non-editable ComboBox with no entries.
         * Position the arrow on the right.
         * Add the greek letter names to the list and select the fourth
       item.
         */

        n = 0;
        XtSetArg(args[n], DtNorientation, DtRIGHT); n++;
        XtSetArg(args[n], DtNvisibleItemCount, 8); n++;
        comboBox = DtCreateComboBox(parent, “comboBox4”, args, n);
        XtManageChild(comboBox);

     for (i = 0; i < numValueStrings; i++) {
      DtComboBoxAddItem(comboBox, valueXmstrings[i],
      0, True);
        }
        XtVaSetValues(comboBox, DtNselectedPosition, 4, NULL);

        /*
         * Free value and color strings, ComboBox has taken a copy.
         */

     for (i = 0; i < numValueStrings; i++) {
      XmStringFree(valueXmstrings[i]);
        }
        XtFree((char*)valueXmstrings);

     for (i = 0; i < numColorStrings; i++) {
      XmStringFree(colorXmstrings[i]);
        }
        XtFree((char*)colorXmstrings);
    }

## Menu Button Widget (DtMenuButton)

Use the `DtMenuButton` widget to provide menu-cascading functionality outside of a menu pane.

`DtMenuButton` widget is a command widget that complements the menu
cascading functionality of an `XmCascadeButton` widget. As a complement to `XmCascadeButton` widget, it can only be instantiated outside a `MenuBar`, `Pulldown`, or `Popup` (use `XmCascadeButton` widget inside a `MenuPane`.) PG.widgs.mkr.9 shows examples of a `DtMenuButton` widget.

### Examples of menu button widget (DtMenuButton)

### Library and Header Files

The `DtMenuButton` widget is in the `libDtWidget` library. The header file is `Dt/MenuButton.h`.

### Demo Program

A demo containing an example of the `DtMenuButton` widget is in `/usr/dt/examples/dtwidget/controls.c`.

### Convenience Functions

`DtCreateMenuButton()` is a convenience function that creates a Common Desktop Environment widget.

`DtMenuButton` widget is a subclass of `XmLabel` class. Visually, `DtMenuButton` widget has a label string and a menu glyph. The menu glyph always appears on the right end of the widget and, by default, is a downward pointing arrow.

`DtMenuButton` widget has an implicitly created submenu attached to it. The submenu is a pop-up menu and has this `DtMenuButton` widget as its parent. The name of the implicitly created submenu is obtained by prefixing `submenu_` to the name of this `DtMenuButton` widget. You can obtain the widget ID of the submenu by setting an `XtGetValues` on `DtNsubMenuId` resource of this `DtMenuButton` widget. The implicitly created submenu must not be destroyed by the user of this widget.

The submenu can be popped up by pressing the menu post button (see `XmNmenuPost` resource of `XmRowColumn`) anywhere on the `DtMenuButton` widget or by pressing the Motif Cancel key (usually Escape).

### Classes

`DtMenuButtonWidget` inherits behavior and resources from `Core`, `XmPrimitive`, and `XmLabel` classes.

The class pointer is `dtMenuButtonWidgetClass`.

The class name is `DtMenuButtonWidget`.

`DtMenuButtonWidget` does not support subclassing.

### Resources

`DtMenuButtonWidget` provides the following resources. PG.widgs.mkr.15 shows the class, type, default, and access for these resources.

- `DtNcascadingCallback` specifies the list of callbacks that are called before the attached submenu is displayed.

- `DtNcascadePixmap` specifies the pixmap that is displayed as the menu glyph. If no pixmap is specified, a downward pointing arrow is displayed.

- `DtNsubMenuId` specifies the widget ID of the pop-up menu pane to be associated with this `DtMenuButton` widget. You must create the pop-up menu pane with this `DtMenuButton` as its parent. You cannot specify this resource when the widget is created because the submenu is automatically destroyed by this widget when the resource is set.

See the `DtMenuButtonWidget`(3) man page for more information.

The codes in the access column show if you can:

- Set the resource at creation time (C)

- Set by using `XtSetValues` (S)

- Retrieve by using `XtGetValues` (G)

### DtMenuButtonWidget Resources

`Name` | `Class` | `Type` | `Default` | `Access`
`DtNcascadingCallback` | `DtCCallback` | `XtCallbackList` | `NULL` | `C`
`DtNcascadePixmap` | `DtCPixmap` | `Pixmap` | `XmUNSPECIFIED_PIXMAP` | `CSG`
`DtNsubMenuId` | `DtCMenuWidget` | `Widget` | `NULL` | `SG`

### Callback Structures

The callback structure follows and is described in PG.widgs.mkr.16.

    typedef struct {
     int  reason;
     XEvent *event;
    } XmAnyCallbackStruct;

### DtMenuButtonWidget Callback Structures

`Structure` | `Description`
reason | Returns reason why the callback was invoked.
event | Points to the `XEvent` that triggered the callback or `NULL` if the callback was not triggered by an XEvent.

### Example of DtMenuButton Widget

The following example shows how to create and use a `DtMenuButton` widget. You can find this code as part of the `controls.c` demo in the `/usr/dt/examples/dtwidget` directory.

    /*
     * Example code for DtMenuButton
     */

    #include Dt/DtMenuButton.h

    /* MenuButton custom glyph */

    #define menu_glyph_width 16
    #define menu_glyph_height 16
    static unsigned char menu_glyph_bits[] = {
     0xe0, 0x03, 0x98, 0x0f, 0x84, 0x1f, 0x82, 0x3f, 0x82, 0x3f, 0x81,

     0x7f,
     0x81, 0x7f, 0xff, 0x7f, 0xff, 0x40, 0xff, 0x40, 0xfe, 0x20, 0xfe,

     0x20,
     0xfc, 0x10, 0xf8, 0x0c, 0xe0, 0x03, 0x00, 0x00};

    static void CreateMenuButtons(Widget parent)
    {
        Widget menuButton, submenu, titleLabel, button;
        Pixmap cascadePixmap;
        Pixel fg, bg;
        Cardinal depth;
        XmString labelString;
        Arg args[20];
        int i, n;

        /* Create title label */

        labelString = XmStringCreateLocalized(“MenuButton Widget”);
        n = 0;
        XtSetArg(args[n], XmNlabelString, labelString); n++;
        titleLabel = XmCreateLabel(parent, “title”, args, n);
        XtManageChild(titleLabel);
        XmStringFree(labelString);

        /*
         * Create a MenuButton.
         * Add push buttons to the built-in popup menu.
         */

        labelString = XmStringCreateLocalized(“Action”);
        n = 0;
        XtSetArg(args[n], XmNlabelString, labelString); n++;
     menuButton = DtCreateMenuButton(parent, “menuButton1”, args, n);
        XtManageChild(menuButton);
        XmStringFree(labelString);

        XtVaGetValues(menuButton, DtNsubMenuId, &submenu, NULL);
        button = XmCreatePushButton(submenu, “Push”, NULL, 0);
        XtManageChild(button);
        button = XmCreatePushButton(submenu, “Pull”, NULL, 0);
        XtManageChild(button);
        button = XmCreatePushButton(submenu, “Turn”, NULL, 0);
        XtManageChild(button);

        /*
         * Create a MenuButton.
         * Replace the built-in popup menu with a tear-off menu.
         * Add a custom pixmap in the colors of the MenuButton.
         */

        labelString = XmStringCreateLocalized(“Movement”);
        n = 0;
        XtSetArg(args[n], XmNlabelString, labelString); n++;
     menuButton = DtCreateMenuButton(parent, “menuButton1”, args, n);
        XtManageChild(menuButton);
        XmStringFree(labelString);

        /* Create a tear-off menu */

        n = 0;
        XtSetArg(args[0], XmNtearOffModel, XmTEAR_OFF_ENABLED); n++;
        submenu = XmCreatePopupMenu(menuButton, “submenu”, args, n);
        button = XmCreatePushButton(submenu, “Run”, NULL, 0);
        XtManageChild(button);
        button = XmCreatePushButton(submenu, “Jump”, NULL, 0);
        XtManageChild(button);
        button = XmCreatePushButton(submenu, “Stop”, NULL, 0);
        XtManageChild(button);

        XtVaSetValues(menuButton, DtNsubMenuId, submenu, NULL);

        /* Create a pixmap using the menu button's colors and depth */

        XtVaGetValues(menuButton,
       XmNforeground, &fg,
       XmNbackground, &bg,
       XmNdepth, &depth,
       NULL);

        cascadePixmap = XCreatePixmapFromBitmapData(XtDisplay
      (menuButton),DefaultRootWindow(XtDisplay
      (menuButton)),
      (char*)menu_glyph_bits,
      menu_glyph_width, menu_glyph_height,
      fg, bg, depth);
        XtVaSetValues(menuButton, DtNcascadePixmap, cascadePixmap,

     NULL);
    }

## Text Editor Widget (DtEditor)

The Common Desktop Environment text editing system consists of two components:

- The text editor client, `dtpad`, which provides editing services through graphical, action, and ToolTalk interfaces.

- The editor widget, `DtEditor`(3), which provides a programmatic interface for the following editing services:

  - Cut and paste

  - Search and replace

  - Simple formatting

  - Spell checking (for 8-bit locales)

  - Undo previous edit

  - Enhanced I/O handling capabilities that support input and output of ASCII text, multibyte text, and buffers of data

  - Support for reading and writing files directly

Although the Motif text widget also provides a programmatic interface, applications that use the system-wide uniform editor should use the `DtEditor`(3) widget. The Common Desktop Environment Text Editor and Mailer use the editor widget. Use this widget in the following circumstances:

1. You want the functionality, such as spell checking, undo, and find/change, that is provided by the `DtEditor`(3) widget.

2. You do not want to write the code so that users may read and write data to and from a file.

3. Your program does not need to examine every character typed or every cursor movement made by a user.

This section describes the text editor widget, `DtEditor`(3).

The Editor Widget library provides support for creating and editing text files. It enables applications running in the desktop environment to have a consistent method of editing text data. The `DtEditor`(3) widget consists of a scrolled edit window for text, an optional status line, and dialogs for finding and changing text, spell checking, and specifying formatting options. The text editor widget includes a set of convenience functions for programmatically controlling the widget.

### Library and Header Files

The `DtEditor` widget is in the `libDtWidget` library. The header file is `Dt/Editor.h`.

### Demo Program

A demo containing an example of the `DtEditor` widget is in `/usr/dt/examples/dtwidget/editor.c`.

### Classes

Widget subclassing is not supported for the `DtEditor` widget class.

`DtEditor` inherits behavior and resources from `Core`, `Composite`, `Constraints`, `XmManager`, and `XmForm` classes.

The class name for the editor widget is `DtEditorWidget`.

The class pointer is `dtEditorWidgetClass`.

### Convenience Functions

The `DtEditor` convenience functions are described in the following tables.

#### Life Cycle Functions

The `DtEditor` life cycle functions are described in PG.widgs.mkr.18.

#### DtEditor Life Cycle Functions

`Function` | `Description`
`DtCreateEditor` | Creates a new instance of a `DtEditor` widget and its children.
`DtEditorReset` | Restores a `DtEditor` widget to its initial state.

#### Input/Output Functions

The `DtEditor` input/output functions are described in PG.widgs.mkr.19.

#### DtEditor Input/Output Functions

`Function` | `Description`
`DtEditorAppend` | Appends content data to the end of an editor widget.
`DtEditorAppendFromFile` | Appends the contents of a file to the end of an editor widget.
`DtEditorGetContents` | Retrieves the entire contents of an editor widget.
`DtEditorInsert` | Inserts content data at the current insert position.
`DtEditorInsertFromFile` | Inserts the contents of a file at the current insert position.
DtEditorReplace | Replaces a portion of text with the supplied data.
DtEditorReplaceFromFile | Replaces a portion of text with the contents of a file.
`DtEditorSaveContentsToFile` | Saves the entire contents to a file.
`DtEditorSetContents` | Loads content data into an editor widget, replacing the entire contents of the widget.
`DtEditorSetContentsFromFile` | Loads the contents of a file into an editor widget, replacing the entire contents of the widget.

#### Selection Functions

The `DtEditor` selection functions are described in PG.widgs.mkr.20.

#### DtEditor Selection Functions

`Function` | `Description`
`DtEditorClearSelection` | Replaces the currently selected contents with blanks.
`DtEditorCopyToClipboard` | Copies the currently selected contents to the clipboard.
`DtEditorCutToClipboard` | Removes the currently selected contents, placing then on the clipboard.
`DtEditorDeleteSelection` | Removes the currently selected contents.
`DtEditorDeselect` | Deselects any selected contents.
`DtEditorPasteFromClipboard` | Pastes the contents of the clipboard into an editor widget, replacing any currently selected contents.
`DtEditorSelectAll` | Selects the entire contents of an editor widget.

#### Format Functions

The `DtEditor` format functions are described in PG.widgs.mkr.21.

#### DtEditor Format Functions

`Function` | `Description`
`DtEditorFormat` | Formats all or part of the contents of an editor widget.
`DtEditorInvokeFormatDialog` | Displays the format dialog box that enables the user to specify format settings for margins and justification style and to perform formatting operations.

#### Find and Change Functions

The `DtEditor` find and change functions are described in PG.widgs.mkr.22.

#### DtEditArea Find and Change Functions

`Function` | `Description`
`DtEditorChange` | Changes one or all occurrences of a string.
`DtEditorFind` | Finds the next occurrence of a string.
`DtEditorInvokeFindChangeDialog` | Displays the dialog box that enables the user to search for, and optionally change, a string.
`DtEditorInvokeSpellDialog` | Displays a dialog box with a list of misspelled words in the current contents.

#### Auxiliary Functions

The `DtEditor` auxiliary functions are described in PG.widgs.mkr.23.

#### DtEditor Auxiliary Functions

`Function` | `Description`
`DtEditorCheckForUnsavedChanges` | Reports whether the contents of an editor widget have been altered since the last time they were retrieved or saved.
DtEditorDisableRedisplay | Prevents redisplay of an editor widget even though its visual attributes have changed.
DtEditorEnableRedisplay | Forces the visual update of an editor widget.
`DtEditorGetInsertPosition` | Returns the insertion cursor position of the editor widget.
`DtEditorGetLastPosition` | Returns the position of the last character in the edit window.
`DtEditorGetMessageTextFieldID` | Retrieves the widget ID of the text field widget used to display application messages.
`DtEditorGetSizeHints` | Retrieves sizing information from an editor widget.
`DtEditorGoToLine` | Moves the insertion cursor to the specified line.
`DtEditorSetInsertionPosition` | Sets the position of the insertion cursor.
`DtEditorTraverseToEditor` | Sets keyboard traversal to the edit window of an editor widget.
`DtEditorUndoEdit` | Undoes the last edit made by a user.

### Resources

The `DtEditor` widget provides the following set of resources.

- `DtNautoShowCursorPosition` ensures that the text visible in the scrolled edit window contains the insert cursor when set to True. If the insert cursor changes, the contents of the editor may scroll to bring the insertion point into the window.

- `DtNblinkRate` specifies the blink rate of the text cursor in milliseconds. The time it takes to blink the insertion cursor on and off is twice the blink rate. When the blink rate is set to zero, the cursor does not blink. The value must not be negative.

- `DtNbuttonFontList` specifies the font list used for the buttons that are displayed in the dialog boxes of `DtEditor`.

- `DtNcolumns` specifies the initial width of the editor as an integer number of characters. The value must be greater than zero.

- `DtNcursorPosition` specifies the location of the current insert cursor in the editor where the current insert cursor is placed. Position is determined by the number of characters from the beginning of the text. The first character position is 0.

- `DtNcursorPositionVisible` marks the insert cursor position by a blinking text cursor when the Boolean value is True.

- `DtNdialogTitle` specifies the title for all dialogs displayed by DtEditor. These include the dialogs for word search and replace, misspelled words, and format settings.

- `DtNeditable` indicates that the user can edit the data when set to True. Prohibits the user from editing data when set to False.

- `DtNlabelFontList` specifies the font list used for `DtEditor` labels (the labels are displayed in the status line and `DtEditor` dialog boxes).

- `DtNoverstrike` when set to False, characters typed into the editor widget inserts at the position of the cursor (the default). When set to True, characters typed into the editor widget replace the characters that directly follow the insertion cursor. When the end of the line is reached, characters are appended to the end of the line. If the status line is visible, the `DtNoverstrikeIndicatorLabel` is displayed in the status line whenever `DtNoverstrike` is True.

- `DtNrows` specifies the initial height of the editor measured in character heights. The value must be greater than zero.

- `DtNscrollHorizontal` adds a scroll bar that enables the user to scroll horizontally through text when the Boolean value is True.

- `DtNscrollLeftSide` puts a vertical scroll bar on the left side of the scrolled edit window when the Boolean value is True.

- `DtNshowStatusLine` displays a status line below the text window when set to True. The status line contains a field that displays the current line number of the insert cursor, total number of lines in the document, and whether the editor is in overstrike mode. Users can type a line number in the line number display to go directly to that line.

The status line also includes a Motif `XmTextField`(3) widget for displaying messages supplied by an application. This field is a convenient place for an application to display status and feedback about the document being edited. The ID of the text field is retrieved using `DtEditorGetMessageTextFieldID`(3). A message is displayed by setting the `XmNvalue` or `XmNvalueWcs` resource of this widget. If the text field is not needed, you can unmanage it by calling `XtUnmanageWidget`(3) with its ID.

- `DtNspellFilter` specifies the filter used to identify spelling errors. The function `DtEditorInvokeSpellDialog`(3) filters the contents of an editor through the filter specified by `DtNspellFilter`. The filter specified should accept a file name and produce a list of misspelled and unrecognized words in this file on `stdout`. The default filter is `spell`(1).

- `DtNtextBackground` specifies the background for the edit window.

- `DtNtextDeselectCallback` specifies a function called whenever no text is selected within the edit area. The reason sent by the callback is `DtEDITOR_TEXT_DESELECT`.

- `DtNtextFontList` specifies the font list used for the `DtEditor` edit window and its text fields. The text fields are displayed in the status line and `DtEditor` dialog boxes.

- `DtNtextForeground` specifies the foreground for the edit window.

- `DtNtextSelectCallback` specifies a function called whenever text is selected within the edit area. The reason sent by the callback is `DtEDITOR_TEXT_SELECT`.

- `DtNtextTranslations` specifies translations that are added to the edit window. Translations specified with this resource override any duplicate translations defined for the edit window. See the `DtEditor`(3) man page for a list of translations provided by `DtEditor`.

- `DtNtopCharacter` displays the line that contains the position of text at the top of the scrolled edit window. The line is displayed at the top of the widget without shifting the text left or right. Position is determined by the number of characters from the beginning of the text. The first character position is zero.

  `XGetValues`(3) for `DtNtopCharacter` returns the position of the first character in the line that is displayed at the top of the widget.

- `DtNwordWrap` breaks lines at word breaks with soft carriage returns when they reach the right edge of the window. Note that word wrap affects only the visual appearance of the contents of an editor widget. The line breaks (soft carriage returns) are not physically inserted into the text. The editor does support substituting hard carriage returns when the contents of the widget are retrieved or saved to a file. See the `DtEditorGetContents`(3) and `DtEditorSaveContentsToFile`(3) man pages for more information.

PG.widgs.mkr.24 lists the class, type, default, and access for each resource. You can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or class in an `.Xdefaults` file, remove the `DtN` or `DtC` prefix and use the remaining letters. To specify one of the defined values for a resource in an `.Xdefaults` file, remove the `Dt` prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words).

The codes in the access column show if you can:

- Set the resource at creation time (C)

- Set by using `XtSetValues` (S)

- Retrieve by using `XtGetValues` (G)

See the `DtEditor`(3) man page for more information.

### DtEditor Resources

`Name` | `Class` | `Type` | `Default` | `Access`
`DtNautoShowCursorPosition` | `DtCAutoShowCursorPosition` | `Boolean` | `True` | `CSG`
`DtNblinkRate` | `DtCBlinkRate` | `int` | `500` | `CSG`
DtNbuttonFontList | DtCFontList | XmFontList | Dynamic | CSG
`DtNcolumns` | `DtCColumns` | `XmNcolumns` | `Dynamic` | `CSG`
`DtNcursorPosition` | `DtCCursorPosition` | `XmTextPosition` | `0` | `CSG`
`DtNcursorPositionVisible` | `DtCCursorPositionVisible` | `Boolean` | `True` | `CSG`
`DtNdialogTitle` | `DtCDialogTitle` | `XmString` | `NULL` | `CSG`
`DtNeditable` | `DtCEditable` | `Boolean` | `True` | `CSG`
DtNlabelFontList | DtCFontList | XmFontList | Dynamic | CSG
`DtNmaxLength` | `DtCMaxLength` | `int` | `Largest integer` | `CSG`
`DtNoverstrike` | `DtCOverstrike` | `Boolean` | `False` | `CSG`
`DtNrows` | `DtCRows` | `XmNrows` | `Dynamic` | `CSG`
`DtNscrollHorizontal` | `DtCScroll` | `Boolean` | `True` | `CG`
`DtNscrollLeftSide` | `DtCScrollSide` | `Boolean` | `Dynamic` | `CG`
`DtNscrollTopSide` | `DtCScrollSide` | `Boolean` | `False` | `CG`
`DtNscrollVertical` | `DtCScroll` | `Boolean` | `True` | `CG`
`DtNshowStatusLine` | `DtCShowStatusLine` | `Boolean` | `False` | `CSG`
`DtNspellFilter` | `DtCspellFilter` | `char *` | `Spell` | `CSG`
`DtNtextBackground` | `DtCBackground` | `Pixel` | `Dynamic` | `CSG`
`DtNtextDeselectCallback` | `DtCCallback` | `XtCallbackList` | `NULL` | `C`
DtNtextFontList | DtCFontList | XmFontList | Dynamic | CSG
`DtNtextForeground` | `DtCForeground` | `Pixel` | `Dynamic` | `CSG`
DtNtextTranslations | DtCTranslations | XtTranslations | NULL | CS
`DtNtextSelectCallback` | `DtCCallback` | `XtCallbackList` | `NULL` | `C`
`DtNtopCharacter` | `DtCTextPosition` | `XmTextPosition` | `0` | `CSG`
`DtNwordWrap` | `DtCWordWrap` | `Boolean` | `True` | `CSG`

### Inherited Resources

`DtEditor` inherits behavior and resources from the following superclasses:

- `XmForm`

- `XmManager`

- `Composite`

- `Core`

Refer to the appropriate man page for more information.

### Localization Resources

The following list describes a set of widget resources that are designed for localization of the `DtEditor` widget and its dialog boxes. Default values for these resources depend on the locale.

- `DtNcenterToggleLabel` specifies the label for the center alignment toggle button in the Format Settings dialog box. The default value in the C locale is Center.

- `DtNchangeAllButtonLabel` specifies the label for the button in the Find/Change dialog box that changes all occurrences of the Find string in the document. The default value in the C locale is Change All.

- `DtNchangeButtonLabel` specifies the label for the button in the Find/Change dialog box that changes the next occurrence of the find string in the document. The default value in the C locale is Change.

- `DtNchangeFieldLabel` specifies the label for the field in the Find/Change dialog box where the user specifies the replacement string. The default value in the C locale is Change To.

- `DtNcurrentLineLabel` specifies the label for the current line number field in the status line. The default value in the C locale is Line.

- `DtNfindButtonLabel` specifies the label for the button in the Find/Change dialog box that finds the next occurrence of the find string in the document. The default value in the C locale is Find.

- `DtNfindChangeDialogTitle` specifies the title for the Find/Change dialog box. If `DtNdialogTitle` is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Find/Change.

- `DtNfindFieldLabel` specifies the label for the field in the Find/Change dialog box where the user specifies the search string. The default value in the C locale is Find.

- `DtNformatAllButtonLabel` specifies the label for the button in the Format Settings dialog box that formats the complete document. The default value in the C locale is All.

- `DtNformatParagraphButtonLabel` specifies the label for the button in the Format Settings dialog box that formats the paragraph containing the insertion cursor. The default value in the C locale is Paragraph.

- `DtNformatSettingsDialogTitle` specifies the title for the Format Settings dialog box. If DtNdialogTitle is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Format Settings.

- `DtNinformationDialogTitle` specifies the title for the Information dialog box that is used to present feedback and general information to the user. If `DtNdialogTitle` is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Information.

- `DtNjustifyToggleLabel` specifies the label for the justify alignment toggle button in the Format Settings dialog box. The default value in the C locale is Justify.

- `DtNleftAlignToggleLabel` specifies the label for the left alignment toggle button in the Format Settings dialog box. The default value in the C locale is Left Align.

- `DtNleftMarginFieldLabel` specifies the label for the left margin value field in the Format Settings dialog box. The default value in the C locale is Left Margin.

- `DtNmisspelledListLabel` specifies the label for the list of unrecognized and misspelled words in the Spell dialog box. The default value in the C locale is Misspelled Words.

- `DtNoverstrikeLabel` specifies the label in the status line that shows that the editor is in overstrike mode. The default value in the C locale is Overstrike.

- `DtNrightAlignToggleLabel` specifies the label for the right alignment toggle button in the Format Settings dialog box. The default value in the C locale is Right Align.

- `DtNrightMarginFieldLabel` specifies the label for the right margin value field in the Format Settings dialog box. The default value in the C locale is Right Margin.

- `DtNspellDialogTitle` specifies the title for the Format Settings dialog box. If `DtNdialogTitle` is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Spell.

- `DtNtotalLineCountLabel` specifies the label for the display as part of the status line that shows the total number of lines in the document. The default value in the C locale is Total.

PG.widgs.mkr.25 lists the class, type, default, and access for each of the localization resources. The codes in the access column show if you can:

- Set the resource at creation time (C)

- Set by using `XtSetValues` (S)

- Retrieve by using `XtGetValues` (G)

See the `DtEditor`(3) man page for more information.

### DtEditor Localization Resources

`Name` | `Class` | `Type` | `Default` | `Access`
`DtNcenterToggleLabel` | `DtCCenterToggleLabel` | `XmString` | `Dynamic` | `CSG`
`DtNchangeAllButtonLabel` | `DtCChangeAllButtonLabel` | `XmString` | `Dynamic` | `CSG`
`DtNchangeButtonLabel` | `DtCChangeButtonLabel` | `XmString` | `Dynamic` | `CSG`
`DtNchangeFieldLabel` | `DtCChangeFieldLabel` | `XmString` | `Dynamic` | `CSG`
`DtNcurrentLineLabel` | `DtCCurrentLineLabel` | `XmString` | `Dynamic` | `CSG`
`DtNfindButtonLabel` | `DtCFindButtonLabel` | `XmString` | `Dynamic` | `CSG`
`DtNfindChangeDialogTitle` | `DtCFindChangeDialogTitle` | `XmString` | `Dynamic` | `CSG`
`DtNfindFieldLabel` | `DtCFindFieldLabel` | `XmString` | `Dynamic` | `CSG`
`DtNformatAllButtonLabel` | `DtCFormatAllButtonLabel` | `XmString` | `Dynamic` | `CSG`
`DtNformatParagraphButtonLabel` | `DtCFormatParagraphButtonLabel` | `XmString` | `Dynamic` | `CSG`
`DtNformatSettingsDialogTitle` | `DtCFormatSettingsDialogTitle` | `XmString` | `Dynamic` | `CSG`
`DtNinformationDialogTitle` | `DtCInformationDialogTitle` | `XmString` | `Dynamic` | `CSG`
`DtNjustifyToggleLabel` | `DtCJustifyToggleLabel` | `XmString` | `Dynamic` | `CSG`
`DtNleftAlignToggleLabel` | `DtCLeftAlignToggleLabel` | `XmString` | `Dynamic` | `CSG`
`DtNleftMarginFieldLabel` | `DtCLeftMarginFieldLabel` | `XmString` | `Dynamic` | `CSG`
`DtNmisspelledListLabel` | `DtCMisspelledListLabel` | `XmString` | `Dynamic` | `CSG`
`DtNoverstrikeLabel` | `DtCOverstrikeLabel` | `XmString` | `Dynamic` | `CSG`
`DtNrightAlignToggleLabel` | `DtCRightAlignToggleLabel` | `XmString` | `Dynamic` | `CSG`
`DtNrightMarginFieldLabel` | `DtCRightMarginFieldLabel` | `XmString` | `Dynamic` | `CSG`
`DtNspellDialogTitle` | `DtCSpellDialogTitle` | `XmString` | `Dynamic` | `CSG`
`DtNtotalLineCountLabel` | `DtCTotalLineCountLabel` | `XmString` | `Dynamic` | `CSG`

### Callback Functions

The `DtEditor` widget supports three callback functions:

- `DtEditorNHelpCallback`

- `DtNtextSelectCallback`

- `DtNtextDeselectCallback`

If you want to present help information about the editor widget and its dialog boxes, set the `XmNhelpCallback` resource and use the reason field passed as part of `DtEditorHelpCallbackStruct` to set the contents of the Help dialog box. A pointer to the following structure is passed to `XmNHelpCallback`. The callback structure and is described in PG.widgs.mkr.26.

    typedef struct {
     int       reason;
     XEvent    *event;
    } DtEditorHelpCallbackStruct;

### DtEditorHelp Callback Structure

`Structure` | `Description`
reason | The reason why the callback was invoked. Refer to the `DtEditor`(3) man page for a list of reasons.
event | A pointer to the event that invoked this callback. The value can be NULL.

Use the `DtNtextSelectCallback` and `DtNtextDeselectCallback` resources when you want to enable and disable menu items and commands depending on whether text is selected. `DtNtextSelectCallback` specifies a function that is called whenever some text is selected in the edit window. `DtNtextDeselectCallback` specifies a function that is called whenever no text is selected within the edit window. The reasons sent by the callbacks are `DtEDITOR_TEXT_SELECT` and `DtEDITOR_TEXT_DESELECT`.