The button group item creates items whose appearance is similar to that of icon command palettes and icon commmand frames but which can be contained in a standard dialog box and operate in the same manner as option or radio buttons.
Button group items define a palette of icons which are displayed in a dialog box. The operation and display of the icons within the palette is defined by the item hook function and the attributes assigned to the item in the resource definition. To the user, a button group actually behaves like an iconic option button which is expanded out and allows radio button selection.
Item list specification
The DialogItemRsc field extent specifies the location of the button group item. The width and height of the item is defined by the iconWidth and iconHeight fields in the button group item resource definition The extent.width and extent.height fields are ignored and should be set 0.
The type field should be ButtonGroup.
The ID determines the DItem_ButtonGroupRsc 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_ButtonGroupRsc instance.
The auxInfo field can override the access string contained in the DItem_ButtonGroupRsc instance.
The following is an example of a button group item list specification:
Item resource specification
The button group item is defined in a resource file with the following structure:
The DItem_ButtonGroupRsc structure has the following unique fields.See CommonItemResourceFields for a description of any field not in this table.
| Field | Description |
|---|---|
| attributes | Specifies attributes which affect the button group item as a whole. It is constructed by combining the constants listed below with the logical OR operator: - BGGROUPATTR_NODRAWBORDER - BGGROUPATTR_HIGHLIGHTINVERT - BGGROUPATTR_MULTISELECTION - BGGROUPATTR_SPRINGLOADED |
| nColumns | Specifies the number of columns in the button group. |
| nRows | Specifies the number of rows in the button group. |
| itemWidth | Specifies the width of the icons contained in the button group in dialog coordinates. A negative value indicates the width is in pixels and a value of 0 indicates that the maximum icon width for the icons in the button group should define the item width. This field is usually 0. |
| itemHeight | Specifies the height of the icons contained in the button group in dialog coordinate units. A negative value indicates the height is in pixels and a value of 0 indicates that the maximum icon height for the icons in the button group should define the item height. This field is usually 0. |
| selectedFgColorIndex | Specifies a color index to be used as the foreground color in displaying the icon when it has been selected by the user. If this value is -1, then the icon's foreground color is used. This field is not used when the BGROUPATTR_HIGHLIGHTINVERT attribute is set. |
| buttonGroupItems | Specifies the contents of the button group item. buttonGroupItems is an array of DItem_ButtonGroupItemRscs that is the button group's subitem list. This structure has many of the same fields as the DItem_OptionButtonItemRsc structure. |
The DItem_OptionButtonItemRsc structure has the following unique fields. See CommonItemResourceFields for a description of any field not in this table.
| Field | Description |
|---|---|
| iconType | Indicates the type of icon the subitem is using. NOTYPE is not supported for this field. |
| iconId | Specifies the ID of the icon instance to load and display as the subitem. NOICON is not supported for this field. |
| value | Is used with mask to determine the currently selected subitem. Only one subitem can be selected at once. mask indicates the relevant bits of the variable specified by accessStr. These bits, shifted so the rightmost bit of the mask becomes bit 0, are compared to value. If the mask is 0x0E (1110 binary) then the masked value will be shifted right 1 bit before being compared to value. The subitem whose shifted masked bits matches value becomes the currently selected subitem. (See the "Value - Mask example" below.) |
| mask | Is used with value to determine the currently selected subitem. (See the "Value - Mask example" below.) If the entire variable specified by accessStr is being compared to value, set this field to NOMASK (which is defined to be 0xFFFFFFFF). |
| enabled | Determines the state (enabled or disabled) of the subitem when the button group is first created. If this field is set to ON, the subitem can be selected; when it is set to OFF, the subitem will be dim and cannot be selected. |
| arrayIndex | Not currently supported. |
| attributes | Specifies subitem specific attribute characteristics. It is constructed by combining the constants from the following table with the logical OR operator: |
Value - Mask example
For example, suppose bits 2 and 3 of the variable flags will be tested. mask will then be 0xC (1100 binary). If bit 2 is on, the first subitem should be selected. If bit 3 is on, the second subitem should be selected. If both bits are on, the third subitem is selected. value and mask should be set to the following for each subitem:
| subitem | value | mask | flags value that will select subitem |
|---|---|---|---|
| 0 | 1 | 0xC | 4 (= 1 << 2) |
| 1 | 2 | 0xC | 8 (= 2 << 2) |
| 2 | 3 | 0xC | 12 (= 3 << 2) |
| attributes Value | Meaning |
|---|---|
| BGROUPITEMATTR_DISABLED | Specifies that the icon is disabled and is not selectable by the user. |
| BGROUPITEMATTR_GREYED | Specifies that when the icon is drawn, it should be drawn using the icon style ICON_STYLE_DGREY (See the mdlWindow_iconDraw function in the MicroStation MDL Function Reference Manual for more information on icon drawing styles). |
The following is an example of a button group item resource. This item is used in the Snap Mode button bar, and is defined in MicroStation's resource file.
Item hook function messages
The following messages are sent to item hook functions that are attached to button group items:
DITEM_MESSAGE_CREATE DITEM_MESSAGE_INIT DITEM_MESSAGE_DESTROY DITEM_MESSAGE_GETSTATE DITEM_MESSAGE_SETSTATE DITEM_MESSAGE_SYNCHRONIZE DITEM_MESSAGE_STATECHANGED DITEM_MESSAGE_QUEUECOMMAND