Text Pull-Down Menu

Text pull-down menus can contain items that display as text strings.

tools.jpg

These items can have attached submenus. These submenus are indicated with a right-pointing triangle on the left side of the menu item. Text pull-down menus are usually used to activate a command action. Most pull-down menus in MicroStation's Command window are text pull-downs.

Item Resource Specification

The text pull-down menu item is defined in a resource file with the following structure:

typedef struct ditem_pulldownmenuitemrsc
{
#if defined (resource)
char label[];
ULong accelerator;
byte enabled;
byte mark;
long subMenuType;
long submenuId;
ULong helpInfo;
char helpTaskId[];
long pulldownItemHookId;
long searchId; // used to search for item //
ULong commandNumber;
char commandTaskId[];
char unparsed[];
#else
long labelLength;
char label[1];
#endif
typedef struct ditem_pulldownmenursc
{
ULong helpInfo;
#if defined (resource)
char helpSource;
long pulldownHookId;
ULong attributes;
char menuTitle[];
DItem_PulldownMenuItemRsc pulldownItems[];
#else
long helpTaskLength;
char helpTaskId[1];
#endif
} DItem_PulldownMenuRsc;

The DItem_PulldownMenuRsc 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 text pull-down menu. This field will normally be ON | ALIGN_LEFT and is constructed by combining the constants from the following table with the logical OR operator:
menuTitle Contains the title of the menu. This field should be set to "" if the text pull-down menu is a submenu. (In this case, its title cannot display.)
Put a tilde `~' before the character in the title that will be the mnemonic. The mnemonic is the key the user presses to activate the menu item when navigating the menu bar with the keyboard.
pulldownItems Represents an array of DItem_PulldownMenuItemRsc. See the next table for a description of the DItem_PulldownMenuItemRsc structure.

The following table lists possible values for the attributes field (described above) and the meaning of those values:

attributes Value Meaning
ON The text pull-down menu will be initially enabled.
OFF All subitems in the text pull-down menu will be disabled (dimmed). The title of the menu will also be dimmed (if the pull-down menu is not a submenu).
ALIGN_LEFT Aligns the pull-down menu on the left side of the menu bar. This attribute is ignored for submenus.
ALIGN_RIGHT Aligns the pull-down menu on the right side of the menu bar. By convention, only a Help menu should be right-aligned. This attribute is ignored for submenus.

The DItem_MenuBarItemRsc structure has the following unique fields. (See "Common item resource fields" for a description of any field not in this table).

Field Description
label Specifies the text string that will display as the menu's item.
Put a tilde '~' before the character in the title that will be the mnemonic. The mnemonic is the key the user presses to activate the menu item when navigating the menu bar with the keyboard.
accelerator Specifies the virtual key code to use as the menu item's accelerator. If the dialog box in which this menu resides has the input focus, pressing the accelerator key will activate the menu item.
enabled Specifies whether the menu item is initially enabled. Usually this field should be ON (enabled).
mark Specifies the type of graphic mark to place on the left side of the menu item before the text string. This field can have one of the values listed in the mark table below.
subMenuType Specifies the type of the menu item's submenu. The choices are NOSUBMENU, PulldownMenu, PulldownOptionMenu and PulldownCPickerMenu.
subMenuId Specifies the resource ID of the menu item's submenu. If no submenu is needed, use 0 or NOSUBMENU.
pulldownItemHookId Specifies the ID of an item hook function.
searchId Specifies a user-definable number that should be unique in each menu. Many functions use this number to find a menu item. This number is more useful than specifying a menu item index when the contents of the menu have been dynamically changed.
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.

The following table lists possible values for the mark field (described above) and the meaning of those values:

mark Value Meaning
NOMARK No mark will display.
MARK_TOGGLE_OUT A raised toggle button will display.
MARK_TOGGLE_IN A recessed and filled toggle button will display.
MARK_RADIO_OUT A raised radio button will display.
MARK_RADIO_IN A recessed and filled radio button will display.
MARK_RIGHT_ARROW A right-pointing triangle will display.

The following is an example of a text pull-down menu resource. This item is the MicroStation Command window Element menu, and is defined in MicroStation's resource file.

{
NOHELP, MHELP, NOHOOK, ON | ALIGN_LEFT, "Element",
{
{"~Color", NOACCEL, ON, NOMARK, PulldownCPickerMenu,
PULLDOWNCPICKERMENUID_ElementColor, NOHELP,MHELP, NOHOOK,
{"~Style", NOACCEL, ON, NOMARK, PulldownOptionMenu,
{"~Weight", NOACCEL, ON, NOMARK, PulldownOptionMenu,
MENUSEARCHID_Element_Info, CMD_ANALYZE, MTASKID,""},
{"~Attributes", NOACCEL, ON, NOMARK, 0, NOSUBMENU,NOHELP,MHELP, NOHOOK,
MENUSEARCHID_Element_Attributes, CMD_DIALOG_ATTRIBUTES,
MTASKID,""},
{"~B-splines", NOACCEL, ON, NOMARK, 0, NOSUBMENU,NOHELP,MHELP, NOHOOK,
"Splines Element"},
{"~Dimensions", NOACCEL, ON, NOMARK, PulldownMenu,
MENUSEARCHID_Element_Dimensions, CMD_DIALOG_DIMPLACE,
MTASKID,""},
{"~Multi-lines", NOACCEL, ON, NOMARK, 0, NOSUBMENU, NOHELP, MHELP,
CMD_DIALOG_MULTILINE, MTASKID, ""},
MENUSEARCHID_Element_Text, CMD_DIALOG_TEXT, MTASKID,""},
}
};

Item hook function messages

The following messages are sent to item hook functions that are attached to text pull-down menus:

          DITEM_MESSAGE_DRAW 
          DITEM_MESSAGE_BUTTON 
          DITEM_MESSAGE_QUEUECOMMAND 

Text pull-down menu specific functions

Field Description
mdlDialog_textPDMItemGetInfo retrieves detailed information about a particular menu item in a text pull-down menu.
mdlDialog_textPDMItemSetInfo sets various aspects of a menu item in a text pull-down menu.
mdlDialog_textPDMItemInsert inserts a menu item into a text pull-down menu.
mdlDialog_textPDMItemIns inserts a menu item into a text pull-down menu.
mdlDialog_textPDMItemSetEnabled changes a text pull-down menu item's state (enabled or disabled).
mdlDialog_textPDMItemSetLabel sets a text pull-down menu item's text label (the item's displayed text string).
mdlDialog_textPDMItemSetMark sets a text pull-down menu item's mark.

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