Radio Button Item

The radio button item shows the state of an application variable that can be any one of a selection of values. The currently selected value is identified by the 3D diamond displayed next to each value label. This item is actually comprised of two different resources: The radio button resource itself which describes one of the possible values an option can assume and the radio button list resource which defines all the radio button values which comprise the group. The collection of these two resources is called a radio button group and is operationally similar to the option button item and visually similar to the toggle button item.

v8radiobutton.jpg

When the user selects one of the options available for a radio button group, that option is highlighted and the previously highlighted option is un-highlighted. That is, radio buttons operate the same as an option button in that only one option can be selected at any one time, but are visually similar to toggle buttons in that they are all displayed to the user at all times are are displayed as toggle fields.

Item list specification

The DialogItemRsc field extent specifies the location of the radio button item. The x position specifies the location of the left side of the radio button's 3D diamond, not the start of the radio button's text label. The y position specifies both the top of the 3D diamond and the top of the text label. If the width is 0, the width of the label is used. If the height is 0, the height of the current dialog font is used.

The type field should contain RadioButton.

The ID determines the DItem_RadioButtonRsc 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 overrides the label contained in the DItem_RadioButtonRsc instance.

The auxInfo field currently overrides only the access string contained in the DItem_RadioButtonRsc instance.

The following is an example of a radio button item list specification:

{{XC, YC, 0, 0}, RadioButton, RBUTTONID_Option4, ON, 0, "", ""}

Item resource specification

The list of radio button item instances is defined in a resource file along with the actual radio button item resources themselves. The list of radio button resources which comprise the radio button group is defined by the following structure:

typedef struct idlistrsc
{
#if defined (resource)
long ids[];
#else
long nIds;
long idList[1];
#endif

This structure defines the list of DItem_RadioButtonRsc resource IDs which comprise the content of the radio button group. The DItem_RadioButtonRsc structure describes a component of a radio button group and is defined by the following structure:

typedef struct ditem_radiobuttonrsc
{
ULong commandNumber;
ULong commandSource;
long synonymsId;
ULong helpInfo;
ULong helpSource;
long itemHookId;
long itemHookArg;
ULong value;
ULong mask;
long radioButtonListId; // must specify, id of list of other rb's in group
#if defined (resource)
char label[];
char accessStr[];
#else
long labelLength;
char label[1];
#endif
} DItem_RadioButtonRsc;

The DItem_RadioButtonRsc structure has the following unique fields.See CommonItemResourceFields.

Field Description
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.
mask Is used with value to determine the currently selected subitem. If the entire variable specified by accessStr is being compared to value, set this field to NOMASK (which is defined to be 0xFFFFFFFF).
radioButtonListId Defines the resource ID of the DItem_RadioButtonListRsc which to which this radio button resource definition belongs. This defines the grouping to be used for this radio button value definition.

For example, suppose bits 2 and 3 of the variableflags 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:

The following is an example of a radio button item resource. This item is used in the Color Palette dialog box, and is defined in MicroStation's resource file.

DItem_RadioButtonListRsc RADIOBUTTONLISTID_ColorInterp_Terminal=
{
{
}
};
{
TXT1_ColorInterpRadioButtonStart, "msDialogState.interpColor"
};
{
TXT1_ColorInterpRadioButtonEnd, "msDialogState.interpColor"
};

Item hook function messages

The following messages are sent to item hook functions that are attached to radio 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

Radio button item functions

There are no radio button item functions.


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