


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


NNAAMMEE
       XmComboBox - The Combo Box widget class

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<CCoommbbooBBooxx..hh>>

       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.


DDEESSCCRRIIPPTTIIOONN
       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.

     CCllaasssseess
       ComboBox  inherits  behaviour  and resources from CCoorree and
       CCoommppoossiittee, CCoonnssttrraaiinntt and XXmmMMaannaaggeerr classes.

       The class pointer is xxmmCCoommbbooBBooxxWWiiddggeettCCllaassss.

       The class name is XXmmCCoommbbooBBooxx.

     NNeeww RReessoouurrcceess
       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  XXmmNN  or
       XXmmCC  prefix  and use the remaining letters. To specify one
       of the defined values for a resource in a .Xdefaults file,
       remove  the  XXmm  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 XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G),
       or is not applicable (N/A).

                           XXmmCCoommbbooBBooxx RReessoouurrccee SSeett
       -----------------------------------------------------------------
        NNaammee                            DDeeffaauulltt                  AAcccceessss
          CCllaassss                           TTyyppee
       -----------------------------------------------------------------
        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
       -----------------------------------------------------------------

       XXmmNNaaccttiivvaatteeCCaallllbbaacckk
              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    XXmmAAnnyyCCaallllbbaacckkSSttrruucctt   and   the   reason   is
              XXmmCCRR__AACCTTIIVVAATTEE.

       XXmmNNaalliiggnnmmeenntt
              The alignment (left to right) for the label's  text
              or    pixmap.    Possible   values   are   XXmmAALLIIGGNN--
              MMEENNTT__BBEEGGIINNNNIINNGG,  XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR,  and  XXmmAALLIIGGNN--
              MMEENNTT__EENNDD.

       XXmmNNaauuttoommaattiiccSSeelleeccttiioonn
              Indicates   whether   the  XXmmNNsseelleeccttiioonnCCaallllbbaacckk  is
              invoked each time the user moves into a new item if
              XXmmNNaauuttoommaattiiccSSeelleeccttiioonn  is  TTrruuee  and  the selection
              mode is XXmmBBRROOWWSSEE__SSEELLEECCTT.  If set to FFaallssee the XXmmNNss--
              eelleeccttiioonnCCaallllbbaacckk  is  not  invoked  until  the user
              releases the mouse button.

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

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

       XXmmNNbboorrddeerrWWiiddtthh
              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.

       XXmmNNccoolluummnnss
              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.

       XXmmNNccuurrssoorrPPoossiittiioonn
              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)


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

       XXmmNNddeeffaauullttAAccttiioonnCCaallllbbaacckk
              Specifies  a list of callbacks that is called every
              time an item  is  double  clicked.  The  reason  is
              XXmmCCRR__DDEEFFAAUULLTT__AACCTTIIOONN.    Please  remember  that  you
              can't use this callback if XXmmNNssttaattiiccLLiisstt  is  FFaallssee
              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.

       XXmmNNddrrooppDDoowwnnCCaallllbbaacckk
              This  is  a list of callbacks to be called when the
              list is about to be shown or  hidden.  The  reasons
              are XXmmCCRR__SSHHOOWW__LLIISSTT or XXmmCCRR__HHIIDDEE__LLIISSTT.

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

       XXmmNNddrrooppDDoowwnnOOffffsseett
              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 XXmmNN--
              ddrrooppDDoowwnnOOffffsseett, negative ones will be ignored.

       XXmmNNeeddiittaabbllee
              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.

       XXmmNNffoonnttLLiisstt
              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 XXmmBBuulllleettiinnBBooaarrdd, XXmmVVeennddoorrSShheellll  or
              XXmmMMeennuuSShheellll.   If  such  an ancestor is found, it's
              font list will be taken by the combo box widget.

       XXmmNNiitteemmCCoouunntt
              Specifies the total number of items in the list.

       XXmmNNiitteemmss
              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  XXmmNNiitteemmss  and  XXmmNNiitteemmCCoouunntt
              together   in  the  same  call  to  XXttSSeettVVaalluueess  or
              XXttVVaaSSeettVVaalluueess.  If you ignore this rule  the  combo
              box  will  ignore you and your attempt to set these
              resources.

       XXmmNNllaabbeellIInnsseennssiittiivveePPiixxmmaapp
              Specifies a pixmap used as the button face if  XXmmNN--
              llaabbeellTTyyppee is set to XXmmPPIIXXMMAAPP and the combo box wid-
              get is insensitive.

       XXmmNNllaabbeellPPiixxmmaapp
              Specifies a pixmap to be displayed to the  left  of
              the  input  field  if  XXmmNNllaabbeellTTyyppee is XXmmPPIIXXMMAAPP and
              XXmmNNsshhoowwLLaabbeell is True (of course).

       XXmmNNllaabbeellSSttrriinngg
              Specifies the the compound string to  be  displayed
              if XXmmNNllaabbeellTTyyppee is set to XXmmSSTTRRIINNGG and XXmmNNsshhoowwLLaabbeell
              is True.

       XXmmNNllaabbeellTTyyppee
              The type of label (either string or pixmap). Possi-
              ble values are XXmmPPIIXXMMAAPP and XXmmSSTTRRIINNGG.

       XXmmNNllaabbeellMMaarrggiinnTToopp,, XXmmNNllaabbeellMMaarrggiinnBBoottttoomm
       XXmmNNllaabbeellMMaarrggiinnLLeefftt,, XXmmNNllaabbeellMMaarrggiinnRRiigghhtt
              The  amount  of space between one side of the label
              and the nearest margin.

       XXmmNNllaabbeellMMaarrggiinnHHeeiigghhtt,, XXmmNNllaabbeellMMaarrggiinnWWiiddtthh
              The spacing between one side of the label  and  the
              nearest edge of a shadow.

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

       XXmmNNlliissttSSiizzeePPoolliiccyy
              Controls the reaction of  the  list  when  an  item
              grows  horizontally beyond the current width of the
              list and XXmmNNssttaattiiccLLiisstt is set to TTrruuee.  If  set  to
              XXmmCCOONNSSTTAANNTT,  the list does not grow, and a horizon-
              tal scroll bar is shown. If this resource is set to
              XXmmVVAARRIIAABBLLEE, 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 XXmmNNlliisstt--
              SSiizzeePPoolliiccyy 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)


       XXmmNNlliissttSSppaacciinngg
              The spacing between items in the list.

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

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

       XXmmNNmmaaxxLLeennggtthh
              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  XXmmCCoommbbooBBooxxSSeettSSttrriinngg
              ignore this resource.

       XXmmNNmmooddiiffyyVVeerriiffyyCCaallllbbaacckk
              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
              XXmmNNeeddiittaabbllee  is  set  to  TTrruuee.   The   reason   is
              XXmmCCRR__MMOODDIIFFYYIINNGG__TTEEXXTT__VVAALLUUEE  and  the  type  of   the
              structure passed to this  callback  is  XXmmCCoommbbooBBooxx--
              TTeexxttVVeerriiffyyCCaallllbbaacckkSSttrruucctt.

       XXmmNNmmoottiioonnVVeerriiffyyCCaallllbbaacckk
              Specifies  the  list  of  callbacks  that is called
              before the insert  cursor  gets  moved  to  another
              position.  The  reason is XXmmCCRR__MMOOVVIINNGG__IINNSSEERRTT__CCUURRSSOORR
              and the type of  the  structure  whose  address  is
              passed to the callback is XXmmCCoommbbooBBooxxTTeexxttVVeerriiffyyCCaallll--
              bbaacckk--SSttrruucctt.

       XXmmNNssccrroollllBBaarrDDiissppllaayyPPoolliiccyy
              Controls the display of the vertical scroll bar  in
              the  list  when  XXmmNNssttaattiiccLLiisstt  is set to TTrruuee..When
              XXmmNNssccrroollllBBaarrDDiissppllaayyPPoolliiccyy is  set  to  XXmmAASS__NNEEEEDDEEDD,
              the  vertical scroll bar is displayed only when the
              list contains more items than can be currently dis-
              played.  If set to XXmmSSTTAATTIICC the vertical scroll bar
              is always displayed.

       XXmmNNppeerrssiisstteennttDDrrooppDDoowwnn
              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)


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

       XXmmNNsseelleeccttiioonnPPoolliiccyy
              This resource controls whether the user  can  dese-
              lect  the  currently  selected  item within a combo
              box.  The  default  value  is  XXmmBBRROOWWSSEE__SSEELLEECCTT,  so
              always  one  item gets selected if the combo box is
              editable. In the case of XXmmSSIINNGGLLEE__SSEELLEECCTT  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 XXmmNNsseelleeccttiioonnPPoolliiccyy are
              currently not allowed. (Multiple selections will be
              probably availabe with the next release.)

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

       XXmmNNsshhoowwLLaabbeell
              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.

       XXmmNNssoorrtteedd
              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).

       XXmmNNssoorrttiinnggCCaallllbbaacckk
              Contains  a  list of callbacks that is called when-
              ever a new item is added to the  combo  box  widget
              and  XXmmNNssoorrtteedd is TTrruuee.  The reason is XXmmCCRR__SSOORRTTIINNGG
              and the type of  the  structure  whose  address  is
              passed  to  the  callback is XXmmCCoommbbooBBooxxSSoorrttiinnggCCaallll--
              bbaacckk--SSttrruucctt.  For detailed information see the fol-
              lowing sections.

       XXmmNNssqquuaarreeAArrrrooww
              Controls  the  width of the arrow button in respect
              to its height. If this resource is TTrruuee  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)


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

       XXmmNNssttrriinnggDDiirreeccttiioonn
              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.

       XXmmNNttwwmmHHaannddlliinnggOOnn
              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.

       XXmmNNttooppIItteemmPPoossiittiioonn
              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.

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

       XXmmNNuunnsseelleeccttiioonnCCaallllbbaacckk
              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  XXmmNNsseelleeccttiioonnPPoolliiccyy   is   XXmmSSIINN--
              GGLLEE__SSEELLEECCTT.  The reason is XXmmCCRR__UUNNSSEELLEECCTT.  The type
              of the structure whose address is  passed  to  this
              callback is XXmmAAnnyyCCaallllbbaacckkSSttrruucctt.

       XXmmNNvvaalluuee
              Contains  the  text  of  the input field. This also
              concerns combo  boxes  which  are  not  editable  (
              XXmmNNeeddiittaabbllee set to FFaallssee).

       XXmmNNvvaalluueeCChhaannggeeddCCaallllbbaacckk
              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
              XXmmCCRR__VVAALLUUEE__CCHHAANNGGEEDD.   The  type  of  the  structure
              whose  address is passed to this callback is XXmmAAnnyy--
              CCaallllbbaacckkSSttrruucctt.





