XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm) NNAAMMEE XmComboBox - The Combo Box widget class SSYYNNOOPPSSIISS ##iinncclluuddee <> 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