Toggle Button Item

The toggle button item (also known as a check button or a check box) shows the state of an application variable that is either on or off.

Item list specification

The DialogItemRsc field extent specifies the location of the toggle button. The x position specifies the location of the left side of the toggle button's 3D square, not the start of the toggle button's text label. The y position specifies both the top of the 3D square 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 ToggleButton.

The ID determines the DItem_ToggleButtonRsc 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_ToggleButtonRsc instance.

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

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

{{XC, YC, 0, 0}, ToggleButton, TOGGLEID_LockGrid, ON, 0, "", ""} 

Item resource specification

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

typedef struct ditem_togglebuttonrsc 
{ 
        ULong commandNumber; 
        ULong commandSource; 
        long synonymsId; 
        ULong helpInfo; 
        ULong helpSource; 
        long itemHookId; 
        long itemHookArg; 
        ULong mask; 
        char invertFlag; 
#if defined (resource) 
        char label[]; 
        char accessStr[]; 
#else 
        long labelLength; 
        char label[1]; 
#endif 
} DItem_ToggleButtonRsc; 

The DItem_ToggleButtonRsc structure has the following unique fields. (See CommonItemResourceFields for a description of any field not in this table).

Field	Description
mask	If invertFlag is FALSE, when the toggle button is ON (depressed and checked) the bitwise OR operator combines mask with the variable specified by accessStr. When the toggle button is OFF (raised \ and unchecked) the bitwise AND operator combines the 1's complement of mask with the variable specified by accessStr. If invertFlag is TRUE, when the toggle button is OFF (raised and un-checked) the bitwise OR operator combines mask with the variable specified by accessStr. When the toggle button is ON (depressed and checked) the bitwise AND operator combines the 1's complement of mask with the variable specified by accessStr.
invertFlag	See the description for mask.

The following is an example of a toggle button item resource. This item is used in the Locks and Toggles dialog boxes, and is defined in MicroStation's resource file.

DItem_ToggleButtonRsc TOGGLEID_LockGrid= 
{ 
        CMD_LOCK, MCMD, NOSYNONYM, NOHELP, MHELP, NOHOOK, NOARG, 0x1, 
        NOINVERT, "Grid Lock", "tcb->control.grid_lock" 
}; 

Item hook function messages

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

Toggle button item functions

Field	Description
mdlDialog_toggleButtonGetInfo	retrieves detailed information about a toggle button.
mdlDialog_toggleButtonSetInfo	sets various aspects of a toggle button.