Version 1.31              20 March 1995                        10





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


       XXmmNNvviissiibblleeIItteemmCCoouunntt
              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.

     IInnhheerriitteedd RReessoouurrcceess
       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.

     CCaallllbbaacckk IInnffoorrmmaattiioonn
       A pointer to the following  structure  is  passed  to  the
       XXmmNNddrrooppDDoowwnnCCaallllbbaacckk callback:

       ttyyppeeddeeff ssttrruucctt {{
         iinntt            _r_e_a_s_o_n;;
         XXEEvveenntt         **_e_v_e_n_t;;
       }} XXmmCCoommbbooBBooxxDDrrooppDDoowwnnCCaallllbbaacckkSSttrruucctt;;

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


       _e_v_e_n_t          Points to the XXEEvveenntt, which  triggered  the
                      callback.  May  be  NNUULLLL if the callback is
                      triggered by a call  to  XXmmCCoommbbooBBooxxSShhoowwLLiisstt
                      or XXmmCCoommbbooBBooxxHHiiddeeLLiisstt.

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

       ttyyppeeddeeff ssttrruucctt {{
         iinntt            _r_e_a_s_o_n;;
         XXEEvveenntt         **_e_v_e_n_t;;
       }} XXmmAAnnyyCCaallllbbaacckkSSttrruucctt;;

       _r_e_a_s_o_n         Indicates why  the  callback  was  invoked.
                      This  is XXmmCCRR__AACCTTIIVVAATTEE for XXmmNNaaccttiivvaatteeCCaallll--
                      bbaacckk.

       _e_v_e_n_t          Points to the XXEEvveenntt, which  triggered  the
                      callback.

       A  pointer  to  the  following  structure is passed to the
       XXmmNNsseelleeccttiioonnCCaallllbbaacckk and XXmmNNddeeffaauullttAAccttiioonnCCaallllbbaacckk:

       ttyyppeeddeeff ssttrruucctt {{
         iinntt            _r_e_a_s_o_n;;



Version 1.31              20 March 1995                        11





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


         XXEEvveenntt         **_e_v_e_n_t;;
         XXmmSSttrriinngg       _v_a_l_u_e;;
         iinntt            _i_n_d_e_x;;
       }} XXmmCCoommbbooBBooxxSSeelleeccttiioonnCCaallllbbaacckkSSttrruucctt,,  XXmmCCoommbbooBBooxxDDeeffaauullttAAcc--
       ttiioonnCCaallllbbaacckkSSttrruucctt;;

       _r_e_a_s_o_n         Within this structure, _r_e_a_s_o_n indicates the
                      reason why the callback was  activated.  At
                      this   time,   the  reason  can  be  either
                      XXmmCCRR__SSIINNGGLLEE__SSEELLEECCTT or XXmmCCRR__BBRROOWWSSEE__SSEELLEECCTT
                      depending  on  the setting of XXmmNNsseelleeccttiioonn--
                      PPoolliiccyy.   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 XXmmNNaauuttoommaattiiccSSeelleeccttiioonn.

       _e_v_e_n_t          Points to the XXEEvveenntt, which  triggered  the
                      callback.

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

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

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

       ttyyppeeddeeff ssttrruucctt {{
         iinntt            _r_e_a_s_o_n;;
         XXEEvveenntt         **_e_v_e_n_t;;
       }} XXmmCCoommbbooBBooxxUUnnsseelleeccttiioonnCCaallllbbaacckkSSttrruucctt;;

       _r_e_a_s_o_n         Indicates why  the  callback  was  invoked.
                      This is XXmmCCRR__UUNNSSEELLEECCTT.

       _e_v_e_n_t          Points  to  the XXEEvveenntt, which triggered the
                      callback.

       A pointer to the following  structure  is  passed  to  the
       XXmmNNmmooddiiffyyVVeerriiffyyCCaallllbbaacckk and XXmmNNmmoottiioonnVVeerriiffyyCCaallllbbaacckk call-
       backs:

       ttyyppeeddeeff ssttrruucctt {{
         iinntt            _r_e_a_s_o_n;;
         XXEEvveenntt         **_e_v_e_n_t;;
         BBoooolleeaann        _d_o_i_t;;
         PPoossiittiioonn       _c_u_r_r_I_n_s_e_r_t_, _n_e_w_I_n_s_e_r_t;;
         PPoossiittiioonn       _s_t_a_r_t_P_o_s_, _e_n_d_P_o_s;;



Version 1.31              20 March 1995                        12





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


         XXmmTTeexxttBBlloocckk    _t_e_x_t;;
       }} XXmmCCoommbbooBBooxxTTeexxttVVeerriiffyyCCaallllbbaacckkSSttrruucctt,, **XXmmCCoommbbooBBooxxTTeexxttVVeerrii--
       ffyyPPttrr;;

       _r_e_a_s_o_n         Indicates  the  reason why the callback was
                      activated.    This    can     be     either
                      XXmmCCRR__MMOODDIIFFYYIINNGG__TTEEXXTT__VVAALLUUEE                or
                      XXmmCCRR__MMOOVVIINNGG__IINNSSEERRTT__CCUURRSSOORR.

       _e_v_e_n_t          Points to the XXEEvveenntt, which  triggered  the
                      callback.

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

       _c_u_r_r_I_n_s_e_r_t     Specifies  the  current  position  of   the
                      insert cursor.

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

       _s_t_a_r_t_P_o_s       Indicates the starting position of the text
                      to     modify.    If    the    reason    is
                      XXmmCCRR__MMOOVVIINNGG__IINNSSEERRTT__CCUURRSSOORR this value is the
                      same as ccuurrrrIInnsseerrtt.

       _e_n_d_P_o_s         Specifies  the  ending position of the text
                      to  modify.  If  no  text  is  replaced  or
                      deleted, then the value will be the same as
                      ssttaarrttPPooss.      If     the     reason     is
                      XXmmCCRR__MMOODDIIFFYYIINNGG__TTEEXXTT__VVAALLUUEE this value is the
                      same as _c_u_r_r_I_n_s_e_r_t.

       _t_e_x_t           Holds the address of a  structure  of  type
                      XXmmTTeexxttBBlloocckkRReecc   which  holds  the  textual
                      information to be inserted.

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

                RReeaassoonn                    VVaalliidd FFiieellddss
       -----------------------------------------------------
       XXmmCCRR__MMOODDIIFFYYIINNGG__TTEEXXTT__VVAALLUUEE     _r_e_a_s_o_n, _e_v_e_n_t, _d_o_i_t,
                                     _s_t_a_r_t_P_o_s, _e_n_d_P_o_s, _t_e_x_t

       XXmmCCRR__MMOOVVIINNGG__IINNSSEERRTT__CCUURRSSOORR     _r_e_a_s_o_n, _e_v_e_n_t, _d_o_i_t,
                                     _c_u_r_r_I_n_s_e_r_t, _n_e_w_I_n_s_e_r_t,

       A pointer to the following structure is passed to the XXmmNN--
       ssoorrttiinnggCCaallllbbaacckk callback: ttyyppeeddeeff ssttrruucctt {{
         iinntt            _r_e_a_s_o_n;;
         XXEEvveenntt         **_e_v_e_n_t;;



Version 1.31              20 March 1995                        13





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


         iinntt            _o_p_e_r_a_t_i_o_n;;
         vvooiidd           **_i_t_e_m___i_n_t_e_r_n_a_l;;
         XXmmSSttrriinngg       _i_t_e_m;;
         iinntt            _r_e_s_u_l_t;;
       }} XXmmCCoommbbooBBooxxSSoorrttiinnggCCaallllbbaacckkSSttrruucctt,, **XXmmCCoommbbooBBooxxSSoorrttiinnggPPttrr;;

       _r_e_a_s_o_n         Indicates the reason why the  callback  was
                      activated. This is XXmmCCRR__SSOORRTTIINNGG.

       _e_v_e_n_t          Contains  always NNUULLLL and is just there for
                      compatibility reasons.

       _o_p_e_r_a_t_i_o_n      Indicates the operation to  carry  out  and
                      can   be   either   XXmmOOPP__IINNIITT,XXmmOOPP__DDOONNEE  or
                      XXmmOOPP__CCOOMMPPAARREE.

       _i_t_e_m___i_n_t_e_r_n_a_l  Must be set during the XXmmOOPP__IINNIITT  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
                      XXmmOOPP__CCOOMMPPAARREEorXXmmOOPP__DDOONNEE  this  field   will
                      contain  whatever you've put into it during
                      XXmmOOPP__IINNIITT.  For detailed information  refer
                      to the documentation "_T_h_e _C_o_m_b_o_B_o_x _W_i_d_g_e_t".

       _i_t_e_m           During XXmmOOPP__IINNIITT this field points  to  the
                      item  to be added to the list. When sorting
                      the list ( XXmmOOPP__CCOOMMPPAARREE) the field contains
                      the  address  of  an item in the list which
                      should be compared against the new item (as
                      remembered in _i_t_e_m___i_n_t_e_r_n_a_l).

       _r_e_s_u_l_t         When comparing an item (out of the list) in
                      _i_t_e_m with the new item  (as  remembered  in
                      _i_t_e_m___i_n_t_e_r_n_a_l)  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.

          RReeaassoonn               VVaalliidd FFiieellddss
       ---------------------------------------------
       XXmmOOPP__IINNIITT        _r_e_a_s_o_n, _e_v_e_n_t, _o_p_e_r_a_t_i_o_n,
                        _i_t_e_m, _i_t_e_m___i_n_t_e_r_n_a_l
       XXmmOOPP__DDOONNEE        _r_e_a_s_o_n, _e_v_e_n_t, _o_p_e_r_a_t_i_o_n,
                        _i_t_e_m___i_n_t_e_r_n_a_l
       XXmmOOPP__CCOOMMPPAARREE     _r_e_a_s_o_n, _e_v_e_n_t, _o_p_e_r_a_t_i_o_n,
                        _i_t_e_m, _i_t_e_m___i_n_t_e_r_n_a_l, _r_e_s_u_l_t

       For  more  information about controlling the sorting order
       see the acompanying documentation "_T_h_e _C_o_m_b_o_B_o_x _W_i_d_g_e_t".

     CCoonnvveenniieennccee rroouuttiinneess
       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.

       vvooiidd XXmmCCoommbbooBBooxxAAddddIItteemm((WWiiddggeett ww,, XXmmSSttrriinngg iitteemm,, iinntt ppooss))
              Add a new item to the list's contents. If XXmmNNssoorrtteedd
              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 XXmmLLiissttAAddddIItteemm.


       vvooiidd   XXmmCCoommbbooBBooxxAAddddIItteemmss((WWiiddggeett   ww,,   XXmmSSttrriinngg   **iitteemmss,,
              iinntt iitteemm__ccoouunntt,, iinntt ppooss))
              Similar to XXmmCCoommbbooBBooxxAAddddIItteemm.  Also  see  XXmmLLiissttAAdd--
              ddIItteemmss.


       vvooiidd  XXmmCCoommbbooBBooxxAAddddIItteemmUUnnsseelleecctteedd((WWiiddggeett  ww,,  XXmmSSttrriinngg
              iitteemm,, iinntt ppooss))
              See XXmmLLiissttAAddddIItteemmUUnnsseelleecctteedd.


       vvooiidd XXmmCCoommbbooBBooxxCClleeaarrIItteemmSSeelleeccttiioonn((WWiiddggeett ww))
              Deselects   all   currently   selected  items  when
              XXmmNNsseelleeccttiioonnPPoolliiccyy is XXmmSSIINNGGLLEE__SSEELLEECCTT.


       vvooiidd XXmmCCoommbbooBBooxxDDeelleetteeIItteemm((WWiiddggeett ww,, XXmmSSttrriinngg iitteemm))
              See XXmmLLiissttDDeelleetteeIItteemm.


       vvooiidd  XXmmCCoommbbooBBooxxDDeelleetteeIItteemmss((WWiiddggeett  ww,,   XXmmSSttrriinngg
              **iitteemmss,,   iinntt iitteemm__ccoouunntt))
              See XXmmLLiissttDDeelleetteeIItteemmss.


       vvooiidd XXmmCCoommbbooBBooxxDDeelleetteePPooss((WWiiddggeett ww,, iinntt ppooss))
              See XXmmLLiissttDDeelleetteePPooss.


       vvooiidd XXmmCCoommbbooBBooxxDDeelleetteeIItteemmssPPooss((WWiiddggeett ww,, iinntt iitteemm__ccoouunntt,,
              iinntt ppooss))
              See XXmmLLiissttDDeelleetteeIItteemmssPPooss.


       vvooiidd XXmmCCoommbbooBBooxxDDeelleetteeAAllllIItteemmss((WWiiddggeett ww))
              See XXmmLLiissttDDeelleetteeAAllllIItteemmss.


       vvooiidd  XXmmCCoommbbooBBooxxRReeppllaacceeIItteemmss((WWiiddggeett  ww,,  XXmmSSttrriinngg
              **oolldd__iitteemmss,, iinntt iitteemm__ccoouunntt,, XXmmSSttrriinngg **nneeww__iitteemmss))
              See XXmmLLiissttRReeppllaacceeIItteemmss.


       vvooiidd XXmmCCoommbbooBBooxxRReeppllaacceeIItteemmssPPooss((WWiiddggeett ww,, XXmmSSttrriinngg
              **nneeww__iitteemmss,, iinntt iitteemm__ccoouunntt,, iinntt ppoossiittiioonn))



