Option Button Item

The option button item lets the user select one choice from a mutually exclusive set of choices. It has an optional label right-justified next to a beveled rectangle that shows the currently selected choice. When the user presses the mouse button while the cursor is in the currently selected choice, the full list of choices displays. The user drags over the various option menu choices and releases the mouse button on the new selection. If the mouse button is released outside of the popped-up menu, the current selection is unchanged. The option choices can be text strings or icons

origin.jpg

Item list specification

The DialogItemRsc field extent specifies the location of the beveled rectangle that displays the option button's current choice. Any label associated with the option button will be right-justified next to the left edge of this beveled rectangle. If the option button is using text subitems and the width is 0, the width of the longest text subitem label will be used. If several option buttons are vertically aligned, a non-zero width should be specified to ensure that these option buttons have the same width. If height is 0, as it normally should be, the height of the current dialog font will be used.

If the option button uses iconic subitems, the default width and height are the width and height of the first subitem. With iconic subitems, a width sometimes needs to be specified in pixels, not dialog coordinate units. To specify pixels, use a negative number.

The type field should be OptionButton.

The ID determines the DItem_OptionButtonRsc 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_OptionButtonRsc instance.

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

The following is an example of an option button item list specification:

ON, 0, "", ""}

Item resource specification

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

typedef struct ditem_optionbuttonitemrsc
{
ULong iconType;
long iconId;
ULong commandNumber;
ULong commandSource;
ULong value;
ULong mask;
byte enabled;
#if defined (resource)
char label[];
#else
long labelLength;
char label[1];
#endif
typedef struct ditem_optionbuttonrsc
{
long synonymsId;
ULong helpInfo;
ULong helpSource;
long itemHookId;
long itemHookArg;
#if defined (resource)
char label[];
char accessStr[];
DItem_OptionButtonItemRsc optionButtonItems[];
#else
long labelLength;
char label[1];
#endif
} DItem_OptionButtonRsc;

The itemHookArg field of the DItem_OptionButtonRsc structure controls how the option button is displayed and initialized as described below:

Value Meaning
OPTNBTNATTR_NEWSTYLE Display the Motif option button bump on the right end of the option button display rectangle. All option buttons should specify this attribute in order to display this bump which allows the user to distinguish more readily between an option button and a push button.
OPTNBTNATTR_DONTADDBUMPWIDTH This attribute indicates to the item handler that the bump width should not be added to the width defined in the option button extent data when creating the option button item. By default, the item handler assumes that the extent information only includes enough space to display the option button selection text and that it must add additional space to display the bump without overwriting the text. If this attribute is used, the item handler assumes the width specifies enough space for both the text and the bump.

The only unique field in the DItem_OptionButtonRsc structure is the array of DItem_OptionButtonItemRscs that is the option button's subitem list. For consistency with MicroStation's dialog boxes, an option button's label should always end with a colon.

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

Field Description
iconType Indicates the type of icon the subitem is using. This field should usually be Icon if you are using IconRscs. If not using icons, specify NOTYPE.
iconId Specifies the ID of the icon instance to load and display as the subitem. If you are not using icons, specify NOICON.
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), the masked value will be shifted right 1 bit before being compared to value. The subitem whose shifted masked bits match 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 option button 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.
label Specifies the subitem's text string if NOTYPE and NOICON are specified for iconType and iconId.

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)

The following is an example of an option button item resource. This item is used in the Element Attributes dialog box, and is defined in MicroStation's resource file.

{
"Class:", "tcb->props",
{
{NOTYPE, NOICON, CMD_ACTIVE_LEVEL, MCMD, 0, 0x000F, ON,
"Primary"},
{NOTYPE, NOICON, CMD_ACTIVE_LEVEL, MCMD, 2, 0x000F, ON,
"Construction"}
}
};

Item hook function messages

The following messages are sent to item hook functions that are attached to option button items:

      DITEM_MESSAGE_CREATE
      DITEM_MESSAGE_INIT
      DITEM_MESSAGE_DESTROY
      DITEM_MESSAGE_BUTTON
      DITEM_MESSAGE_SYNCHRONIZE
      DITEM_MESSAGE_GETSTATE
      DITEM_MESSAGE_SETSTATE
      DITEM_MESSAGE_STATECHANGED
      DITEM_MESSAGE_QUEUECOMMAND

Option button item functions

Funtion Description
mdlDialog_optionButtonGetNItems returns the number of subitems in an option button.
mdlDialog_optionButtonGetItemInfo retrieves detailed information about a subitem of an option button.
mdlDialog_optionButtonSetItemInfo sets various aspects of a subitem of an option button.
mdlDialog_optionButtonDeleteItem deletes a subitem from an option button.
mdlDialog_optionButtonDeleteAll deletes all subitems from an option button.
mdlDialog_optionButtonInsertItem inserts a subitem into an option button.
mdlDialog_optionButtonSetEnabled sets the state (enabled or disabled) of an option button's subitem.

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