The ComboBox widget manages both a List widget and a TextField widget. This combination of List and TextField gives users two ways to choose an item. The user can choose an item either by selecting one of the entries displayed by the List widget or by typing the selection directly into the TextField widget.
By default, the ComboBox displays both the TextField widget and the List widget. However, it is possible to hide the List widget so that it will only be displayed when the user requests it. If the List is hidden, the user can make it visible by clicking on a displayed arrow.
The TextField can either be editable or non-editable. If the TextField is non-editable, the user must pick one of the choices displayed by the List.
Motif provides three types of ComboBox widgets. The widget
type is specified using the XmNcomboBoxType resource on ComboBox. The possible
settings for this resource are as shown in Table 4.
Table 4. XmNcomboBoxType Resource Values
| Value | TextField | List Widget |
| XmCOMBO_BOX | Editable | Always displayed |
| XmDROP_DOWN_COMBO_BOX | Editable | Hidden |
| XmDROP_DOWN_LIST | Non-editable | Hidden |
XmDROP_DOWN_LIST is the default value.
ComboBoxes with hidden Lists are usually more desirable when screen space is limited. ComboBoxes with hidden Lists are also recommended when users are more likely to enter text into the TextField than to choose an item from the List.
Motif provides the following three convenience functions for creating ComboBoxes:
Each function creates an instance of a ComboBox widget and returns its associated widget ID.
Each function requires an arglist parameter. The resource values specified in arglist will be passed not only to the ComboBox, but to the List and TextField as well. Thus, an application can specify resources for the List such as XmNitems and XmNvisibleItemCount by including them in the arglist parameter passed to the ComboBox.
The List part of the ComboBox expects an array of compound strings to fill the list. If an array is not passed to the List at creation time, the application must provide this array later. Each string becomes an item in the list, with the first string becoming the item in position 1, the second string becoming the item in position 2, and so on. Your application can obtain the XmList widget ID by specifying *List as an argument to XtNameToWidget( ). Similarly, the TextField widget in the ComboBox can be accessed by passing *Text to XtNameToWidget( ). You can then call a convenience function, such as XmListAddItem, to add more List items. You can also access the List and TextField widgets through the XmNlist and XmNtextField resources, but these resources are read-only.
If the TextField widget is editable, the user can type directly in the text field to enter a selection. If the application wishes to validate the entered text, it can do so by installing the XmNmodifyVerifyCallback on the TextField widget directly.
The following example illustrates how to create a drop-down ComboBox containing five items. It illustrates how to use the XmCreateComboBox( ) function, and how to pass its children resources at creation time. This example uses XtNameToWidget( ) to manipulate the List child, setting the List child's XmNvisibleItemCount to 5.
{
#define NUM_LIST_ITEMS 5
Widget comboBox;
Arg args[10];
Cardinal n, i;
XmString ListItem[NUM_LIST_ITEMS];
static char *ListString[] = { "kiwi",
"raspberry",
"carambola",
"litchi",
"coconut" };
/* Create a list of XmStrings for the ComboBox List child */
for (i=0; i < NUM_LIST_ITEMS; i++)
ListItem[i] = XmStringCreate (ListString[i],
XmSTRING_DEFAULT_CHARSET);
/* Create a ComboBox of type XmDROP_DOWN_COMBO_BOX. */
/* Resources passed to ComboBox are passed on to the
* children of ComboBox. So, in the argument list
* below, the resources, XmNitems, and XmNitemCount
* will be passed on to the List child of ComboBox. */
n=0;
XtSetArg (args[n], XmNcomboBoxType, XmDROP_DOWN_COMBO_BOX); n++;
XtSetArg (args[n], XmNarrowSpacing, 5); n++;
XtSetArg (args[n], XmNitems, ListItem); n++;
XtSetArg (args[n], XmNitemCount, NUM_LIST_ITEMS); n++;
comboBox = XmCreateComboBox (parent, "ComboBox", args, n);
XtManageChild (comboBox);
XtAddCallback (comboBox, XmNselectionCallback, SelectionCB,
(XtPointer)NULL);
/* Example of manipulating a child widget directly to set the
* visibleItemCount on the list. */
n=0;
XtSetArg (args[n], XmNvisibleItemCount, 5); n++;
XtSetValues (XtNameToWidget (comboBox,"*List"), args, n);
}
You may add and manipulate Combobox items using the functions
All of these functions take a widget ID that specifies the ComboBox; none returns a value.
If a ComboBox has a hidden List, then the ComboBox displays an arrow. The arrow will always be displayed adjacent to the TextField. However, the placement of this arrow depends on the XmNlayoutDirection resource of the VendorShell (or subclass of) in which the ComboBox is contained, as follows:
Use XmNarrowSize to set the requested size of the arrow. Use XmNarrowSpacing to set the spacing between the arrow and the TextField.
Note that XmNarrowSize is a size request, not a size guarantee. For example, if the requested arrowSize is larger than the current size of the ComboBox, ComboBox will have to make a geometry request to its parent. Whether the geometry request is wholly, partially, or not accepted depends on the parent. If this request is accepted, the arrow size request can be granted. If the ComboBox's request to grow is only partially granted or not granted at all, ComboBox will make the arrow size the maximum that will fit inside the ComboBox's allowed size.
If the ComboBox does not have an editable TextField, any text that the user types will not appear in the TextField. Instead, typing text may cause a matching algorithm to be invoked that will attempt to match the entered text with an item in the list. If a match is found, the item is selected, and the item appears in the TextField field of the ComboBox. Whether a specific matching algorithm is applied or not is determined by the value of the XmNmatchBehavior resource on ComboBox. There are two values that the XmNmatchBehavior resource can accept: XmNONE and XmQUICK_NAVIGATE. A value of XmNONE indicates that no matching algorithm will be invoked. A value of XmQUICK_NAVIGATE indicates that when the List widget has focus, a one-character navigation is supported. In this algorithm, if the typed character is the initial character of some item in the XmList, this algorithm causes that item to be navigated to and selected. Subsequently typing the same character will cycle among the items with the same first character.
When a selection occurs in ComboBox, the XmNselectionCallback callbacks are called. For example, the code fragment appearing earlier in this section established a selection callback procedure named SelectionCB. Here is the code for that callback:
void
SelectionCB (Widget w, XtPointer client_data, XtPointer call_data)
{
XmComboBoxCallbackStruct *cb = (XmComboBoxCallbackStruct *)call_data;
XmStringCharSet charset;
XmStringDirection direction;
XmStringContext context;
Boolean separator;
char *item;
/* This callback procedure prints the item that was just selected. */
/* Retrieve the selected text string from XmString. */
item = XmStringUnparse(cb->item_or_text, NULL, XmCHARSET_TEXT,
XmCHARSET_TEXT, NULL, 0, XmOUTPUT_ALL);
printf ("ComboBox SelectionCB: item = %s\n\n", item);
}
ComboBox allows a single item to be selected in many ways, including through a matching behavior. A list item can more directly be selected by scrolling to it with either the mouse or keyboard, and selecting the item directly. ComboBox supports the Browse Select selection method of XmList. If the ComboBox has an editable text field, the selection can be typed directly into the TextField entry field. Regardless of the selection mechanism used, when an item in the list is selected, the list item is highlighted by displaying it in reverse colors, and the selected item is displayed in the TextField field in the ComboBox.
Additionally, if the user performs an action that moves focus away from the ComboBox, the XmNselectionCallbacks are called to notify the application of the user's choice. The item_or_text field in the call data structure passed to the callback will contain the contents of the TextField field at the time of the callback. The application then takes whatever action is required for the specified selection.
The XmComboBoxUpdate function resynchronizes the internal data structures of a specified ComboBox widget. This function is useful when an application manipulates ComboBox's child widgets, possibly changing data structures. For example, you might want to use the XmComboBoxUpdate function after a ComboBox List child selection policy has been changed without notification.