Version 1.31              20 March 1995                        15





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


              See XXmmLLiissttRReeppllaacceeIItteemmssPPooss.


       BBoooolleeaann XXmmCCoommbbooBBooxxIItteemmEExxiissttss((WWiiddggeett ww,, XXmmSSttrriinngg iitteemm))
              See XXmmLLiissttIItteemmEExxiissttss.


       iinntt XXmmCCoommbbooBBooxxIItteemmPPooss((WWiiddggeett ww,, XXmmSSttrriinngg iitteemm))
              See XXmmLLiissttIItteemmPPooss.


       BBoooolleeaann   XXmmCCoommbbooBBooxxGGeettMMaattcchhPPooss((WWiiddggeett   ww,,  XXmmSSttrriinngg
              iitteemm,,  iinntt ****ppooss__lliisstt,, iinntt **ppooss__ccoouunntt))
              See XXmmLLiissttGGeettMMaattcchhPPooss.


       vvooiidd XXmmCCoommbbooBBooxxSSeelleeccttPPooss((WWiiddggeett ww,, iinntt ppooss,, BBoooolleeaann
              nnoottiiffyy))
              See XXmmLLiissttSSeelleeccttPPooss.


       vvooiidd  XXmmCCoommbbooBBooxxSSeelleeccttIItteemm((WWiiddggeett  ww,,  XXmmSSttrriinngg   iitteemm,,
              BBoooolleeaann nnoottiiffyy))
              See XXmmLLiissttSSeelleeccttIItteemm.


       iinntt XXmmCCoommbbooBBooxxGGeettSSeelleecctteeddPPooss((WWiiddggeett ww))
              This function  differs  from  XXmmLLiissttGGeettSSeelleecctteeddPPooss.
              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.


       vvooiidd XXmmCCoommbbooBBooxxCClleeaarrSSeelleeccttiioonn((WWiiddggeett ww,, TTiimmee ttiimmee))
              See XXmmTTeexxttFFiieellddCClleeaarrSSeelleeccttiioonn.


       BBoooolleeaann XXmmCCoommbbooBBooxxCCooppyy((WWiiddggeett ww,, TTiimmee ttiimmee))
              See XXmmTTeexxttFFiieellddCCooppyy.


       BBoooolleeaann XXmmCCoommbbooBBooxxCCuutt((WWiiddggeett ww,, TTiimmee ttiimmee))
              See XXmmTTeexxttFFiieellddCCuutt.


       XXmmTTeexxttPPoossiittiioonn XXmmCCoommbbooBBooxxGGeettIInnsseerrttiioonnPPoossiittiioonn((WWiiddggeett ww))
              See XXmmTTeexxttFFiieellddGGeettIInnsseerrttiioonnPPoossiittiioonn.


       XXmmTTeexxttPPoossiittiioonn XXmmCCoommbbooBBooxxGGeettLLaassttPPoossiittiioonn((WWiiddggeett ww))
              See XXmmTTeexxttFFiieellddGGeettLLaassttPPoossiittiioonn.





