XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
NAME
XmComboBox - The Combo Box widget class
SYNOPSIS
#include <ComboBox.h>
Depending on your system's configuration the place of this
include file may vary. In doubt, contact your local system
administrator. Or run in circles and shout.
DESCRIPTION
The ComboBox widget allows the user to select elements
from a list of choices, and enter their own values in a
text widget. To conserve screen space, the list of choices
is shown only when the user selects the down arrow button.
The choices may then be selected from this list. The list
will automatically by removed when the user selects an
item in the list. When the list is removed, the item that
was selected will be placed in the text widget. Typing the
escape key when the list is up, cancels the list popup.
Classes
ComboBox inherits behaviour and resources from Core and
Composite, Constraint and XmManager classes.
The class pointer is xmComboBoxWidgetClass.
The class name is XmComboBox.
New Resources
The following table defines a set of widget resources used
by the programmer to specify data. The programmer can also
set the resource values for the inherited classes to set
attributes for this widget. To reference a resource by
name or by class in a .Xdefaults file, remove the XmN or
XmC prefix and use the remaining letters. To specify one
of the defined values for a resource in a .Xdefaults file,
remove the Xm prefix and use the remaining letters (in
either lowercase or uppercase, but include any underscores
between words). The codes in the access column indicate if
the given resource can be set at creation time (C), set by
using XtSetValues (S), retrieved by using XtGetValues (G),
or is not applicable (N/A).
XmComboBox Resource Set
-----------------------------------------------------------------
Name Default Access
Class Type
-----------------------------------------------------------------
XmNactivateCallback NULL C
XmCCallback XtCallbackList
-----------------------------------------------------------------
Version 1.31 20 March 1995 1
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmNalignment XmALIGNMENT_CENTER CSG
XmCAlignment unsigned char
-----------------------------------------------------------------
XmNarrowSpacingOn False CSG
XmNCArrowSpacingOn Boolean
-----------------------------------------------------------------
XmNautomaticSelection False CSG
XmCAutomaticSelection Boolean
-----------------------------------------------------------------
XmNblinkRate 500 CSG
XmCBlinkRate int
-----------------------------------------------------------------
XmNcolumns dynamic CSG
XmCColumns short
-----------------------------------------------------------------
XmNcursorPosition 0 CSG
XmCCursorPosition XmTextPosition
-----------------------------------------------------------------
XmNcursorPositionVisible True CSG
XmCCursorPositionVisible Boolean
-----------------------------------------------------------------
XmNdefaultActionCallback NULL CSG
XmCCallback XtCallbackList
-----------------------------------------------------------------
XmNdropDownCallback NULL CSG
XmCDropDownCallback XtCallbackList
-----------------------------------------------------------------
XmNdropDownCursor center_ptr CSG
XmCDropDownCursor Cursor
-----------------------------------------------------------------
XmNdropDownOffset dynamic CSG
XmCDropDownOffset Position
-----------------------------------------------------------------
XmNeditable False CG
XmCEditable Boolean
-----------------------------------------------------------------
XmNfontList dynamic CSG
XmCFontList XmFontList
-----------------------------------------------------------------
XmNitemCount 0 CSG
XmCItemCount int
-----------------------------------------------------------------
XmNitems NULL CSG
XmCItems XmStringTable
-----------------------------------------------------------------
XmNlabelFontList dynamic CSG
XmCLabelFontList XmFontList
-----------------------------------------------------------------
XmNlabelInsensitivePixmap XmUNSPECIFIED_PIXMAP CSG
XmCLabelInsensitivePixmap Pixmap
-----------------------------------------------------------------
XmNlabelMarginBottom 0 CSG
Version 1.31 20 March 1995 2
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmCLabelMarginBottom Dimension
-----------------------------------------------------------------
XmNlabelMarginHeight 2 CSG
XmCLabelMarginHeight Dimension
-----------------------------------------------------------------
XmNlabelMarginLeft 0 CSG
XmCLabelMarginLeft Dimension
-----------------------------------------------------------------
XmNlabelMarginRight 0 CSG
XmCLabelMarginRight Dimension
-----------------------------------------------------------------
XmNlabelMarginTop 0 CSG
XmCLabelMarginTop Dimension
-----------------------------------------------------------------
XmNlabelMarginWidth 0 CSG
XmCLabelMarginWidth Dimension
-----------------------------------------------------------------
XmNlabelPixmap XmUNSPECIFIED_PIXMAP CSG
XmCLabelPixmap Pixmap
-----------------------------------------------------------------
XmNlabelString dynamic CSG
XmCXmString XmString
-----------------------------------------------------------------
XmNlabelType XmSTRING CSG
XmCLabelType unsigned char
-----------------------------------------------------------------
XmNlistMarginHeight 0 CSG
XmCListMarginHeight Dimension
-----------------------------------------------------------------
XmNlistMarginWidth 0 CSG
XmCListMarginWidth Dimension
-----------------------------------------------------------------
XmNlistSizePolicy XmVARIABLE CG
XmCListSizePolicy unsigned char
-----------------------------------------------------------------
XmNlistSpacing 0 CSG
XmCListSpacing Dimension
-----------------------------------------------------------------
XmNmarginHeight 5 CSG
XmCMarginHeight Dimension
-----------------------------------------------------------------
XmNmarginWidth 5 CSG
XmCMarginWidth Dimension
-----------------------------------------------------------------
XmNmaxLength largest integer CSG
XmCMaxLength int
-----------------------------------------------------------------
XmNmodifyVerifyCallback NULL CSG
XmCCallback XtCallbackList
-----------------------------------------------------------------
XmNmotionVerifyCallback NULL CSG
XmCCallback XtCallbackList
-----------------------------------------------------------------
Version 1.31 20 March 1995 3
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmNpersistentDropDown False CSG
XmCPersistentDropDown Boolean
-----------------------------------------------------------------
XmNscrollBarDisplayPolicy XmAS_NEEDED CSG
XmCScrollBarDisplayPolicy unsigned char
-----------------------------------------------------------------
XmNselectionCallback NULL CSG
XmCCallback XtCallbackList
-----------------------------------------------------------------
XmNselectionPolicy XmBROWSE_SELECT CG
XmCSelectionPolicy unsigned char
-----------------------------------------------------------------
XmNselectThreshold 5 CSG
XmCSelectThreshold int
-----------------------------------------------------------------
XmNshowLabel False CG
XmCShowLabel Boolean
-----------------------------------------------------------------
XmNsorted False CSG
XmCSorted Boolean
-----------------------------------------------------------------
XmNsortingCallback NULL CSG
XmCCallback XtCallbackList
-----------------------------------------------------------------
XmNsquareArrow False CSG
XmCSquareArrow Boolean
-----------------------------------------------------------------
XmNstaticList False CSG
XmCStaticList Boolean
-----------------------------------------------------------------
XmNstringDirection dynamic CSG
XmCStringDirection XmStringDirection
-----------------------------------------------------------------
XmNtwmHandlingOn False CSG
XmCTwmHandlingOn Boolean
-----------------------------------------------------------------
XmNtopItemPostion 1 G
XmCTopItemPostion int
-----------------------------------------------------------------
XmNunselectionCallback NULL CSG
XmCCallback XtCallbackList
-----------------------------------------------------------------
XmNvalue "" CSG
XmCValue String
-----------------------------------------------------------------
XmNvalueChangedCallback NULL CSG
XmCCallback XtCallbackList
-----------------------------------------------------------------
XmNvisibleItemCount 8 CSG
XmCVisibleItemCount Int
-----------------------------------------------------------------
XmNactivateCallback
Specifies a list of callbacks to be called when the
Version 1.31 20 March 1995 4
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
user presses either the key "Enter" or "Activate".
The type of the structure passed to this callback
is XmAnyCallbackStruct and the reason is
XmCR_ACTIVATE.
XmNalignment
The alignment (left to right) for the label's text
or pixmap. Possible values are XmALIGN-
MENT_BEGINNING, XmALIGNMENT_CENTER, and XmALIGN-
MENT_END.
XmNautomaticSelection
Indicates whether the XmNselectionCallback is
invoked each time the user moves into a new item if
XmNautomaticSelection is True and the selection
mode is XmBROWSE_SELECT. If set to False the XmNs-
electionCallback is not invoked until the user
releases the mouse button.
XmNarrowSpacingOn
Indicates whether a gap is displayed between the
arrow button and the text input field if this
resource is set to True and XmNeditable is also set
to True. If this resource is set to False the
combo box widget will never display a gab between
the arrow button and the text area, irrespective of
the setting of XmNeditable. Note that setting
XmNarrowSpacingOn to False doesn not conform to
common GUI styles. And it prevents the user from
easily recognizing whether the combo box is
editable or not.
XmNblinkRate
The time in milliseconds that the cursor spends
being visible or invisible. A value of 0 prevents
the cursor from blinking.
XmNborderWidth
That's no new resource but is already introduced in
the core class. This class overrides the default
value and sets it to zero. You can however override
it again if you're dissatisfied with the new
default setting.
XmNcolumns
Specifies the initial width of the input field mea-
sured in character spaces. The default value
depends on the value of the width of the combo box.
XmNcursorPosition
Indicates the position in the text where the insert
cursor is to be located. Its position is the offset
of characters and it starts with offset 0 at the
beginning of the text.
Version 1.31 20 March 1995 5
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmNcursorPositionVisible
Flags whether the insert cursor position is marked
by a blinking cursor.
XmNdefaultActionCallback
Specifies a list of callbacks that is called every
time an item is double clicked. The reason is
XmCR_DEFAULT_ACTION. Please remember that you
can't use this callback if XmNstaticList is False
because the list is immediatly hidden after the
user selected an item from the list. Thus the user
can't double click on any item within the list.
XmNdropDownCallback
This is a list of callbacks to be called when the
list is about to be shown or hidden. The reasons
are XmCR_SHOW_LIST or XmCR_HIDE_LIST.
XmNdropDownCursor
Specifies the cursor to be used whenever the mouse
cursor is within the drop down list.
XmNdropDownOffset
Specifies the distance between the left border of
the list and the left border of the input field.
The default value is set to the width of the arrow
button. Only positive values are allowed for XmN-
dropDownOffset, negative ones will be ignored.
XmNeditable
Specifies the type of combo box. If set to True,
the combo box contains an editable input field.
Therefore, the user is free to select entries out
of the list and to enter new text or modify it. In
the other case, with XmNeditable set to False the
user can solely browse in and select entries out of
the list.
XmNfontList
Indicates the font list to be used for the input
field and the list. If the value is NULL at ini-
tialization, it is initialized by looking up the
parent hierarchy of the widget for an ancestor that
is a subclass of XmBulletinBoard, XmVendorShell or
XmMenuShell. If such an ancestor is found, it's
font list will be taken by the combo box widget.
XmNitemCount
Specifies the total number of items in the list.
XmNitems
Points to an array of compound strings representing
the items to be displayed in the list. By means of
this a program can find out what items the list
Version 1.31 20 March 1995 6
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
contains. It is also possible to set the contents
of the list box in one step by setting this
resource to a new array of compound strings. Please
remember: always set XmNitems and XmNitemCount
together in the same call to XtSetValues or
XtVaSetValues. If you ignore this rule the combo
box will ignore you and your attempt to set these
resources.
XmNlabelInsensitivePixmap
Specifies a pixmap used as the button face if XmN-
labelType is set to XmPIXMAP and the combo box wid-
get is insensitive.
XmNlabelPixmap
Specifies a pixmap to be displayed to the left of
the input field if XmNlabelType is XmPIXMAP and
XmNshowLabel is True (of course).
XmNlabelString
Specifies the the compound string to be displayed
if XmNlabelType is set to XmSTRING and XmNshowLabel
is True.
XmNlabelType
The type of label (either string or pixmap). Possi-
ble values are XmPIXMAP and XmSTRING.
XmNlabelMarginTop, XmNlabelMarginBottom
XmNlabelMarginLeft, XmNlabelMarginRight
The amount of space between one side of the label
and the nearest margin.
XmNlabelMarginHeight, XmNlabelMarginWidth
The spacing between one side of the label and the
nearest edge of a shadow.
XmNlistMarginHeight, XmNlistMarginWidth
The height or width of the margin between the bor-
der of the list and the items in the list.
XmNlistSizePolicy
Controls the reaction of the list when an item
grows horizontally beyond the current width of the
list and XmNstaticList is set to True. If set to
XmCONSTANT, the list does not grow, and a horizon-
tal scroll bar is shown. If this resource is set to
XmVARIABLE, the list instead trys to grow such that
it match the size of the longest item, thus no hor-
izontal scroll bar will appear. When XmNlist-
SizePolicy is the list will again try to grow but
in case the width of the longest item in the list
is wider than the viewing area of the list a hori-
zontal scroll bar appears.
Version 1.31 20 March 1995 7
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmNlistSpacing
The spacing between items in the list.
XmNmarginHeight
Specifies the distance between the top and the bot-
tom of the widget window and the text displayed in
the input field.
XmNmarginWidth
Like XmNmarginHeight this resource specifies the
distance between the left and the right border of
the widget window and the text.
XmNmaxLength
Specifies the maximum length of the text string
that can be entered from the keyboard into the
input field of the combo box. Strings that are put
into the input field using XmComboBoxSetString
ignore this resource.
XmNmodifyVerifyCallback
Contains a list of callbacks called before text is
deleted from or inserted into the text area of the
combo box widget. The callbacks are called only if
XmNeditable is set to True. The reason is
XmCR_MODIFYING_TEXT_VALUE and the type of the
structure passed to this callback is XmComboBox-
TextVerifyCallbackStruct.
XmNmotionVerifyCallback
Specifies the list of callbacks that is called
before the insert cursor gets moved to another
position. The reason is XmCR_MOVING_INSERT_CURSOR
and the type of the structure whose address is
passed to the callback is XmComboBoxTextVerifyCall-
back-Struct.
XmNscrollBarDisplayPolicy
Controls the display of the vertical scroll bar in
the list when XmNstaticList is set to True.When
XmNscrollBarDisplayPolicy is set to XmAS_NEEDED,
the vertical scroll bar is displayed only when the
list contains more items than can be currently dis-
played. If set to XmSTATIC the vertical scroll bar
is always displayed.
XmNpersistentDropDown
Welcome to the sad section in the life of X11
applications. This resource and the inherent prob-
lems are due to the focus policy of the window man-
ager you're using. See the further details in the
later sections.
Version 1.31 20 March 1995 8
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmNselectionCallback
Specifies a list of callbacks that is called when
an item is selected. The reason is
XmCR_SINGLE_SELECT. The callbacks are NOT called
when the user browses through the items in the
list.
XmNselectionPolicy
This resource controls whether the user can dese-
lect the currently selected item within a combo
box. The default value is XmBROWSE_SELECT, so
always one item gets selected if the combo box is
editable. In the case of XmSINGLE_SELECT the user
may deselect the current item either by clicking on
it in the drop down list or pressing the key
"Delete". Other values for XmNselectionPolicy are
currently not allowed. (Multiple selections will be
probably availabe with the next release.)
XmNselectThreshold
Specifies the amount of pixels the mouse must move
until the selection of text is recognized in click
and drag mode.
XmNshowLabel
Specifies, whether a label containing text or a
pixmap should be displayed on the left side of the
combo box. This resource can only be specified dur-
ing the creation of the combo box, afterwards it
will have no effect.
XmNsorted
Specifies whether the items in the list are sorted
or not In an unsorted list, the items are shown in
the order in which they're put into the list. When
adding an item to a sorted list, this item will be
put at the right place (alphabetically sorted).
XmNsortingCallback
Contains a list of callbacks that is called when-
ever a new item is added to the combo box widget
and XmNsorted is True. The reason is XmCR_SORTING
and the type of the structure whose address is
passed to the callback is XmComboBoxSortingCall-
back-Struct. For detailed information see the fol-
lowing sections.
XmNsquareArrow
Controls the width of the arrow button in respect
to its height. If this resource is True the arrow
button is always layed out square. Otherwise the
arrow button's width will be approximatly 4/5th of
its height.
Version 1.31 20 March 1995 9
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmNstaticList
Controls whether the list is always statically dis-
played right below the text input area of the combo
box if set to True. If you use a combo box with
XmNstaticList set to True and XmNeditable set to
False you should consider using a simple list wid-
get instead.
XmNstringDirection
Specifies the initial direction to draw the string
(from the left to the right or in the opposite
direction). The whole story seems to be incompre-
hensible... therefore this resource is provided for
completeness only.
XmNtwmHandlingOn
If you have trouble with the list then this
resource may help you. Set it to True, if the list
gets hidden at the moment the mouse cursor enters
the list.
XmNtopItemPosition
This resource is intended as an informal hint. It
specifies the index of the item which is displayed
at the visible top of the list.
XmNvalue
Contains the text of the input field. This also
concerns combo boxes which are not editable (
XmNeditable set to False).
XmNunselectionCallback
Specifies a list of callbacks that is called when-
ever the currently selected item is deselected and
no other item gets selected. This callback is acti-
vated only when XmNselectionPolicy is XmSIN-
GLE_SELECT. The reason is XmCR_UNSELECT. The type
of the structure whose address is passed to this
callback is XmAnyCallbackStruct.
XmNvalue
Contains the text of the input field. This also
concerns combo boxes which are not editable (
XmNeditable set to False).
XmNvalueChangedCallback
Specifies a list of callbacks to be called after
text is deleted from or inserted into the text area
of the combo box widget. The reason is
XmCR_VALUE_CHANGED. The type of the structure
whose address is passed to this callback is XmAny-
CallbackStruct.
Version 1.31 20 March 1995 10
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmNvisibleItemCount
Specifies the number of items that can fit in the
visible space of the list. The combo box uses this
value to determine the height of its list.
Inherited Resources
XmComboBox inherits behaviour and resources from the fol-
lowing superclasses. For a complete description of each
resource, refer to the man page for that superclass.
Callback Information
A pointer to the following structure is passed to the
XmNdropDownCallback callback:
typedef struct {
int reason;
XEvent *event;
} XmComboBoxDropDownCallbackStruct;
reason Within this structure, reason indicates the
reason why the callback was activated. This
can be XmCR_SHOW_LIST as well as
XmCR_HIDE_LIST. A callback is called with
the reason XmCR_SHOW_LIST just before the
list is dropped down, whereas the callback
is called with XmCR_HIDE_LIST after the
list is hidden.
event Points to the XEvent, which triggered the
callback. May be NULL if the callback is
triggered by a call to XmComboBoxShowList
or XmComboBoxHideList.
A pointer to the following structure is passed to the
XmNactivateCallback callback:
typedef struct {
int reason;
XEvent *event;
} XmAnyCallbackStruct;
reason Indicates why the callback was invoked.
This is XmCR_ACTIVATE for XmNactivateCall-
back.
event Points to the XEvent, which triggered the
callback.
A pointer to the following structure is passed to the
XmNselectionCallback and XmNdefaultActionCallback:
typedef struct {
int reason;
Version 1.31 20 March 1995 11
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XEvent *event;
XmString value;
int index;
} XmComboBoxSelectionCallbackStruct, XmComboBoxDefaultAc-
tionCallbackStruct;
reason Within this structure, reason indicates the
reason why the callback was activated. At
this time, the reason can be either
XmCR_SINGLE_SELECT or XmCR_BROWSE_SELECT
depending on the setting of XmNselection-
Policy. It indicates that the user
selected a (potentially new) item in the
list. Whether this callback is activated
every time the user moves into a new item
of the list or only when the user releases
the mouse button is controlled through the
setting of XmNautomaticSelection.
event Points to the XEvent, which triggered the
callback.
value Points to a XmString, which contains the
text of the current selected item. This
XmString must never be freed or changed by
the called program code!
index Index (starting from 1) of the currently
selected item in the list.
A pointer to the following structure is passed to the
XmNunselectionCallback callback:
typedef struct {
int reason;
XEvent *event;
} XmComboBoxUnselectionCallbackStruct;
reason Indicates why the callback was invoked.
This is XmCR_UNSELECT.
event Points to the XEvent, which triggered the
callback.
A pointer to the following structure is passed to the
XmNmodifyVerifyCallback and XmNmotionVerifyCallback call-
backs:
typedef struct {
int reason;
XEvent *event;
Boolean doit;
Position currInsert, newInsert;
Position startPos, endPos;
Version 1.31 20 March 1995 12
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmTextBlock text;
} XmComboBoxTextVerifyCallbackStruct, *XmComboBoxTextVeri-
fyPtr;
reason Indicates the reason why the callback was
activated. This can be either
XmCR_MODIFYING_TEXT_VALUE or
XmCR_MOVING_INSERT_CURSOR.
event Points to the XEvent, which triggered the
callback.
doit Indicates whether the offending action
should be performed. Setting this field of
the callback structure to False denies the
action.
currInsert Specifies the current position of the
insert cursor.
Indicates the position at which the user
attempts to position the cursor.
startPos Indicates the starting position of the text
to modify. If the reason is
XmCR_MOVING_INSERT_CURSOR this value is the
same as currInsert.
endPos Specifies the ending position of the text
to modify. If no text is replaced or
deleted, then the value will be the same as
startPos. If the reason is
XmCR_MODIFYING_TEXT_VALUE this value is the
same as currInsert.
text Holds the address of a structure of type
XmTextBlockRec which holds the textual
information to be inserted.
The following table describes the reasons why the individ-
ual verification callback structure fields are valid.
Reason Valid Fields
-----------------------------------------------------
XmCR_MODIFYING_TEXT_VALUE reason, event, doit,
startPos, endPos, text
XmCR_MOVING_INSERT_CURSOR reason, event, doit,
currInsert, newInsert,
A pointer to the following structure is passed to the XmN-
sortingCallback callback: typedef struct {
int reason;
XEvent *event;
Version 1.31 20 March 1995 13
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
int operation;
void *item_internal;
XmString item;
int result;
} XmComboBoxSortingCallbackStruct, *XmComboBoxSortingPtr;
reason Indicates the reason why the callback was
activated. This is XmCR_SORTING.
event Contains always NULL and is just there for
compatibility reasons.
operation Indicates the operation to carry out and
can be either XmOP_INIT,XmOP_DONE or
XmOP_COMPARE.
item_internal Must be set during the XmOP_INIT operation
to a suitable representation of the new
item which is to be added to the list. In
all subsequent calls to this callback with
XmOP_COMPAREorXmOP_DONE this field will
contain whatever you've put into it during
XmOP_INIT. For detailed information refer
to the documentation "The ComboBox Widget".
item During XmOP_INIT this field points to the
item to be added to the list. When sorting
the list ( XmOP_COMPARE) the field contains
the address of an item in the list which
should be compared against the new item (as
remembered in item_internal).
result When comparing an item (out of the list) in
item with the new item (as remembered in
item_internal) the result has to be stored
into this structure's field.
The following table describes which individual callback
structure fields are valid during which operations.
Reason Valid Fields
---------------------------------------------
XmOP_INIT reason, event, operation,
item, item_internal
XmOP_DONE reason, event, operation,
item_internal
XmOP_COMPARE reason, event, operation,
item, item_internal, result
For more information about controlling the sorting order
see the acompanying documentation "The ComboBox Widget".
Convenience routines
ComboBox has a number of convenience routines to control
Version 1.31 20 March 1995 14
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
the behavior and contents of its children.
void XmComboBoxAddItem(Widget w, XmString item, int pos)
Add a new item to the list's contents. If XmNsorted
is set to True, the new item is inserted alphabeti-
cally. If the list is unsorted, the same assump-
tions can be applied as with XmListAddItem.
void XmComboBoxAddItems(Widget w, XmString *items,
int item_count, int pos)
Similar to XmComboBoxAddItem. Also see XmListAd-
dItems.
void XmComboBoxAddItemUnselected(Widget w, XmString
item, int pos)
See XmListAddItemUnselected.
void XmComboBoxClearItemSelection(Widget w)
Deselects all currently selected items when
XmNselectionPolicy is XmSINGLE_SELECT.
void XmComboBoxDeleteItem(Widget w, XmString item)
See XmListDeleteItem.
void XmComboBoxDeleteItems(Widget w, XmString
*items, int item_count)
See XmListDeleteItems.
void XmComboBoxDeletePos(Widget w, int pos)
See XmListDeletePos.
void XmComboBoxDeleteItemsPos(Widget w, int item_count,
int pos)
See XmListDeleteItemsPos.
void XmComboBoxDeleteAllItems(Widget w)
See XmListDeleteAllItems.
void XmComboBoxReplaceItems(Widget w, XmString
*old_items, int item_count, XmString *new_items)
See XmListReplaceItems.
void XmComboBoxReplaceItemsPos(Widget w, XmString
*new_items, int item_count, int position)
Version 1.31 20 March 1995 15
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
See XmListReplaceItemsPos.
Boolean XmComboBoxItemExists(Widget w, XmString item)
See XmListItemExists.
int XmComboBoxItemPos(Widget w, XmString item)
See XmListItemPos.
Boolean XmComboBoxGetMatchPos(Widget w, XmString
item, int **pos_list, int *pos_count)
See XmListGetMatchPos.
void XmComboBoxSelectPos(Widget w, int pos, Boolean
notify)
See XmListSelectPos.
void XmComboBoxSelectItem(Widget w, XmString item,
Boolean notify)
See XmListSelectItem.
int XmComboBoxGetSelectedPos(Widget w)
This function differs from XmListGetSelectedPos.
The list in a combo box can contain only one
selected item. Therefore this function returns the
index of the selected item in the list or zero, if
none is currently selected.
void XmComboBoxClearSelection(Widget w, Time time)
See XmTextFieldClearSelection.
Boolean XmComboBoxCopy(Widget w, Time time)
See XmTextFieldCopy.
Boolean XmComboBoxCut(Widget w, Time time)
See XmTextFieldCut.
XmTextPosition XmComboBoxGetInsertionPosition(Widget w)
See XmTextFieldGetInsertionPosition.
XmTextPosition XmComboBoxGetLastPosition(Widget w)
See XmTextFieldGetLastPosition.
Version 1.31 20 March 1995 16
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
int XmComboBoxGetMaxLength(Widget w)
See XmTextFieldGetMaxLength.
char *XmComboBoxGetSelection(Widget w)
See XmTextFieldGetSelection.
Boolean XmComboBoxGetSelectionPosition(Widget w,
XmTextPosition *left, XmTextPosition *right)
See XmTextFieldGetSelectionPosition.
char *XmComboBoxGetString(Widget w)
See XmTextFieldGetString.
void XmComboBoxInsert(Widget w, XmTextPosition
position, char *value)
See XmTextFieldInsert.
Boolean XmComboBoxPaste(Widget w)
See XmTextFieldPaste.
Boolean XmComboBoxRemove(Widget w)
See XmTextFieldRemove.
void XmComboBoxReplace(Widget w, XmTextPosition
from_pos, XmTextPosition to_pos, char *value)
See XmTextFieldReplace.
void XmComboBoxSetAddMode(Widget w, Boolean state)
See XmTextFieldSetAddMode.
void XmComboBoxSetHighlight(Widget w, XmTextPosition
left, XmTextPosition right, XmHighlightMode mode)
See XmTextFieldSetHighlight.
void XmComboBoxSetInsertionPosition(Widget w,
XmTextPosition position)
See XmTextFieldSetInsertionPosition.
void XmComboBoxSetMaxLength(Widget w, int max_length)
See XmTextFieldSetMaxLength.
Version 1.31 20 March 1995 17
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
void XmComboBoxSetSelection(Widget w, XmTextPosition
first, XmTextPosition last, Time time)
See XmTextFieldSetSelection.
void XmComboBoxSetString(Widget w, char *value)
At least Motif 1.1 contains a very anoying bug. If
you try to set the contents of an XmTextField to an
empty string (""), you'll get garbage, when asking
the XmTextField for its contents afterwards. This
interface function provides a work around. Also see
XmTextFieldSetString.
void XmComboBoxShowPosition(Widget w, XmTextPosition posi-
tion)
See XmTextFieldShowPosition.
The Disliked Keyboard Focus
Now I'll annotate a somewhat tricky subject. If the
resource XmNpersistentDropDown defaults to its initial
value of False, one can observe the following effect (this
may be annoying).
When the user drops down the list and then moves the mouse
cursor out of the window where the combo box resides in,
the list will be hidden. This is because the widget lost
the keyboard focus. Some users are irritated because they
didn't expect that behavior, because they just moved the
mouse to get it out of the way. If your window manager's
focus policy is "pointer focus", i.e. if you move the
pointer into another window, that window will automati-
cally get the keyboard focus. On the other hand, if your
window manager's focus policy is "explicit", you have to
move the pointer into another window and click a mouse
button to give that window the keyboard focus. This is
often referred to as the "click-to-type" method. In
"explicit" mode, you will never see the list's annoying
behavior.
To bypass this behavior on some window managers a really
dirty hack was used. The user can activate that hack, if
he sets XmNpersistentDropDown to True in the application's
resources. Sorry, on some window managers this will not
fix the annoying behavior.
Try it if you like - but don't complain at me if it
doesn't work as expected. But at least it worked on the
author's machine: a cute little SGI Indigo running 4dwm as
the window manager.
On some other window managers like twm you will face
another problem: the list gets hidden as soon as the mouse
Version 1.31 20 March 1995 18
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
cursor enters the list. Try to set XmNtwmHandlingOn to
True. This resource will also work with other window man-
agers.
Creating a ComboBox
Using the combo box in your own programs is easy. Just
create the widget with one of the innumerable X toolkit
functions (like XtCreateManagedWidget or XtVaCreateMan-
agedWidget).
Specify as the widget class xmComboBoxWidgetClass - that's
all. There is also a so-called creation convenience func-
tion called XmCreateComboBox, but it isn't really needed.
Widget XmCreateComboBox(parent, name, arglist, argcount)
Widget parent;
String name;
ArgList arglist;
Cardinal argcount;
Somewhere in your program you'll need something like the
following code fragment:
Widget ComboBox;
ComboBox = XtVaCreateManagedWidget("combobox",
xmComboBoxWidgetClass, Parent,
XmNeditable, True or False,
other Resources...
NULL);
Setting the resource XmNeditable is not absolutely neces-
sary, but it's better to do so.
After creation, items can be added to the combo box's list
by means of interface functions like XmComboBoxAd-
dItem(...). Which item the user selected can be deter-
mined by calling XmComboBoxGetString(...).
If you want to preselect an item (that is setting a
default item to the input field of the combo box) you can
use several convenience functions. On a combo box with a
non editable input field there are two ways to select an
item:
XmComboBoxSelectPos(ComboBox, item #, False);
or:
Version 1.31 20 March 1995 19
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
XmComboBoxSelectItem(ComboBox, itemString, False);
The third parameter in these two function calls indicates
whether the XmNselectionCallback should be called. The
only difference between these functions is the first one
is expecting an item number whereas the second one expects
a XmString. The list is then searched for this string and
if it is found the input field will be updated.
On a combo box with XmNeditable set to True use another
function:
XmComboBoxSetString(ComboBox, string);
This sets the contents of the text input field to string.
BUGS
Not more than currently available in Motif 1.2.3 or Motif
1.2.4, but less than in the upcomming Motif 2.0. Report
bugs to albrecht@igpm.rwth-aachen.de. Include a thoroughly
description, and say which version of the ComboBox widget
you are using.
COPYRIGHT
Copyright 1993, 1994 Harald Albrecht.
The ComboBox widget is free software; you can redistribute
it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Founda-
tion; either version 2, or (at your option) any later ver-
sion.
AVAILABILITY
The most recent released version of the ComboBox widget is
always available for anonymous ftp from either
ftp.x.org (198.112.44.100)
/contrib/widgets/motif/ComboBox
or from
ftp.informatik.rwth-aachen.de (137.226.112.172)
/pub/packages/ComboBox
AUTHOR
Author of Software & Documentation:
Version 1.31 20 March 1995 20
XmComboBox(3Xm) Harry's Motif Tools XmComboBox(3Xm)
Harald Albrecht
Institut fuer Geometrie und Praktische Mathematik
RWTH Aachen, Bundesrepublik Deutschland
e-mail: albrecht@igpm.rwth-aachen.de
English Documentation:
Chris Marotz
Sterling Software ITD
e-mail: marotz@itd.sterling.com
RELATED INFORMATION
"The ComboBox Widget" documentation
Core(3X), XmComposite(3X), XmList(3X), XmTextField(3X)
Douglas Adams: The Hitchhiker's Guide to the Galaxy.
file://134.130.161.30/arc/pub/unix/html/motifcorner.html
Version 1.31 20 March 1995 21
