Provided by: libmotif-dev_2.3.8-3.1build1_amd64 bug

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)