


XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


NAME
       XmComboBox - The Combo Box widget class

SYNOPSIS
       #include <ComboBox.h>

       Depending on your system's configuration the place of this
       include file may vary. In doubt, contact your local system
       administrator. Or run in circles and shout.


DESCRIPTION
       The  ComboBox  widget  allows  the user to select elements
       from a list of choices, and enter their own  values  in  a
       text widget. To conserve screen space, the list of choices
       is shown only when the user selects the down arrow button.
       The  choices may then be selected from this list. The list
       will automatically by removed when  the  user  selects  an
       item in the list.  When the list is removed, the item that
       was selected will be placed in the text widget. Typing the
       escape key when the list is up, cancels the list popup.

     Classes
       ComboBox  inherits  behaviour  and resources from Core and
       Composite, Constraint 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 set at creation time (C), set by
       using XtSetValues (S), retrieved by using XtGetValues (G),
       or is not applicable (N/A).

                           XmComboBox Resource Set
       -----------------------------------------------------------------
        Name                            Default                  Access
          Class                           Type
       -----------------------------------------------------------------
        XmNactivateCallback             NULL                     C
          XmCCallback                     XtCallbackList
       -----------------------------------------------------------------




Version 1.31              20 March 1995                         1





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


        XmNalignment                    XmALIGNMENT_CENTER       CSG
          XmCAlignment                    unsigned char
       -----------------------------------------------------------------
        XmNarrowSpacingOn               False                    CSG
          XmNCArrowSpacingOn              Boolean
       -----------------------------------------------------------------
        XmNautomaticSelection           False                    CSG
          XmCAutomaticSelection           Boolean
       -----------------------------------------------------------------
        XmNblinkRate                    500                      CSG
          XmCBlinkRate                    int
       -----------------------------------------------------------------
        XmNcolumns                      dynamic                  CSG
          XmCColumns                      short
       -----------------------------------------------------------------
        XmNcursorPosition               0                        CSG
          XmCCursorPosition               XmTextPosition
       -----------------------------------------------------------------
        XmNcursorPositionVisible        True                     CSG
          XmCCursorPositionVisible        Boolean
       -----------------------------------------------------------------
        XmNdefaultActionCallback        NULL                     CSG
          XmCCallback                     XtCallbackList
       -----------------------------------------------------------------
        XmNdropDownCallback             NULL                     CSG
          XmCDropDownCallback             XtCallbackList
       -----------------------------------------------------------------
        XmNdropDownCursor               center_ptr               CSG
          XmCDropDownCursor               Cursor
       -----------------------------------------------------------------
        XmNdropDownOffset               dynamic                  CSG
          XmCDropDownOffset               Position
       -----------------------------------------------------------------
        XmNeditable                     False                    CG
          XmCEditable                     Boolean
       -----------------------------------------------------------------
        XmNfontList                     dynamic                  CSG
          XmCFontList                     XmFontList
       -----------------------------------------------------------------
        XmNitemCount                    0                        CSG
          XmCItemCount                    int
       -----------------------------------------------------------------
        XmNitems                        NULL                     CSG
          XmCItems                        XmStringTable
       -----------------------------------------------------------------
        XmNlabelFontList                dynamic                  CSG
          XmCLabelFontList                XmFontList
       -----------------------------------------------------------------
        XmNlabelInsensitivePixmap       XmUNSPECIFIED_PIXMAP     CSG
          XmCLabelInsensitivePixmap       Pixmap
       -----------------------------------------------------------------
        XmNlabelMarginBottom            0                        CSG





Version 1.31              20 March 1995                         2





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


          XmCLabelMarginBottom            Dimension
       -----------------------------------------------------------------
        XmNlabelMarginHeight            2                        CSG
          XmCLabelMarginHeight            Dimension
       -----------------------------------------------------------------
        XmNlabelMarginLeft              0                        CSG
          XmCLabelMarginLeft              Dimension
       -----------------------------------------------------------------
        XmNlabelMarginRight             0                        CSG
          XmCLabelMarginRight             Dimension
       -----------------------------------------------------------------
        XmNlabelMarginTop               0                        CSG
          XmCLabelMarginTop               Dimension
       -----------------------------------------------------------------
        XmNlabelMarginWidth             0                        CSG
          XmCLabelMarginWidth             Dimension
       -----------------------------------------------------------------
        XmNlabelPixmap                  XmUNSPECIFIED_PIXMAP     CSG
          XmCLabelPixmap                  Pixmap
       -----------------------------------------------------------------
        XmNlabelString                  dynamic                  CSG
          XmCXmString                     XmString
       -----------------------------------------------------------------
        XmNlabelType                    XmSTRING                 CSG
          XmCLabelType                    unsigned char
       -----------------------------------------------------------------
        XmNlistMarginHeight             0                        CSG
          XmCListMarginHeight             Dimension
       -----------------------------------------------------------------
        XmNlistMarginWidth              0                        CSG
          XmCListMarginWidth              Dimension
       -----------------------------------------------------------------
        XmNlistSizePolicy               XmVARIABLE               CG
          XmCListSizePolicy               unsigned char
       -----------------------------------------------------------------
        XmNlistSpacing                  0                        CSG
          XmCListSpacing                  Dimension
       -----------------------------------------------------------------
        XmNmarginHeight                 5                        CSG
          XmCMarginHeight                 Dimension
       -----------------------------------------------------------------
        XmNmarginWidth                  5                        CSG
          XmCMarginWidth                  Dimension
       -----------------------------------------------------------------
        XmNmaxLength                    largest integer          CSG
          XmCMaxLength                    int
       -----------------------------------------------------------------
        XmNmodifyVerifyCallback         NULL                     CSG
          XmCCallback                     XtCallbackList
       -----------------------------------------------------------------
        XmNmotionVerifyCallback         NULL                     CSG
          XmCCallback                     XtCallbackList
       -----------------------------------------------------------------




