Tool Palettes

Tool palettes contain icons that, when activated, add a command to MicroStation's input queue. There are two types of MicroStation's tool palettes: icon command frames and icon command palettes.

Icon command palettes can contain only icon commands. These icon commands can have associated items. These items will display when the icon is selected and are the icon's popdown items. (See the MicroStation User's Guide for an explanation of these items).

Icon command frames can contain icon commands or icon command palettes. The icon commands that are directly in a command frame cannot have associated item lists. Each icon command palette in a command frame has a current icon, the icon command from the palette that is displayed in the parent icon command frame. When the data button is pressed while the cursor is over a icon command palette in a command frame, the full palette is popped up. The user can then select an icon command from the palette, or tear off the palette. (To tear off a palette, drag the cursor off from the palette until an outline of the palette displays. The palette can then be placed anywhere on the screen).

Icon command frame

An icon command frame should be the only item in a dialog box. Icon command frames should usually be vertically oriented (which means that they have more rows than columns).

Item list specification

The DialogItemRsc field extent is unused for icon command frame items. The dialog box that contains an icon command frames is resized so the command frame fills the dialog box. The extent should be set to {0, 0, 0, 0}.

The type field should be IconCmdFrame.

The ID determines the DItem_IconCmdFrameRsc instance to load.

The attributes are ignored for icon command frame items. The icon command frame is always enabled and displayed.

The itemArg field is unused and should usually be set to 0.

The label field is unused and should be set to "".

The auxInfo field is unused and should be set to "".

The following is an example of a icon command frame item list specification:

{{0, 0, 0, 0}, IconCmdFrame, ICONCMDFRAMEID_Main, ON, 0, "", ""}

Item resource specification

The icon command frame item is defined in a resource file with the following structure:

typedef struct ditem_iconcmdframersc 
{ 
        int nColumns; 
        int nRows; 
        ULong helpInfo; 
        ULong helpSource; 
#if defined (resource) 
        char label[]; 
        DialogItemSpec iconPieces[]; 
#else 
        long labelLength; 
        char label[1]; 
#endif 
} DItem_IconCmdFrameRsc; 

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

Field	Description
nColumns	Specifies the number of columns in the icon command frame.
nRows	Specifies the number of rows in the icon command frame.
label	Specifies the title of the icon command frame. The dialog box title will be set to this string's value.
iconPieces	Specifies the contents of the icon command frame. iconPieces is an array of DialogItemSpec members. The type field of an iconPieces member can be either IconCmd or IconCmdPalette. The id field of an iconPieces member indicates the DItem_IconCmdRsc or DItem_IconCmdPaletteRsc instance to load.

The following is an example of a icon command frame item resource. This item is the MicroStation Main tool box, and is defined in MicroStation's resource file.

DItem_IconCmdFrameRsc ICONCMDFRAMEID_Main=
{
                2, 10, NOHELP, MHELP, "Main",
                {
                                {IconCmd, ICONCMDID_ChooseElement},
                                {IconCmdPalette, ICONCMDPALETTEID_Line},
                                {IconCmdPalette, ICONCMDPALETTEID_Arc},
                                {IconCmdPalette, ICONCMDPALETTEID_LineString},
                                {IconCmd, ICONCMDID_PlaceOpenBSpline},
                                {IconCmdPalette, ICONCMDPALETTEID_Polygon},
                                {IconCmdPalette, ICONCMDPALETTEID_Fillet},
                                {IconCmdPalette, ICONCMDPALETTEID_Circle},
                                {IconCmdPalette, ICONCMDPALETTEID_Point},
                                {IconCmdPalette, ICONCMDPALETTEID_Cell},
                                {IconCmdPalette, ICONCMDPALETTEID_EnterData},
                                {IconCmdPalette, ICONCMDPALETTEID_Text},
                                {IconCmdPalette, ICONCMDPALETTEID_MirrorElement},
                                {IconCmdPalette, ICONCMDPALETTEID_CopyElement},
                                {IconCmdPalette, ICONCMDPALETTEID_Change},
                                {IconCmdPalette, ICONCMDPALETTEID_Modify},
                                {IconCmdPalette, ICONCMDPALETTEID_Chain},
                                {IconCmdPalette, ICONCMDPALETTEID_Drop},
                                {IconCmdPalette, ICONCMDPALETTEID_View},
                                {IconCmd, ICONCMDID_DeleteElement},
                }
};