Version 1.31              20 March 1995                        16





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


       iinntt XXmmCCoommbbooBBooxxGGeettMMaaxxLLeennggtthh((WWiiddggeett ww))
              See XXmmTTeexxttFFiieellddGGeettMMaaxxLLeennggtthh.


       cchhaarr **XXmmCCoommbbooBBooxxGGeettSSeelleeccttiioonn((WWiiddggeett ww))
              See XXmmTTeexxttFFiieellddGGeettSSeelleeccttiioonn.


       BBoooolleeaann XXmmCCoommbbooBBooxxGGeettSSeelleeccttiioonnPPoossiittiioonn((WWiiddggeett  ww,,
              XXmmTTeexxttPPoossiittiioonn **lleefftt,, XXmmTTeexxttPPoossiittiioonn **rriigghhtt))
              See XXmmTTeexxttFFiieellddGGeettSSeelleeccttiioonnPPoossiittiioonn.


       cchhaarr **XXmmCCoommbbooBBooxxGGeettSSttrriinngg((WWiiddggeett ww))
              See XXmmTTeexxttFFiieellddGGeettSSttrriinngg.


       vvooiidd XXmmCCoommbbooBBooxxIInnsseerrtt((WWiiddggeett  ww,,  XXmmTTeexxttPPoossiittiioonn
              ppoossiittiioonn,,  cchhaarr **vvaalluuee))
              See XXmmTTeexxttFFiieellddIInnsseerrtt.


       BBoooolleeaann XXmmCCoommbbooBBooxxPPaassttee((WWiiddggeett ww))
              See XXmmTTeexxttFFiieellddPPaassttee.


       BBoooolleeaann XXmmCCoommbbooBBooxxRReemmoovvee((WWiiddggeett ww))
              See XXmmTTeexxttFFiieellddRReemmoovvee.


       vvooiidd   XXmmCCoommbbooBBooxxRReeppllaaccee((WWiiddggeett   ww,,   XXmmTTeexxttPPoossiittiioonn
              ffrroomm__ppooss,, XXmmTTeexxttPPoossiittiioonn ttoo__ppooss,, cchhaarr **vvaalluuee))
              See XXmmTTeexxttFFiieellddRReeppllaaccee.


       vvooiidd XXmmCCoommbbooBBooxxSSeettAAddddMMooddee((WWiiddggeett ww,, BBoooolleeaann ssttaattee))
              See XXmmTTeexxttFFiieellddSSeettAAddddMMooddee.


       vvooiidd  XXmmCCoommbbooBBooxxSSeettHHiigghhlliigghhtt((WWiiddggeett   ww,,   XXmmTTeexxttPPoossiittiioonn
              lleefftt,, XXmmTTeexxttPPoossiittiioonn rriigghhtt,, XXmmHHiigghhlliigghhttMMooddee mmooddee))
              See XXmmTTeexxttFFiieellddSSeettHHiigghhlliigghhtt.


       vvooiidd  XXmmCCoommbbooBBooxxSSeettIInnsseerrttiioonnPPoossiittiioonn((WWiiddggeett   ww,,
              XXmmTTeexxttPPoossiittiioonn ppoossiittiioonn))
              See XXmmTTeexxttFFiieellddSSeettIInnsseerrttiioonnPPoossiittiioonn.


       vvooiidd XXmmCCoommbbooBBooxxSSeettMMaaxxLLeennggtthh((WWiiddggeett ww,, iinntt mmaaxx__lleennggtthh))
              See XXmmTTeexxttFFiieellddSSeettMMaaxxLLeennggtthh.






