Icon command items cannot be directly placed in a dialog box item list. They must be referenced by an icon command palette item or an icon command frame item.
Each DItem_IconCmdRsc structure has associated IconCmdSmallRsc and IconCmdLargeRsc instances. These resources contain the icon's actual raster bitmaps. These three resources are connected by making their resource IDs identical. For example, if an instance of DItem_IconCmdRsc has an ID of 5, the IDs of the corresponding IconCmdSmallRsc and IconCmdLargeRsc should also be 5.
For consistency with MicroStation's icon commands, small icons should be 23 pixels wide by 23 pixels high, and large icons should be 31 pixels wide by 31 pixels high.
Item resource specification
The icon command item is defined in a resource file with the following structure:
The DItem_IconCmdRsc structure has the following unique fields. (See "Common item resource fields" for a description of any field not in this table).
| Field | Description |
|---|---|
| attributes | Specifies the attributes of the icon command. This field will normally be 0 and is constructed by combining the constants from the attributes table (below) with the logical OR operator. |
| commandTaskId | Specifies the task that will execute the command associated with commandNumber. Setting comandTaskId to OTASKID, which is #defined to be an empty string, indicates that the task that owns (originally creates) the dialog should execute the command. Setting comandTaskId to MTASKID, which is #defined to be "+", indicates that MicroStation should be used to execute the command. (commandNumber must be a MicroStation command number defined in cmdlist.h.) If you need to specify a task different than the owner or MicroStation, put the task name here. |
| enabledAccessStr | Is currently unused and should be set to "". |
| iconItems | An array of DialogItemRsc and the list of popdown dialog items associated with the icon command. This list is created the same way that a normal dialog item list is created. See the "DialogBoxRsc Structure" and "DialogItemRsc Structure" sections in this chapter for more information on specifying dialog item lists. Only icon commands included in icon command palettes can have an item list. Icon command frames will not display popdown item lists. When used in an icon command item list specification, the extent member of DialogItemRsc specifies positions relative to the bottom left of the parent icon command palette, not the upper left corner of the dialog box containing the icon command. |
| attributes Value | Meaning |
|---|---|
| ICONCMDATTR_DONTSINGLESHOT | Indicates that this icon command can not be double clicked upon to enter single-shot operational mode. By default, double-clicking on an icon causes MicroStation to enter single-shot mode for the selected icon. |
| ICONCMDATTR_DONTAUTOSELECT | Indicates that this icon resource should not be highlighted (selected) when the command associated with the icon is queued to MicroStation. |
The following is an example of an icon command resource. This is the MicroStation icon command for the keyin PLACE LINE ANGLE and can be found in the Lines tool box. It is defined in MicroStation's resource file.
Item hook function messages
The icon command item cannot have an associated item hook function.
Icon cmd item functions
| Funtions | Description |
|---|---|
| mdlDialog_selectIconsById | changes the selection state of an icon by its resource ID. |
| mdlDialog_selectIconsByIdNoMsg | changes the selection state of an icon by its resource ID but does not display the command message inthe command window. |
| mdlDialog_selectIconsByCmd | changes the selection state of an icon by its command number. |
| mdlDialog_selectIconsByCmdNoMsg | changes the selection state of an icon by its command number but does not display the command message inthe command window. |
Palettes vs. tool boxes
The default MicroStation user interface uses tool boxes rather than icon command palettes. Still, palettes remain completely supported in MicroStation, but do not have the advanced features of tool boxes.
As in the Microsoft Office products, tool boxes are resizable and dockable. Additionally, tool boxes support tool tip and tool description help and allow items to be grouped. To support docking and to preserve screen space, tool boxes do not have pop-down fields. The Tool Settings dialog is used for this purpose.
Application developers are encouraged, but not required, to switch to tool boxes.
Tool Boxes
Notice that a tool box must be contained in a dialog box definition and that icon command resources can be shared between MDL applications using the "owner=" specification.
Tool boxes utilize the exact same icon command resources (DItem_IconCmdRsc) used by palettes. No icon rework is necessary. To add tool tip and tool description information, an extended attributes resource must be added.
For a frame to include a tool box, the extended frame resource(DItem_IconCmdFrameXRsc) must be used.Note that a tool box containing items other than icon command resources cannot be included in a frame.
Converting Icon Palettes to Tool Boxes
To illustrate a simple case of conversion from an icon command palette to a tool box, use the Lines-Sample icon command palette from the PALETTE MDL application. This command palette is delivered with MicroStation V5 MDL examples.
The first step in the conversion is creating a dialog box resource definition for the tool box. The dialog box resource contains one item, the tool box. Note that the dialog box and tool box resources have the same resource identifier. Since tool boxes are really just dialog boxes, you might want to differentiate dialog boxes from tool boxes in your application. This can be accomplished by numbering your dialog boxes and tool boxes with a different series of numbers. For example, start numbering dialog boxes with resource identifier 100 and tool boxes with resource identifier 200.
Next, define the tool box resource by populating the DItem_ToolBoxRsc structure.This structure is defined in dlogbox.h.The items contained in the tool box are declared in a manner similar to declaring items within a dialog box, that is, by populating the DialogItemRsc structure.
The auxiliary information field, (the last parameter) is NULL when reusing Bentley PowerDraft's icon commands, but contains the string: "owner=\"PALETTE"" for the icon commands that belong to other MDL applications. The string, in quotes, that follows the "owner=" string is the task identifier of the application that owns the icon command. Since our PALETTE application owns the icon commands in this tool box, we could have left the auxiliary information field blank. We chose to fill in the field with "owner="PALETTE"" to show how we might reuse an icon command that exists in some other MDL application. The only instance necessary to fill in this field is when an application, other than MicroStation or your MDL application, owns the icon command.
The item argument field of the DialogItemRsc structure can be thought as a group index.If all items in the dialog should be part of the same group, then assign the same value to all instances of the item argument field.If the items should be in different groups, then assign the same item argument value to all items within the group.The group index should be defined in the dialog item list structure in ascending order.
With the above tool box resource definition, we have the tool boxes shown below :
There are two major differences between an icon command palette and a tool box:
- Tool boxes can be resized, (shown above) and docked to the edges of the application window.
- All pop-down items that you may have associated with your icon command will always be displayed in the tool settings window in MicroStation PowerDraft.
Adding a tool box
Now that you have a handle on the tools necessary to build a tool box, let's look at the more complex case of incorporating a tool box into an icon command frame in place of an icon command palette. The declaration of the tool box to be added to the icon command frame is the same as the aforementioned declaration, but the tool box can only contain icon commands.
Convert your icon command palettes to tool boxes as demonstrated above. Then change your icon command frame resource to an extended icon command frame resource. Before modifying the PALETTE application, you should have the icon command frame with the resource definition below.
To add a tool box when modifying the icon command frame definition, the dialog box definition for the icon command frame will be basically the same-except that instead of including an IconCmdFrame in the dialog box definition, include an extended version of the IconCmdFrame resource, IconCmdFrameX.
The changes made to the icon command frame (in bold) allow us to add a tool box to this frame. Note, there are two additional parameters in the extended resource
- The attribute field, which is reserved for future use and should be zero.
- The owner task identifier, which is the MDL task identifier of the application that owns the icon command palette or icon command. When specifying ownership of the items on a frame, it is best to specify the task explicitly, rather than using OTASKID.
For this example above, we have only converted the first icon command palette that exists in this icon command frame.We have also changed the last icon command in the frame from ICONCMDID_SampleDeleteElement to ICONCMDID_DeleteElement to show that you can reuse one of MicroStation PowerDraft's icon commands (notice that the owner task identifier is a NULL string).
Incorporating tool tips and descriptions
While no changes to icon commands are required to make them part of the tool box, you can incorporate Tool Tips (balloon help) and Tool Descriptions (flyover help) into your icon commands. Balloon help is displayed in a yellow text box near a toolbox item when you place the pointer on top of the item, and the pointer is stationary for about 0.5 seconds. Flyover help is displayed in MicroStation PowerDraft's status area when the balloon help is displayed over an item or when the pointer passes over (flies over) the icon command.
Notice that we have extended the resource definition for the icon command to include the extendedAttributes information, rather than create a new resource type to include this information. The resource compiler and dialog manager have been enhanced to read and process this extended information for dialog items. By extending resource definitions, we can maintain backward compatibility with existing dialog items that you might include in a tool box, rather than creating an IconCmdX resource, for instance. If you add dialog items to your toolbox without adding the extended attribute information, then the items will display and operate properly, but you will not have the balloon and flyover help features enabled.
When creating the text strings for balloon and flyover help, follow these guidelines:
- For balloon help (or tool tip), use the command name if the string is not too long for the yellow box. We recommend that the string length should not exceed 30 to 40 characters. Capitalize the first letter of each word. The maximum string length for balloon help is 80 characters. flyover help (or tool description), use a one-liner that describes the command. Capitalize the first word in the sentence and do not end the sentence with a period. The maximum string length for flyover help is 80 characters.
- Balloon and flyover help are only supported for:
Icon commands that exist in icon command frames or tool boxes
Dialog items that exist in tool boxes - Use balloon help for a dialog item in a tool box to replace the item's label. You should not use a label for a dialog item that is placed in a tool box.
In the above example, the following definitions are declared in the header file, palettxt.h.
It really is easy to convert existing icon command palettes to tool boxes. And with this knowledge, you can quickly and easily blend your application into MicroStation PowerDraft or the next MicroStation upgrade.
Tool box summary
With the introduction of MicroStation PowerDraft, tool boxes effectively replace palettes. Tool boxes have many advantages over palettes. Tool boxes are:
- Resizable
- Dockable
- Consistent with MicroSoft Office products
Additionally, tool boxes:
- May contain items other than icon command items.
- Support fly-over help.
- Allow commands to be grouped.
Some special rules apply to tool boxes:
- A tool box must be contained in a dialog box resource definition.
- A tool box does not have slam-down fields, (all slam-downs display in the Tool Settings dialog).
- For a frame to include a tool box, the extended frame resource (DItem_IconCmdFrameXRsc) must be used.
- Tool boxes which contain items other than icon command resources cannot be included in a frame.
The format of the tool box resource is as follows, (from dlogbox.h):
Converting palettes to tool boxes
Conversion of palettes to tool boxes is straightforward. The tool box's resource definition contains a dialog item resource for each item in the tool box.
- To convert each existing palette to a tool box by following these steps
- Create a tool box definition, using the format in dlogbox.h.
- For each icon command resource in the existing palette, create a dialog item resource in the tool box item list.
- Create a dialog box definition and assign it the same resource id as the new tool box.
- List only the tool box item in the new dialog box's item list.
The icon command resources do not require modification.
Although palettes will continue to be supported, their appearance will only confuse our customers. Users would be frustrated to not be able to dock and resize palettes.
Icon Command Resources
CmdItemListRsc. Since it is command based, (command numbers are used as the IDs) CmdItemListRsc's let MicroStation find the tool settings for the current command no matter how the command was called. MicroStation now looks for a CmdItemListRsc associated with the current command before checking for an item list in an IconCmdRsc resource.
This enhancement does not change the resource definition of IconCmdRsc's. However, is recommended to remove the item list from the IconCmdRsc when you have added a CmdItemListRsc. CmdItemListRsc's have been added and tool settings removed from IconCmdRsc's for all MicroStation and MicroStation MDL application commands.
Adding CmdItemListRsc's is an easy task, since it's item list is of the same form as the item list in the IconCmdRsc. See the example below which was taken from V551NEW.R from the delivered MDL example called V551NEW.
The only restriction is that the command and it's associated CmdItemListRsc must be in the same application.