Button Group Items

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.

ss29.jpg

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:

{{XC, YC, 0, 0}, ButtonGroup, BGROUPID_SnapButtonWide, ON, 0, "", ""}

Item resource specification

The button group item is defined in a resource file with the following structure:

typedef struct ditem_buttongroupitemrsc
{
ULong iconType;
long iconId;
ULong commandNumber;
ULong commandSource;
ULong value;
ULong mask;
ULong arrayIndex;
ULong attributes;
#if defined (resource)
char label[];
#else
long labelLength;
char label[1];
#endif
typedef struct ditem_buttongrouprsc
{
long synonymsId;
ULong helpInfo;
ULong helpSource;
long itemHookId;
long itemHookArg;
ULong attributes;
long nColumns;
long nRows;
long itemWidth;
long itemHeight;
long selectedFgColorIndex; // only if lgrey highlight,
-1 = use icon's
#if defined (resource)
char label[];
char accessStr[];
DItem_ButtonGroupItemRsc buttonGroupItems[];
#else
long labelLength;
char label[1];
#endif
} DItem_ButtonGroupRsc;

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.

DItem_ButtonGroupRsc BGROUPID_SnapButtonTwoRow=
{
SYNONYMID_SnapButtonGroup, NOHELP, MHELP,
0, 8, 2, 0, 0, WHITE_INDEX, "", "tcb->snapOverride",
{
{Icon, ICONID_NearSnapPoint, NOCMD, MCMD, 0, NOMASK, 0, 0, ""},
{Icon, ICONID_KeyPointSnap, NOCMD, MCMD, 1, NOMASK, 0, 0, ""},
{Icon, ICONID_MidPointSnap, NOCMD, MCMD, 2, NOMASK, 0, 0, ""},
{Icon, ICONID_CenterSnapCircle, NOCMD, MCMD, 3, NOMASK, 0, 0, ""},
{Icon, ICONID_OriginSnap, NOCMD, MCMD, 4, NOMASK, 0, 0, ""},
{Icon, ICONID_BisectorSnap, NOCMD, MCMD, 5, NOMASK, 0, 0, ""},
{Icon, ICONID_IntersectSnap, NOCMD, MCMD, 6, NOMASK, 0, 0, ""},
{Icon, ICONID_TangentSnap, NOCMD, MCMD, 7, NOMASK, 0, 0, ""},
{Icon, ICONID_TangentPointSnap, NOCMD, MCMD, 8, NOMASK, 0, 0, ""},
{Icon, ICONID_PerpendicularSnap, NOCMD, MCMD, 9, NOMASK, 0, 0, ""},
{Icon, ICONID_ParallelSnap, NOCMD, MCMD, 11,NOMASK, 0, 0, ""},
{Icon, ICONID_ThruPointSnap, NOCMD, MCMD, 12,NOMASK, 0, 0, ""},
{Icon, ICONID_PointOnSnap, NOCMD, MCMD, 13,NOMASK, 0, 0, ""},
{Icon, ICONID_ResizeBoxToTall, NOCMD, MCMD, 14,NOMASK, 0, 0, ""},
}
};

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 

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