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.

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 
} DItem_ComboBoxRsc;
#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.