Version 1.31              20 March 1995                         3





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


        XmNpersistentDropDown           False                    CSG
          XmCPersistentDropDown           Boolean
       -----------------------------------------------------------------
        XmNscrollBarDisplayPolicy       XmAS_NEEDED              CSG
          XmCScrollBarDisplayPolicy       unsigned char
       -----------------------------------------------------------------
        XmNselectionCallback            NULL                     CSG
          XmCCallback                     XtCallbackList
       -----------------------------------------------------------------
        XmNselectionPolicy              XmBROWSE_SELECT          CG
          XmCSelectionPolicy              unsigned char
       -----------------------------------------------------------------
        XmNselectThreshold              5                        CSG
          XmCSelectThreshold              int
       -----------------------------------------------------------------
        XmNshowLabel                    False                    CG
          XmCShowLabel                    Boolean
       -----------------------------------------------------------------
        XmNsorted                       False                    CSG
           XmCSorted                      Boolean
       -----------------------------------------------------------------
        XmNsortingCallback              NULL                     CSG
          XmCCallback                     XtCallbackList
       -----------------------------------------------------------------
        XmNsquareArrow                  False                    CSG
          XmCSquareArrow                  Boolean
       -----------------------------------------------------------------
        XmNstaticList                   False                    CSG
          XmCStaticList                   Boolean
       -----------------------------------------------------------------
        XmNstringDirection              dynamic                  CSG
          XmCStringDirection              XmStringDirection
       -----------------------------------------------------------------
        XmNtwmHandlingOn                False                    CSG
          XmCTwmHandlingOn                Boolean
       -----------------------------------------------------------------
        XmNtopItemPostion               1                        G
          XmCTopItemPostion               int
       -----------------------------------------------------------------
        XmNunselectionCallback          NULL                     CSG
          XmCCallback                     XtCallbackList
       -----------------------------------------------------------------
        XmNvalue                        ""                       CSG
          XmCValue                        String
       -----------------------------------------------------------------
        XmNvalueChangedCallback         NULL                     CSG
          XmCCallback                     XtCallbackList
       -----------------------------------------------------------------
        XmNvisibleItemCount             8                        CSG
          XmCVisibleItemCount             Int
       -----------------------------------------------------------------

       XmNactivateCallback
              Specifies a list of callbacks to be called when the



Version 1.31              20 March 1995                         4





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


              user  presses either the key "Enter" or "Activate".
              The type of the structure passed to  this  callback
              is    XmAnyCallbackStruct   and   the   reason   is
              XmCR_ACTIVATE.

       XmNalignment
              The alignment (left to right) for the label's  text
              or    pixmap.    Possible   values   are   XmALIGN-
              MENT_BEGINNING,  XmALIGNMENT_CENTER,  and  XmALIGN-
              MENT_END.

       XmNautomaticSelection
              Indicates   whether   the  XmNselectionCallback  is
              invoked each time the user moves into a new item if
              XmNautomaticSelection  is  True  and  the selection
              mode is XmBROWSE_SELECT.  If set to False the XmNs-
              electionCallback  is  not  invoked  until  the user
              releases the mouse button.

       XmNarrowSpacingOn
              Indicates whether a gap is  displayed  between  the
              arrow  button  and  the  text  input  field if this
              resource is set to True and XmNeditable is also set
              to  True.   If  this  resource  is set to False the
              combo box widget will never display a  gab  between
              the arrow button and the text area, irrespective of
              the setting  of  XmNeditable.   Note  that  setting
              XmNarrowSpacingOn  to  False  doesn  not conform to
              common GUI styles. And it prevents  the  user  from
              easily   recognizing   whether  the  combo  box  is
              editable or not.

       XmNblinkRate
              The time in milliseconds  that  the  cursor  spends
              being  visible  or invisible. A value of 0 prevents
              the cursor from blinking.

       XmNborderWidth
              That's no new resource but is already introduced in
              the  core  class.  This class overrides the default
              value and sets it to zero. You can however override
              it  again  if  you're  dissatisfied  with  the  new
              default setting.

       XmNcolumns
              Specifies the initial width of the input field mea-
              sured   in  character  spaces.  The  default  value
              depends on the value of the width of the combo box.

       XmNcursorPosition
              Indicates the position in the text where the insert
              cursor is to be located. Its position is the offset
              of  characters  and  it starts with offset 0 at the
              beginning of the text.



