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. Figure 7-2 “Example of text field and list box widget (DtComboBox)” shows examples of a DtComboBox widget.

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

Figure 7-3 Example 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 Table 7-4 “DtComboBox Widget Convenience Functions”

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

Table 7-4 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. Table 7-5 “DtComboBox Widget Resources” 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)

Table 7-5 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.

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

Table 7-6 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);
}

Text Field and List Box Widget (DtComboBox)

Technical documentation

» Table of Contents

» Glossary

» Index