Combo Box Item

The combo box item consists of a popup list and a selection field. The popup list presents the options a user can select and the selection field displays the current selection. The selection field may optionally be an edit field used to enter text not in the list. Any new values are then added to the list of available options.

v8combobox.jpg

Item List Specification

The DialogItemRsc field extent specifies the location and size of the combo box item selection field. The x position specifies the location of the left side of the selection field, and the y position specifies either the top of the selection field or, if the `label on top' attribute is set, the top of the label. If width is 0, the width of the ComboBox selection field is calculated using the maximum number of characters the field cancontain. Specifying an explicit width is recommended. If height is 0, the height is calculated using the current dialog font.

The type field should contain ComboBox.

The ID determines the DItem_ComboBoxRsc instance to load.

The attributes field can be ON or OFF, and optionally combined with hidden. It will usually be ON.

The itemArg field is unused and should usually be set to 0.

The label field can override the label contained in the DItem_ComboBoxRsc instance.

The auxInfo field can currently override only the access string contained in the DItem_ComboBoxRsc instance.

The following is an example of an item list specification for the ComboBox item:

{{X_POS, Y_POS, CMBX_W, 0}, ComboBox, COMBOBOXID_STATES, ON, 0,"",""},

Item Resource Specification

The ComboBox resource is defined in a resource file with the following structure:

typedef struct ditem_comboboxrsc
{
ULong commandNumber;
ULong commandSource;
long synonymsId;
ULong helpInfo;
ULong helpSource;
long itemHookId;
long itemHookArg;
byte maxSize; // max # of chars in text field
char formatToDisplay[16]; // format str to convert from internal
char formatToInternal[16]; // convert to internal from display str
char minimum[16]; // minimum value
char maximum[16]; // maximum value
ULong mask; // only used with integer types
long stringListId; // Id of initial string list used
long nRows; // Number of rows to show in list
UShort gapWidth; // Gap between textedit & button
UShort listWidth; // Width of dropdown listbox
UShort valueColumnIndex; // Index of Column to get value from
ULong attributes; // other attributes
#if defined (resource)
char label[];
char accessStr[];
DItem_ListColumnRsc listColumns[];
#else
long labelLength;
char label[1];
#endif
#if defined (resource)
resourceclass DItem_ComboBoxRsc RTYPE_ComboBox extendedAttributes;
#define ComboBox RTYPE_ComboBox
#endif

For consistency with MicroStation's dialog boxes, a combo box item's label should end with a colon.

The following fields are described in the Text Item resource specification and are functionally identical in the combo box :

maxSize, formatToDisplay, formatToInternal, minimum, maximum and mask.

The following fields are described in the List Box Item resource specification and are functionally identical in the combo box :

nRows and listColumns.

The DItem_ComboBoxRsc structure has the following unique fields. (See "Common item resource fields" for a description of any field not in this table.)

Field Description
stringListId Resource Id of a String List to be used to fill the popup list.
gapWidth The gap between the selection field and the popup list activation button (specified in dialog coordinates (dcoords)).
listWidth The width of popup List Box (specified in dialog coordinates (dcoords)).
valueColumnIndex Specifies the index of the list column to obtain the selection field value from.
attributes Specifies the attributes of the combo box item. It is constructed by combining the constants from the attributes table (below) with the logical OR operator.

Valid constants for use with the attributes field:

Constant Description
COMBOATTR_READONLY The selection field is read only; no editting is allowed
COMBOATTR_SORT Sort members in string list initially and as new values are added
COMBOATTR_DRAWPREFIXICON Draw a specified icon preceding the text in the popup List Box
COMBOATTR_INDEXISVALUE Use the list box member index as the value; not the actual value of the list box member
COMBOATTR_AUTOADDNEWSTRINGS Automatically add new values to the string list after they are entered in the selection field
COMBOATTR_LABELABOVE Place the label above the selection field

The following attribute is new in MicroStation V8:

Constant Description
COMBOATTR_USEMODELVALUE Indicates the value of the ComboBox is to be the internal value stored in the List Model cell, as opposed to the actual string displayed or the row index.

The following are two examples of a ComboBox item resource.

DItem_ComboBoxRsc COMBOBOXID_STATES=
{
NOCMD, LCMD, NOSYNONYM, NOHELP, MHELP, HOOKID_ComboStates,
NOARG, 2, "", "", "", "", NOMASK, STRLISTID_ComboBoxStates, 15, 0,
TW*4, 0, COMBOATTR_READONLY | COMBOATTR_INDEXISVALUE, "States:", "",
{ {TW, 2, 0, "Code"}, {0, 15, 0, "State Name"}, }
};
DItem_ComboBoxRsc COMBOBOXID_EDITTABLE=
{
NOCMD, LCMD, NOSYNONYM, NOHELP, MHELP, HOOKID_ComboBoxes, NOARG,
12, "%.1lf", "%lf", "0.0", "100.0", NOMASK, 0, 6, 4, 0, 0,
COMBOATTR_AUTOADDNEWSTRINGS, "ComboBox 2:", "", { {0, 12, 0, ""}, }
};

Item Hook Function Messages

The following messages are sent to item hook functions that are attached to ComboBox items: DITEM_MESSAGE_CREATE, DITEM_MESSAGE_DESTROY, DITEM_MESSAGE_SYNCHRONIZE, DITEM_MESSAGE_BUTTON, DITEM_MESSAGE_KEYSTROKE, DITEM_MESSAGE_STATECHANGED, DITEM_MESSAGE_GETSTATE and DITEM_MESSAGE_SETSTATE.

ComboBox Item Functions

Funtion Description
mdlDialog_comboBoxGetInfo gets the attributes of a combo box.
mdlDialog_comboBoxSetInfo sets the attributes of a combo box.
mdlDialog_comboBoxGetTextP returns the RawItemHdr pointer of the attached text item.
mdlDialog_comboBoxGetListBoxP returns the RawItemHdr pointer of the attached popup list box.
mdlDialog_comboBoxGetStrListP returns a pointer to the string list that is currently connected to the combo box.
mdlDialog_comboBoxSetStrListP sets the string list that the combo box will manipulate.
mdlDialog_comboBoxSetPopupState may be used to programmatically open or close the popup list box.

The following functions are new in MicroStation V8:

Funtion Description
mdlDialog_comboBoxGetListModelP retrieves a pointer to the ListModel.
mdlDialog_comboBoxSetListModelP sets the ListModel pointer in the ComboBox. ListModels and StringLists are mutually exclusive.
mdlDialog_comboBoxGetIndex gets the index of the specified combo box dialog item.
mdlDialog_comboBoxSetIndex sets the index for the combo box dialog item.
mdlDialog_comboBoxSetSubEditor notifies the combo box item of its sub editor status.

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.