Version 1.31              20 March 1995                         5





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


       XmNcursorPositionVisible
              Flags whether the insert cursor position is  marked
              by a blinking cursor.

       XmNdefaultActionCallback
              Specifies  a list of callbacks that is called every
              time an item  is  double  clicked.  The  reason  is
              XmCR_DEFAULT_ACTION.    Please  remember  that  you
              can't use this callback if XmNstaticList  is  False
              because  the  list  is  immediatly hidden after the
              user selected an item from the list. Thus the  user
              can't double click on any item within the list.

       XmNdropDownCallback
              This  is  a list of callbacks to be called when the
              list is about to be shown or  hidden.  The  reasons
              are XmCR_SHOW_LIST or XmCR_HIDE_LIST.

       XmNdropDownCursor
              Specifies  the cursor to be used whenever the mouse
              cursor is within the drop down list.

       XmNdropDownOffset
              Specifies the distance between the left  border  of
              the  list  and  the left border of the input field.
              The default value is set to the width of the  arrow
              button.  Only  positive values are allowed for XmN-
              dropDownOffset, negative ones will be ignored.

       XmNeditable
              Specifies the type of combo box. If  set  to  True,
              the  combo  box  contains  an editable input field.
              Therefore, the user is free to select  entries  out
              of  the list and to enter new text or modify it. In
              the other case, with XmNeditable set to  False  the
              user can solely browse in and select entries out of
              the list.

       XmNfontList
              Indicates the font list to be used  for  the  input
              field  and  the  list. If the value is NULL at ini-
              tialization, it is initialized by  looking  up  the
              parent hierarchy of the widget for an ancestor that
              is a subclass of XmBulletinBoard, XmVendorShell  or
              XmMenuShell.   If  such  an ancestor is found, it's
              font list will be taken by the combo box widget.

       XmNitemCount
              Specifies the total number of items in the list.

       XmNitems
              Points to an array of compound strings representing
              the  items to be displayed in the list. By means of
              this a program can find out  what  items  the  list



Version 1.31              20 March 1995                         6





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


              contains.  It  is also possible to set the contents
              of the  list  box  in  one  step  by  setting  this
              resource to a new array of compound strings. Please
              remember:  always  set  XmNitems  and  XmNitemCount
              together   in  the  same  call  to  XtSetValues  or
              XtVaSetValues.  If you ignore this rule  the  combo
              box  will  ignore you and your attempt to set these
              resources.

       XmNlabelInsensitivePixmap
              Specifies a pixmap used as the button face if  XmN-
              labelType is set to XmPIXMAP and the combo box wid-
              get is insensitive.

       XmNlabelPixmap
              Specifies a pixmap to be displayed to the  left  of
              the  input  field  if  XmNlabelType is XmPIXMAP and
              XmNshowLabel is True (of course).

       XmNlabelString
              Specifies the the compound string to  be  displayed
              if XmNlabelType is set to XmSTRING and XmNshowLabel
              is True.

       XmNlabelType
              The type of label (either string or pixmap). Possi-
              ble values are XmPIXMAP and XmSTRING.

       XmNlabelMarginTop, XmNlabelMarginBottom
       XmNlabelMarginLeft, XmNlabelMarginRight
              The  amount  of space between one side of the label
              and the nearest margin.

       XmNlabelMarginHeight, XmNlabelMarginWidth
              The spacing between one side of the label  and  the
              nearest edge of a shadow.

       XmNlistMarginHeight, XmNlistMarginWidth
              The  height or width of the margin between the bor-
              der of the list and the items in the list.

       XmNlistSizePolicy
              Controls the reaction of  the  list  when  an  item
              grows  horizontally beyond the current width of the
              list and XmNstaticList is set to True.  If  set  to
              XmCONSTANT,  the list does not grow, and a horizon-
              tal scroll bar is shown. If this resource is set to
              XmVARIABLE, the list instead trys to grow such that
              it match the size of the longest item, thus no hor-
              izontal  scroll  bar  will  appear.   When XmNlist-
              SizePolicy is the list will again try to  grow  but
              in  case  the width of the longest item in the list
              is wider than the viewing area of the list a  hori-
              zontal scroll bar appears.