Item hook function messages

The icon command frame item cannot have an associated item hook function.

Icon Command Frame Item Functions

Field	Description
mdlDialog_icFrameGetItemInfo	retrieves detailed information about an item in an icon command frame.
mdlDialog_icFrameSetItemInfo	sets various aspects of an item in an icon command frame.
mdlDialog_icFrameGetNItems	returns the number of items in an icon command frame.
mdlDialog_icFrameGetNSubItems	returns the number of subitems in an icon command frame palette item.
mdlDialog_icFrameSelectIcon	selects (highlights) an icon in an icon command frame/palette.

Icon command pallette

Icon command palettes are different from other items in that no dialog box is associated with them when their resources are defined. In fact, they cannot be placed directly inside a dialog box by including them in dialog item list specification. Instead only an icon command palette resource is created in a resource file. The special function mdlDialog_openPalette is then used to display the palette. At that point, the dialog box is automatically created on-the-fly to contain the specified icon command palette.

Icon command palettes should usually be horizontally oriented. (They should have more columns than rows.) Horizontally oriented palettes simplify laying out popdown items in the palette's icon commands.

Item resource specification

The icon command palette item is defined in a resource file with the following structure:

                        typedef struct ditem_iconcmdpalettersc
                        { 
                        int nColumns;
                        int nRows; 
                        int defaultItem; 
                        ULong helpInfo; 
                        ULong helpSource; 
                        long itemHookId; 
                        long itemHookArg; 
                        #if defined (resource) 

                        char label[]; 
                        int iconCmds[]; 
#else 
                        long labelLength; 
                        char label[1]; 
#endif 
} DItem_IconCmdPaletteRsc; 

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

Field	Description
nColumns	Specifies the number of columns in the icon command palette.
nRows	Specifies the number of rows in the icon command palette.
defaultItem	Specifies the index of the icon command to display when the icon command palette is contained in an icon command frame.
label	Specifies the title of the icon command palette. When the icon palette displays in its dialog box, this string sets the dialog box's title.
iconCmds	Specifies the contents of the icon command palette. iconCmds is an array of DItem_IconCmdRsc resource ids. This array determines the DItem_IconCmdRsc instances to load. The number of entries in the iconCmds array can be less than nRows * nColumns, in which case the empty slots in the palette are left blank when the palette is displayed.

The following is an example of an icon command palette item resource. This item is the MicroStation Lines tool box, and is defined in MicroStation's resource file.

DItem_IconCmdPaletteRsc ICONCMDPALETTEID_Line= 
{ 
        8, 2, 0, NOHELP, MHELP, NOHOOK, NOARG, "Lines", 
        { 
                ICONCMDID_PlaceLine, 
                ICONCMDID_PlaceLineAA, 
                ICONCMDID_ConstBisectorLine, 
                ICONCMDID_ConstBisectorAngle, 
                ICONCMDID_PlaceTerminator, 
                ICONCMDID_ConstLineMin, 
                ICONCMDID_ConstTanPerp, 
                ICONCMDID_ConstTanBetween, 
                ICONCMDID_ConstLineAAToPt, 
                ICONCMDID_ConstLineAAFromPt, 
                ICONCMDID_ConstLineAAToPtK, 
                ICONCMDID_ConstLineAAFromPtK, 
                ICONCMDID_ConstPerpToElem, 
                ICONCMDID_ConstPerpFromElem, 
                ICONCMDID_ConstTanToElem, 
                ICONCMDID_ConstTanFromElem, 
        } 
}; 

Item hook function messages

No messages are sent to the item hook function.

f Icon cmd palette item functions

Field	Description
mdlDialog_icPaletteGetItemInfo	retrieves detailed information about a item in an icon command palette.
mdlDialog_icPaletteSetItemInfo	sets various aspects of an item in an icon command palette.
mdlDialog_icPaletteGetNItems	returns the number of items in an icon command palette.
mdlDialog_icPaletteSelectIcon	selects (highlights) an icon in an icon command palette.