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
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:
The option button item is defined in a resource file with the following structure:
The itemHookArg field of the DItem_OptionButtonRsc structure controls how the option button is displayed and initialized as described below:
|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.)
|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.
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
|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.|