Version 1.31              20 March 1995                         7





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


       XmNlistSpacing
              The spacing between items in the list.

       XmNmarginHeight
              Specifies the distance between the top and the bot-
              tom of the widget window and the text displayed  in
              the input field.

       XmNmarginWidth
              Like  XmNmarginHeight  this  resource specifies the
              distance between the left and the right  border  of
              the widget window and the text.

       XmNmaxLength
              Specifies  the  maximum  length  of the text string
              that can be entered  from  the  keyboard  into  the
              input  field of the combo box. Strings that are put
              into  the  input  field  using  XmComboBoxSetString
              ignore this resource.

       XmNmodifyVerifyCallback
              Contains  a list of callbacks called before text is
              deleted from or inserted into the text area of  the
              combo  box widget. The callbacks are called only if
              XmNeditable  is  set  to  True.   The   reason   is
              XmCR_MODIFYING_TEXT_VALUE  and  the  type  of   the
              structure passed to this  callback  is  XmComboBox-
              TextVerifyCallbackStruct.

       XmNmotionVerifyCallback
              Specifies  the  list  of  callbacks  that is called
              before the insert  cursor  gets  moved  to  another
              position.  The  reason is XmCR_MOVING_INSERT_CURSOR
              and the type of  the  structure  whose  address  is
              passed to the callback is XmComboBoxTextVerifyCall-
              back-Struct.

       XmNscrollBarDisplayPolicy
              Controls the display of the vertical scroll bar  in
              the  list  when  XmNstaticList  is set to True.When
              XmNscrollBarDisplayPolicy is  set  to  XmAS_NEEDED,
              the  vertical scroll bar is displayed only when the
              list contains more items than can be currently dis-
              played.  If set to XmSTATIC the vertical scroll bar
              is always displayed.

       XmNpersistentDropDown
              Welcome to the sad  section  in  the  life  of  X11
              applications.  This resource and the inherent prob-
              lems are due to the focus policy of the window man-
              ager  you're  using. See the further details in the
              later sections.





Version 1.31              20 March 1995                         8





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


       XmNselectionCallback
              Specifies a list of callbacks that is  called  when
              an    item    is    selected.     The   reason   is
              XmCR_SINGLE_SELECT.  The callbacks are  NOT  called
              when  the  user  browses  through  the items in the
              list.

       XmNselectionPolicy
              This resource controls whether the user  can  dese-
              lect  the  currently  selected  item within a combo
              box.  The  default  value  is  XmBROWSE_SELECT,  so
              always  one  item gets selected if the combo box is
              editable. In the case of XmSINGLE_SELECT  the  user
              may deselect the current item either by clicking on
              it in the  drop  down  list  or  pressing  the  key
              "Delete".  Other  values for XmNselectionPolicy are
              currently not allowed. (Multiple selections will be
              probably availabe with the next release.)

       XmNselectThreshold
              Specifies  the amount of pixels the mouse must move
              until the selection of text is recognized in  click
              and drag mode.

       XmNshowLabel
              Specifies,  whether  a  label  containing text or a
              pixmap should be displayed on the left side of  the
              combo box. This resource can only be specified dur-
              ing the creation of the combo  box,  afterwards  it
              will have no effect.

       XmNsorted
              Specifies  whether the items in the list are sorted
              or not In an unsorted list, the items are shown  in
              the  order in which they're put into the list. When
              adding an item to a sorted list, this item will  be
              put at the right place (alphabetically sorted).

       XmNsortingCallback
              Contains  a  list of callbacks that is called when-
              ever a new item is added to the  combo  box  widget
              and  XmNsorted is True.  The reason is XmCR_SORTING
              and the type of  the  structure  whose  address  is
              passed  to  the  callback is XmComboBoxSortingCall-
              back-Struct.  For detailed information see the fol-
              lowing sections.

       XmNsquareArrow
              Controls  the  width of the arrow button in respect
              to its height. If this resource is True  the  arrow
              button  is  always  layed out square. Otherwise the
              arrow button's width will be approximatly 4/5th  of
              its height.