Version 1.31              20 March 1995                        17





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


       vvooiidd  XXmmCCoommbbooBBooxxSSeettSSeelleeccttiioonn((WWiiddggeett  ww,,   XXmmTTeexxttPPoossiittiioonn
              ffiirrsstt,, XXmmTTeexxttPPoossiittiioonn llaasstt,, TTiimmee ttiimmee))
              See XXmmTTeexxttFFiieellddSSeettSSeelleeccttiioonn.


       vvooiidd XXmmCCoommbbooBBooxxSSeettSSttrriinngg((WWiiddggeett ww,, cchhaarr **vvaalluuee))
              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
              XXmmTTeexxttFFiieellddSSeettSSttrriinngg.


       vvooiidd XXmmCCoommbbooBBooxxSShhoowwPPoossiittiioonn((WWiiddggeett ww,, XXmmTTeexxttPPoossiittiioonn ppoossii--
              ttiioonn))
              See XXmmTTeexxttFFiieellddSShhoowwPPoossiittiioonn.


     TThhee DDiisslliikkeedd KKeeyybbooaarrdd FFooccuuss
       Now I'll  annotate  a  somewhat  tricky  subject.  If  the
       resource  XXmmNNppeerrssiisstteennttDDrrooppDDoowwnn  defaults  to  its initial
       value of FFaallssee, 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 XXmmNNppeerrssiisstteennttDDrrooppDDoowwnn to TTrruuee 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  XXmmNNttwwmmHHaannddlliinnggOOnn  to
       TTrruuee.  This resource will also work with other window man-
       agers.


     CCrreeaattiinngg aa CCoommbbooBBooxx
       Using the combo box in your own  programs  is  easy.  Just
       create  the  widget  with one of the innumerable X toolkit
       functions (like  XXttCCrreeaatteeMMaannaaggeeddWWiiddggeett  or  XXttVVaaCCrreeaatteeMMaann--
       aaggeeddWWiiddggeett).


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

       WWiiddggeett XXmmCCrreeaatteeCCoommbbooBBooxx((_p_a_r_e_n_t_, _n_a_m_e_, _a_r_g_l_i_s_t_, _a_r_g_c_o_u_n_t))
         WWiiddggeett         _p_a_r_e_n_t;
         SSttrriinngg         _n_a_m_e;
         AArrggLLiisstt        _a_r_g_l_i_s_t;
         CCaarrddiinnaall       _a_r_g_c_o_u_n_t;

       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 XXmmNNeeddiittaabbllee 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  XXmmCCoommbbooBBooxxAAdd--
       ddIItteemm((......)).  Which item the user selected  can  be  deter-
       mined by calling XXmmCCoommbbooBBooxxGGeettSSttrriinngg((......)).


       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 XXmmNNsseelleeccttiioonnCCaallllbbaacckk  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 XXmmNNeeddiittaabbllee set to  TTrruuee  use  another
       function:

            XmComboBoxSetString(ComboBox, string);

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



BBUUGGSS
       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.



CCOOPPYYRRIIGGHHTT
       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.



AAVVAAIILLAABBIILLIITTYY
       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



AAUUTTHHOORR
       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



RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
       "_T_h_e _C_o_m_b_o_B_o_x _W_i_d_g_e_t" documentation
       CCoorree((33XX)), XXmmCCoommppoossiittee((33XX)), XXmmLLiisstt((33XX)),  XXmmTTeexxttFFiieelldd((33XX))
       _D_o_u_g_l_a_s _A_d_a_m_s_: _T_h_e _H_i_t_c_h_h_i_k_e_r_'_s _G_u_i_d_e _t_o _t_h_e _G_a_l_a_x_y_.
       ffiillee::////113344..113300..116611..3300//aarrcc//ppuubb//uunniixx//hhttmmll//mmoottiiffccoorrnneerr..hhttmmll








































Version 1.31              20 March 1995                        21


