Text Pull-Down Menu

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

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 
} DItem_PulldownMenuItemRsc;
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.

DItem_PulldownMenuRsc PULLDOWNMENUID_Element=
{
        NOHELP, MHELP, NOHOOK, ON | ALIGN_LEFT, "Element",
{
{"~Color",                              NOACCEL, ON, NOMARK, PulldownCPickerMenu,
                                        PULLDOWNCPICKERMENUID_ElementColor, NOHELP,MHELP, NOHOOK,
                                        MENUSEARCHID_Element_Color, NOCMD, MTASKID,""},
{"~Style",                              NOACCEL, ON, NOMARK, PulldownOptionMenu,
                                        PULLDOWNOPTIONMENUID_ElementStyle, NOHELP,MHELP, NOHOOK,
                                        MENUSEARCHID_Element_Style, NOCMD, MTASKID,""},
{"~Weight",                             NOACCEL, ON, NOMARK, PulldownOptionMenu,
                                        PULLDOWNOPTIONMENUID_ElementWeight, NOHELP,MHELP, NOHOOK,
                                        MENUSEARCHID_Element_Weight, NOCMD, MTASKID,""},
{"~Info",                               NOACCEL, ON, NOMARK, 0, NOSUBMENU, NOHELP,MHELP, NOHOOK,
                                        MENUSEARCHID_Element_Info, CMD_ANALYZE, MTASKID,""},
{"-",                           NOACCEL, OFF,NOMARK,0,NOSUBMENU,NOHELP,MHELP,
                                        NOHOOK, NOARG, NOCMD, MTASKID,""},
{"~Attributes",                 NOACCEL, ON, NOMARK, 0, NOSUBMENU,NOHELP,MHELP, NOHOOK,
                                        MENUSEARCHID_Element_Attributes, CMD_DIALOG_ATTRIBUTES,
                                        MTASKID,""},
{"-",                           NOACCEL, OFF,NOMARK,0,NOSUBMENU,NOHELP,MHELP, NOHOOK,
                                        NOARG,NOCMD, MTASKID,""},
{"~B-splines",                  NOACCEL, ON, NOMARK, 0, NOSUBMENU,NOHELP,MHELP, NOHOOK,
                                        MENUSEARCHID_Element_BSplines, CMD_MDL_LOAD, MTASKID,
                                        "Splines Element"},
{"~Dimensions",                 NOACCEL, ON, NOMARK, PulldownMenu,
                                        PULLDOWNMENUID_SubDimension, NOHELP, MHELP, NOHOOK,
                                        MENUSEARCHID_Element_Dimensions, CMD_DIALOG_DIMPLACE,
                                        MTASKID,""},
{"~Multi-lines",        NOACCEL, ON, NOMARK, 0, NOSUBMENU, NOHELP, MHELP,
                                        NOHOOK, MENUSEARCHID_Element_MultiLines,
                                        CMD_DIALOG_MULTILINE, MTASKID, ""},
{"~Text",                               NOACCEL, ON, NOMARK, 0, NOSUBMENU,NOHELP,MHELP, NOHOOK,
                                        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.