Version 1.31              20 March 1995                         9





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


       XmNstaticList
              Controls whether the list is always statically dis-
              played right below the text input area of the combo
              box  if  set  to True.  If you use a combo box with
              XmNstaticList set to True and  XmNeditable  set  to
              False  you should consider using a simple list wid-
              get instead.

       XmNstringDirection
              Specifies the initial direction to draw the  string
              (from  the  left  to  the  right or in the opposite
              direction). The whole story seems to  be  incompre-
              hensible... therefore this resource is provided for
              completeness only.

       XmNtwmHandlingOn
              If  you  have  trouble  with  the  list  then  this
              resource may help you.  Set it to True, if the list
              gets hidden at the moment the mouse  cursor  enters
              the list.

       XmNtopItemPosition
              This  resource  is intended as an informal hint. It
              specifies the index of the item which is  displayed
              at the visible top of the list.

       XmNvalue
              Contains  the  text  of  the input field. This also
              concerns combo  boxes  which  are  not  editable  (
              XmNeditable set to False).

       XmNunselectionCallback
              Specifies  a list of callbacks that is called when-
              ever the currently selected item is deselected  and
              no other item gets selected. This callback is acti-
              vated  only  when  XmNselectionPolicy   is   XmSIN-
              GLE_SELECT.  The reason is XmCR_UNSELECT.  The type
              of the structure whose address is  passed  to  this
              callback is XmAnyCallbackStruct.

       XmNvalue
              Contains  the  text  of  the input field. This also
              concerns combo  boxes  which  are  not  editable  (
              XmNeditable set to False).

       XmNvalueChangedCallback
              Specifies  a  list  of callbacks to be called after
              text is deleted from or inserted into the text area
              of   the   combo   box   widget.   The   reason  is
              XmCR_VALUE_CHANGED.   The  type  of  the  structure
              whose  address is passed to this callback is XmAny-
              CallbackStruct.





