Provided by: libmotif-dev_2.3.8-3_amd64 
NAME
XmComboBox — The ComboBox widget class "XmComboBox" "widget class" "ComboBox"
SYNOPSIS
#include <Xm/ComboBox.h>
DESCRIPTION
XmComboBox combines the capabilities of a single-line TextField widget and a List widget.
It allows users to perform opoerations like typing and pasting information, and it also
provides a list of possible choices that the user can select from to complete the
TextField entry field. The list can either be displayed at all times or can be dropped
down by the user. When the list portion of the ComboBox is hidden, users are given a
visual cue (a downward-pointing arrow) next to the TextField field. The position of the
arrow relative to the TextField field depends on the XmNlayoutDirection resource of the
widget. This version of the ComboBox is called the "drop-down" ComboBox. Drop-down
ComboBoxes are useful when screen space is limited, or when users will complete the text
entry field more often by typing text than by selecting the entry field text from the
list. The user can access the drop-down ComboBox in either one of two ways:
• By clicking and releasing <Btn1> on the downward-pointing arrow, which pops the list
up, and the list stays up. A later selection of an item in the list will cause the
item to appear in the text entry field, and the list will unpost itself.
• By pressing <Btn1> on the downward-pointing arrow, dragging it to a list item, and
then releasing it there, which selects that item. The list disappears, and the
selected item appears in the text entry field.
The application provides an array of strings that fill the list. At creation time, string
items can be passed to the ComboBox via an arglist. 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. The size of the list is set by specifying the number of
items that are visible in the list (XmNvisibleItemCount). If the number of items in the
list exceeds the number of items that are visible, a vertical scroll bar will
automatically appear that allows the user to scroll through a large number of items.
ComboBox creates two child widgets: a TextField widget for entering text and a
ScrolledWindow containing a List for the list of items. The name of the items list itself
is List, and the name of the TextField is Text. The application or user can specify
resource values for these widgets in a resource file, and the application can use
XtNameToWidget (specifying "*List" for the items list or "*Text" for the TextField widget)
to obtain the widget IDs of the descendant widgets. At creation time, ComboBox passes
appropriate resource values in the creation arglist, including XmNitems, to the items
list. Note that the result of providing the XmNdestroyCallback resource in the creation
arglist is unspecified. The application should use the XtAddCallback function to add
callbacks to the appropriate widget (TextField or List) after creating it.
ComboBox forces the following resource values on its List child:
• If XmNcomboBoxType is XmCOMBO_BOX, XmNtraversalOn is forced to False.
• XmNhighlightThickness is forced to 2 in a drop-down ComboBox and to 0 in other types
of ComboBoxes.
• XmNborderWidth is forced to 0.
• XmNnavigationType is forced to XmNONE.
• XmNselectionPolicy is forced to XmBROWSE_SELECT.
• XmNlistSizePolicy is forced to XmVARIABLE.
• XmNspacing is forced to 0.
• XmNvisualPolicy is forced to XmVARIABLE.
• XmNselectedPositions is forced to NULL.
• XmNselectedPositionsCount is forced to 0.
When XmNcomboBoxType is XmDROP_DOWN_LIST, ComboBox forces the following resource values on
its TextField child:
• XmNeditable is forced to False.
• XmNcursorPositionVisible is forced to False.
• XmNshadowThickness is forced to 0.
By contrast, when XmNcomboBoxType is XmCOMBO_BOX or XmDROP_DOWN_COMBO_BOX, ComboBox forces
the following resource values on its TextField child:
• XmNeditable is forced to True.
• XmNcursorPositionVisible is forced to True.
• XmNeditMode is forced to XmSINGLE_LINE_EDIT.
ComboBox always forces the values of the following resources on the TextField:
• XmNnavigationType is forced to XmNONE.
• XmNhighlightThickness is forced to 0.
• XmNborderWidth is forced to 0.
ComboBox allows a single item to be selected in two ways: by selecting the desired item
from the List or by entering text into the TextField. ComboBox does not automatically
select a list item if the user types that string into the TextField. It selects the item
when the user presses KActivate or moves the focus. ComboBox supports the Browse Select
selection model of List (see the XmList reference page for a description of this model),
so selections are mutually exclusive. Selecting an item from the list causes that item to
be displayed in the TextField portion of the ComboBox. If an application sets the
XmNvalue resource of TextField, that string is shown in the TextField. If the application
has not provided any list items, or if there is no current selection, the TextField is
empty.
The TextField in the ComboBox widget can be either editable or noneditable, depending on
the value of the XmNcomboBoxType resource.
If the TextField is editable, the user can type into it. When the user presses the Return
key, the ComboBox will compare the typed entry to the items in the List. If there is an
exact match, then the matched List item is selected. If the application wishes to
validate the entered text (for example, to ensure that the typed selection is a valid
one), it can do so by setting XmNmodifyVerifyCallback on the TextField widget.
If the TextField is noneditable, typing text may invoke a matching algorithm that will
attempt to match the entered text with items in the list. The specific matching algorithm
applied, which may be none, is determined by the value of the XmNmatchBehavior resource in
ComboBox, which can be either XmNONE or XmQUICK_NAVIGATE. A value of XmNONE indicates that
no matching algorithm will occur. A value of XmQUICK_NAVIGATE indicates that when the List
widget has focus, one-character navigation is supported. In this algorithm, if the typed
character is the initial character of some item in the List, this algorithm causes that
item to be navigated to and selected, and the item is displayed in the TextField.
Subsequently typing the same character will cycle among the items with the same first
character.
Regardless of the selection mechanism used (either selected directly from the List or
typed into the TextField), when an item in the List is selected, that item is highlighted
in the List. In addition, the selected item is displayed in the TextField of the
ComboBox. If the user performs an action that would move focus away from ComboBox, or
selects a List item, the XmNselectionCallback callbacks are invoked to notify the
application of the current contents of the TextField (or choice). The application then
takes whatever action is required based on those contents (or choice).
ComboBox uses the XmQTspecifyRenderTable trait and holds the XmQTaccessTextual trait.
Classes
XmComboBox inherits behavior, resources, and traits from Core, Composite, and XmManager
classes.
The class pointer is xmComboBoxWidgetClass.
The class name is XmComboBox.
New Resources
The following table defines a set of widget resources used by the programmer to specify
data. The programmer can also set the resource values for the inherited classes to set
attributes for this widget. To reference a resource by name or by class in a .Xdefaults
file, remove the XmN or XmC prefix and use the remaining letters. To specify one of the
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the
remaining letters (in either lowercase or uppercase, but include any underscores between
words). The codes in the access column indicate if the given resource can be at creation
time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not
applicable (N/A).
┌───────────────────────────────────────────────────────────────────────────────────────┐
--
ERRORS/WARNINGS
The toolkit will display a warning if the application tries to set the value of XmNlist or
the XmNtextField resource, which are read-only (marked G in the resource table).
RELATED
Composite(3), Core(3), XmCreateComboBox(3), XmList(3), XmManager(3), XmTextField(3),
XmVaCreateComboBox(3), and XmVaCreateManagedComboBox(3).
XmComboBox(3)