HP OpenVMS Systems Documentation

7 Common Desktop Environment Motif Widgets

Using Common Desktop Environment Motif

Motif Libraries

Features Added to Motif

Enhancements to Existing Motif Functionality

Visual Enhancements

Text Field and Arrow Button Widget (DtSpinBox)

Library and Header Files

Demo Program

Compatibility with Motif 2.0

Convenience Functions

Classes

Resources

Callback Structures

Example of DtSpinBox Widget

Text Field and List Box Widget (DtComboBox)

Library and Header Files

Demo Program

Compatibility with Motif 2.0

Convenience Functions

Classes

Resources

Callback Structures

Example of DtComboBox Widget

Menu Button Widget (DtMenuButton)

Library and Header Files

Demo Program

Convenience Functions

Classes

Resources

Callback Structures

Example of DtMenuButton Widget

Text Editor Widget (DtEditor)

Library and Header Files

Demo Program

Classes

Convenience Functions

Resources

Inherited Resources

Localization Resources

Callback Functions

OPEN LOOK and

The widget library, libDtWidget, contains four widgets that combine or enhance functionality of existing Motif 1.2 widgets:

• DtSpinBox combines a text field and arrow buttons in a control that can increment or decrement numeric or text values.

• DtComboBox combines a text field and a list box in a control that displays one of the many valid choices for the text field.

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

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

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 Common Desktop Environment Motif

Common Desktop Environment Motif adds functionality to the Motif 1.2.3 release while maintaining source compatibility. Common Desktop Environment Motif is source and binary compatible with Motif 1.2 applications. Existing Motif 1.2 applications will compile using Common Desktop Environment Motif. Existing Motif 1.2 binaries will run without modification using Common Desktop Environment Motif.

Common Desktop Environment Motif also provides four custom widgets not found in Motif 1.2. The custom widgets are described in detail in this chapter.

Motif Libraries

Motif Library (libXm)

Motif UIL Library (libUil)

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

Motif Resource Manager Library (libMrm)

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

Features Added to Motif

• Complete internationalization of toolkit error messages.

• XmGetPixmap() and XmGetPixmapByDepth() use the environment variable XMICONSEARCHPATH or XMICONBMSEARCHPATH as the icon search path. If neither of these variables is set, XBMLANGPATH is used, which governs the Motif 1.2 behavior.See Common Desktop Environment Motif man page for more information.

Enhancements to Existing Motif Functionality

• 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.

Visual Enhancements

• 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.

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)

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. Figure 7-1 shows examples of the DtSpinBox widget.

Figure 7-1 Examples of the DtSpinBox widget

Library and Header Files

Demo Program

Compatibility with Motif 2.0

Convenience Functions

Table 7-1 DtSpinBox Convenience Functions

Classes

The class pointer is dtSpinBoxWidgetClass.

The class name is DtSpinBoxWidget.

DtSpinBoxWidget does not support subclassing.

Resources

• 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.

Table 7-2 DtSpinBoxWidget Resources

Callback Structures

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

Example of DtSpinBox Widget

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

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. Figure 7-2 shows examples of a DtComboBox widget.

Figure 7-2 Examples of text field and list box widget (DtComboBox)

Library and Header Files

Demo Program

Compatibility with Motif 2.0

Convenience Functions

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

DtComboBox Widget Convenience Functions

Table 7-4 DtComboBox Widget Convenience Functions

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

Classes

The class pointer is dtComboBoxWidgetClass.

The class name is DtComboBoxWidget.

DtComboBoxWidget does not support subclassing.

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 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)

Callback Structures

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

Example of DtComboBox Widget

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

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.) Figure 7-3 shows examples of a DtMenuButton widget.

Figure 7-3 Examples of menu button widget (DtMenuButton)

Library and Header Files

Demo Program

Convenience Functions

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

The class pointer is dtMenuButtonWidgetClass.

The class name is DtMenuButtonWidget.

DtMenuButtonWidget does not support subclassing.

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.

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)

Callback Structures

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

Example of DtMenuButton Widget

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

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.

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

Demo Program

Classes

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

Life Cycle Functions

Table 7-9 DtEditor Life Cycle Functions

Input/Output Functions

Table 7-10 DtEditor Input/Output Functions

Selection Functions

Table 7-11 DtEditor Selection Functions

Format Functions

Table 7-12 DtEditor Format Functions

Find and Change Functions

Table 7-13 DtEditArea Find and Change Functions (Continued)

Auxiliary Functions

Table 7-14 DtEditor Auxiliary Functions

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.

• 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(3X) 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.

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)

Table 7-15 DtEditor Resources

Inherited Resources

• XmForm
• XmManager
• Composite
• Core

Localization Resources

• 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.

• Set the resource at creation time (C)
• Set by using XtSetValues (S)
• Retrieve by using XtGetValues (G)

Table 7-16 DtEditor Localization Resources (Continued)

Callback Functions

• DtEditorNHelpCallback
• DtNtextSelectCallback
• DtNtextDeselectCallback

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

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.