Version 1.31              20 March 1995                        10





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


       XmNvisibleItemCount
              Specifies the number of items that can fit  in  the
              visible  space of the list. The combo box uses this
              value to determine the height of its list.

     Inherited Resources
       XmComboBox inherits behaviour and resources from the  fol-
       lowing  superclasses.  For  a complete description of each
       resource, refer to the man page for that superclass.

     Callback Information
       A pointer to the following  structure  is  passed  to  the
       XmNdropDownCallback callback:

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

       reason         Within this structure, reason indicates the
                      reason why the callback was activated. This
                      can    be   XmCR_SHOW_LIST   as   well   as
                      XmCR_HIDE_LIST.  A callback is called  with
                      the  reason  XmCR_SHOW_LIST just before the
                      list is dropped down, whereas the  callback
                      is  called  with  XmCR_HIDE_LIST  after the
                      list is hidden.


       event          Points to the XEvent, which  triggered  the
                      callback.  May  be  NULL if the callback is
                      triggered by a call  to  XmComboBoxShowList
                      or XmComboBoxHideList.

       A  pointer  to  the  following  structure is passed to the
       XmNactivateCallback callback:

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

       reason         Indicates why  the  callback  was  invoked.
                      This  is XmCR_ACTIVATE for XmNactivateCall-
                      back.

       event          Points to the XEvent, which  triggered  the
                      callback.

       A  pointer  to  the  following  structure is passed to the
       XmNselectionCallback and XmNdefaultActionCallback:

       typedef struct {
         int            reason;



Version 1.31              20 March 1995                        11





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


         XEvent         *event;
         XmString       value;
         int            index;
       } XmComboBoxSelectionCallbackStruct,  XmComboBoxDefaultAc-
       tionCallbackStruct;

       reason         Within this structure, reason indicates the
                      reason why the callback was  activated.  At
                      this   time,   the  reason  can  be  either
                      XmCR_SINGLE_SELECT or XmCR_BROWSE_SELECT
                      depending  on  the setting of XmNselection-
                      Policy.   It  indicates   that   the   user
                      selected  a  (potentially  new) item in the
                      list.  Whether this callback  is  activated
                      every  time  the user moves into a new item
                      of the list or only when the user  releases
                      the  mouse button is controlled through the
                      setting of XmNautomaticSelection.

       event          Points to the XEvent, which  triggered  the
                      callback.

       value          Points  to  a  XmString, which contains the
                      text of the current  selected  item.   This
                      XmString  must never be freed or changed by
                      the called program code!

       index          Index (starting from 1)  of  the  currently
                      selected item in the list.

       A  pointer  to  the  following  structure is passed to the
       XmNunselectionCallback callback:

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

       reason         Indicates why  the  callback  was  invoked.
                      This is XmCR_UNSELECT.

       event          Points  to  the XEvent, which triggered the
                      callback.

       A pointer to the following  structure  is  passed  to  the
       XmNmodifyVerifyCallback and XmNmotionVerifyCallback call-
       backs:

       typedef struct {
         int            reason;
         XEvent         *event;
         Boolean        doit;
         Position       currInsert, newInsert;
         Position       startPos, endPos;



Version 1.31              20 March 1995                        12





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


         XmTextBlock    text;
       } XmComboBoxTextVerifyCallbackStruct, *XmComboBoxTextVeri-
       fyPtr;

       reason         Indicates  the  reason why the callback was
                      activated.    This    can     be     either
                      XmCR_MODIFYING_TEXT_VALUE                or
                      XmCR_MOVING_INSERT_CURSOR.

       event          Points to the XEvent, which  triggered  the
                      callback.

       doit           Indicates   whether  the  offending  action
                      should be performed. Setting this field  of
                      the  callback structure to False denies the
                      action.

       currInsert     Specifies  the  current  position  of   the
                      insert cursor.

                      Indicates  the  position  at which the user
                      attempts to position the cursor.

       startPos       Indicates the starting position of the text
                      to     modify.    If    the    reason    is
                      XmCR_MOVING_INSERT_CURSOR this value is the
                      same as currInsert.

       endPos         Specifies  the  ending position of the text
                      to  modify.  If  no  text  is  replaced  or
                      deleted, then the value will be the same as
                      startPos.      If     the     reason     is
                      XmCR_MODIFYING_TEXT_VALUE this value is the
                      same as currInsert.

       text           Holds the address of a  structure  of  type
                      XmTextBlockRec   which  holds  the  textual
                      information to be inserted.

       The following table describes the reasons why the individ-
       ual verification callback structure fields are valid.

                Reason                    Valid Fields
       -----------------------------------------------------
       XmCR_MODIFYING_TEXT_VALUE     reason, event, doit,
                                     startPos, endPos, text

       XmCR_MOVING_INSERT_CURSOR     reason, event, doit,
                                     currInsert, newInsert,

       A pointer to the following structure is passed to the XmN-
       sortingCallback callback: typedef struct {
         int            reason;
         XEvent         *event;



Version 1.31              20 March 1995                        13





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


         int            operation;
         void           *item_internal;
         XmString       item;
         int            result;
       } XmComboBoxSortingCallbackStruct, *XmComboBoxSortingPtr;

       reason         Indicates the reason why the  callback  was
                      activated. This is XmCR_SORTING.

       event          Contains  always NULL and is just there for
                      compatibility reasons.

       operation      Indicates the operation to  carry  out  and
                      can   be   either   XmOP_INIT,XmOP_DONE  or
                      XmOP_COMPARE.

       item_internal  Must be set during the XmOP_INIT  operation
                      to  a  suitable  representation  of the new
                      item which is to be added to the list.   In
                      all  subsequent calls to this callback with
                      XmOP_COMPAREorXmOP_DONE  this  field   will
                      contain  whatever you've put into it during
                      XmOP_INIT.  For detailed information  refer
                      to the documentation "The ComboBox Widget".

       item           During XmOP_INIT this field points  to  the
                      item  to be added to the list. When sorting
                      the list ( XmOP_COMPARE) the field contains
                      the  address  of  an item in the list which
                      should be compared against the new item (as
                      remembered in item_internal).

       result         When comparing an item (out of the list) in
                      item with the new item  (as  remembered  in
                      item_internal)  the result has to be stored
                      into this structure's field.

       The following table describes  which  individual  callback
       structure fields are valid during which operations.

          Reason               Valid Fields
       ---------------------------------------------
       XmOP_INIT        reason, event, operation,
                        item, item_internal
       XmOP_DONE        reason, event, operation,
                        item_internal
       XmOP_COMPARE     reason, event, operation,
                        item, item_internal, result

       For  more  information about controlling the sorting order
       see the acompanying documentation "The ComboBox Widget".

     Convenience routines
       ComboBox has a number of convenience routines  to  control



Version 1.31              20 March 1995                        14





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


       the behavior and contents of its children.

       void XmComboBoxAddItem(Widget w, XmString item, int pos)
              Add a new item to the list's contents. If XmNsorted
              is set to True, the new item is inserted alphabeti-
              cally.  If  the  list is unsorted, the same assump-
              tions can be applied as with XmListAddItem.


       void   XmComboBoxAddItems(Widget   w,   XmString   *items,
              int item_count, int pos)
              Similar to XmComboBoxAddItem.  Also  see  XmListAd-
              dItems.


       void  XmComboBoxAddItemUnselected(Widget  w,  XmString
              item, int pos)
              See XmListAddItemUnselected.


       void XmComboBoxClearItemSelection(Widget w)
              Deselects   all   currently   selected  items  when
              XmNselectionPolicy is XmSINGLE_SELECT.


       void XmComboBoxDeleteItem(Widget w, XmString item)
              See XmListDeleteItem.


       void  XmComboBoxDeleteItems(Widget  w,   XmString
              *items,   int item_count)
              See XmListDeleteItems.


       void XmComboBoxDeletePos(Widget w, int pos)
              See XmListDeletePos.


       void XmComboBoxDeleteItemsPos(Widget w, int item_count,
              int pos)
              See XmListDeleteItemsPos.


       void XmComboBoxDeleteAllItems(Widget w)
              See XmListDeleteAllItems.


       void  XmComboBoxReplaceItems(Widget  w,  XmString
              *old_items, int item_count, XmString *new_items)
              See XmListReplaceItems.


       void XmComboBoxReplaceItemsPos(Widget w, XmString
              *new_items, int item_count, int position)



Version 1.31              20 March 1995                        15





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


              See XmListReplaceItemsPos.


       Boolean XmComboBoxItemExists(Widget w, XmString item)
              See XmListItemExists.


       int XmComboBoxItemPos(Widget w, XmString item)
              See XmListItemPos.


       Boolean   XmComboBoxGetMatchPos(Widget   w,  XmString
              item,  int **pos_list, int *pos_count)
              See XmListGetMatchPos.


       void XmComboBoxSelectPos(Widget w, int pos, Boolean
              notify)
              See XmListSelectPos.


       void  XmComboBoxSelectItem(Widget  w,  XmString   item,
              Boolean notify)
              See XmListSelectItem.


       int XmComboBoxGetSelectedPos(Widget w)
              This function  differs  from  XmListGetSelectedPos.
              The  list  in  a  combo  box  can  contain only one
              selected item. Therefore this function returns  the
              index  of the selected item in the list or zero, if
              none is currently selected.


       void XmComboBoxClearSelection(Widget w, Time time)
              See XmTextFieldClearSelection.


       Boolean XmComboBoxCopy(Widget w, Time time)
              See XmTextFieldCopy.


       Boolean XmComboBoxCut(Widget w, Time time)
              See XmTextFieldCut.


       XmTextPosition XmComboBoxGetInsertionPosition(Widget w)
              See XmTextFieldGetInsertionPosition.


       XmTextPosition XmComboBoxGetLastPosition(Widget w)
              See XmTextFieldGetLastPosition.





Version 1.31              20 March 1995                        16





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


       int XmComboBoxGetMaxLength(Widget w)
              See XmTextFieldGetMaxLength.


       char *XmComboBoxGetSelection(Widget w)
              See XmTextFieldGetSelection.


       Boolean XmComboBoxGetSelectionPosition(Widget  w,
              XmTextPosition *left, XmTextPosition *right)
              See XmTextFieldGetSelectionPosition.


       char *XmComboBoxGetString(Widget w)
              See XmTextFieldGetString.


       void XmComboBoxInsert(Widget  w,  XmTextPosition
              position,  char *value)
              See XmTextFieldInsert.


       Boolean XmComboBoxPaste(Widget w)
              See XmTextFieldPaste.


       Boolean XmComboBoxRemove(Widget w)
              See XmTextFieldRemove.


       void   XmComboBoxReplace(Widget   w,   XmTextPosition
              from_pos, XmTextPosition to_pos, char *value)
              See XmTextFieldReplace.


       void XmComboBoxSetAddMode(Widget w, Boolean state)
              See XmTextFieldSetAddMode.


       void  XmComboBoxSetHighlight(Widget   w,   XmTextPosition
              left, XmTextPosition right, XmHighlightMode mode)
              See XmTextFieldSetHighlight.


       void  XmComboBoxSetInsertionPosition(Widget   w,
              XmTextPosition position)
              See XmTextFieldSetInsertionPosition.


       void XmComboBoxSetMaxLength(Widget w, int max_length)
              See XmTextFieldSetMaxLength.






Version 1.31              20 March 1995                        17





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


       void  XmComboBoxSetSelection(Widget  w,   XmTextPosition
              first, XmTextPosition last, Time time)
              See XmTextFieldSetSelection.


       void XmComboBoxSetString(Widget w, char *value)
              At least Motif 1.1 contains a very anoying bug.  If
              you try to set the contents of an XmTextField to an
              empty string (""), you'll get garbage, when  asking
              the  XmTextField  for its contents afterwards. This
              interface function provides a work around. Also see
              XmTextFieldSetString.


       void XmComboBoxShowPosition(Widget w, XmTextPosition posi-
              tion)
              See XmTextFieldShowPosition.


     The Disliked Keyboard Focus
       Now I'll  annotate  a  somewhat  tricky  subject.  If  the
       resource  XmNpersistentDropDown  defaults  to  its initial
       value of False, one can observe the following effect (this
       may be annoying).

       When the user drops down the list and then moves the mouse
       cursor out of the window where the combo box  resides  in,
       the  list  will be hidden. This is because the widget lost
       the keyboard focus. Some users are irritated because  they
       didn't  expect  that behavior, because they just moved the
       mouse to get it out of the way. If your  window  manager's
       focus  policy  is  "pointer  focus", i.e.  if you move the
       pointer into another window, that  window  will  automati-
       cally  get  the keyboard focus. On the other hand, if your
       window manager's focus policy is "explicit", you  have  to
       move  the  pointer  into  another window and click a mouse
       button to give that window the  keyboard  focus.  This  is
       often  referred  to  as  the  "click-to-type"  method.  In
       "explicit" mode, you will never see  the  list's  annoying
       behavior.

       To  bypass  this behavior on some window managers a really
       dirty hack was used. The user can activate that  hack,  if
       he sets XmNpersistentDropDown to True in the application's
       resources. Sorry, on some window managers  this  will  not
       fix the annoying behavior.

       Try  it  if  you  like  -  but  don't complain at me if it
       doesn't work as expected. But at least it  worked  on  the
       author's machine: a cute little SGI Indigo running 4dwm as
       the window manager.

       On some other window  managers  like  twm  you  will  face
       another problem: the list gets hidden as soon as the mouse



Version 1.31              20 March 1995                        18





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


       cursor enters the list. Try  to  set  XmNtwmHandlingOn  to
       True.  This resource will also work with other window man-
       agers.


     Creating a ComboBox
       Using the combo box in your own  programs  is  easy.  Just
       create  the  widget  with one of the innumerable X toolkit
       functions (like  XtCreateManagedWidget  or  XtVaCreateMan-
       agedWidget).


       Specify as the widget class xmComboBoxWidgetClass - that's
       all. There is also a so-called creation convenience  func-
       tion  called XmCreateComboBox, but it isn't really needed.

       Widget XmCreateComboBox(parent, name, arglist, argcount)
         Widget         parent;
         String         name;
         ArgList        arglist;
         Cardinal       argcount;

       Somewhere in your program you'll need something  like  the
       following code fragment:


            Widget ComboBox;

            ComboBox = XtVaCreateManagedWidget("combobox",
                           xmComboBoxWidgetClass, Parent,
                           XmNeditable, True or False,
                           other Resources...
                           NULL);


       Setting  the resource XmNeditable is not absolutely neces-
       sary, but it's better to do so.

       After creation, items can be added to the combo box's list
       by   means   of  interface  functions  like  XmComboBoxAd-
       dItem(...).  Which item the user selected  can  be  deter-
       mined by calling XmComboBoxGetString(...).


       If  you  want  to  preselect  an  item  (that is setting a
       default item to the input field of the combo box) you  can
       use  several convenience functions.  On a combo box with a
       non editable input field there are two ways to  select  an
       item:


            XmComboBoxSelectPos(ComboBox, item #, False);

       or:



Version 1.31              20 March 1995                        19





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


            XmComboBoxSelectItem(ComboBox, itemString, False);

       The  third parameter in these two function calls indicates
       whether the XmNselectionCallback  should  be  called.  The
       only  difference  between these functions is the first one
       is expecting an item number whereas the second one expects
       a  XmString. The list is then searched for this string and
       if it is found the input field will be updated.

       On a combo box with XmNeditable set to  True  use  another
       function:

            XmComboBoxSetString(ComboBox, string);

       This  sets the contents of the text input field to string.



BUGS
       Not more than currently available in Motif 1.2.3 or  Motif
       1.2.4,  but  less  than in the upcomming Motif 2.0. Report
       bugs to albrecht@igpm.rwth-aachen.de. Include a thoroughly
       description,  and say which version of the ComboBox widget
       you are using.



COPYRIGHT
       Copyright 1993, 1994 Harald Albrecht.

       The ComboBox widget is free software; you can redistribute
       it  and/or  modify  it  under the terms of the GNU General
       Public License as published by the Free  Software  Founda-
       tion; either version 2, or (at your option) any later ver-
       sion.



AVAILABILITY
       The most recent released version of the ComboBox widget is
       always available for anonymous ftp from either

              ftp.x.org (198.112.44.100)
              /contrib/widgets/motif/ComboBox

       or from

              ftp.informatik.rwth-aachen.de (137.226.112.172)
              /pub/packages/ComboBox



AUTHOR
       Author of Software & Documentation:



Version 1.31              20 March 1995                        20





XmComboBox(3Xm)        Harry's Motif Tools        XmComboBox(3Xm)


              Harald Albrecht
              Institut fuer Geometrie und Praktische Mathematik
              RWTH Aachen, Bundesrepublik Deutschland
              e-mail: albrecht@igpm.rwth-aachen.de

       English Documentation:
              Chris Marotz
              Sterling Software ITD
              e-mail: marotz@itd.sterling.com



RELATED INFORMATION
       "The ComboBox Widget" documentation
       Core(3X), XmComposite(3X), XmList(3X),  XmTextField(3X)
       Douglas Adams: The Hitchhiker's Guide to the Galaxy.
       file://134.130.161.30/arc/pub/unix/html/motifcorner.html








































Version 1.31              20 March 1995                        21


