This section describes menus and explains how to use them.
A menu is a list of items that specify options or groups of options (a submenu) for an application. Clicking a menu item opens a submenu or causes the application to carry out a command.
Menu bar and menus
A menu is arranged in a hierarchy. At the top level of the hierarchy is the menu bar which contains a list of menus. A menu item can either carry out a command or open a submenu. A menu opened from the menu bar drops down from the menu bar and is sometimes called a drop-down menu. When a drop-down menu is displayed, it is attached to the menu bar.
A menu item on the menu bar that opens a drop-down menu is also called a menu name.
The menu names on a menu bar represent the main categories of commands that an application provides. Selecting a menu name from the menu bar typically opens a menu whose menu items correspond to the commands in a category. For example, a menu bar might contain a File menu name that, when clicked by the user, activates a menu with menu items such as New, Open, and Save.
Popup menus
The system also provides popup menus. A popup menu is not attached to the menu bar; it can appear anywhere on the screen. An application typically associates a popup menu with a portion of a window, such as the client area, or with a specific object, such as an icon. For this reason, these menus are also called context menus. A shortcut menu remains hidden until the user activates it, typically by right-clicking a selection, a toolbar, or a taskbar button. SmallPlugin allows you to have as many popup menus as you need. To set popup menu as the right-click menu use the SetContextMenuHandle command.
Command items and items that open submenus
When the user chooses a command item, plugin calls object labeled as menu_event_handler from the Master Top Layer. When the user points to an item that have a small arrow to the right of the text of a menu item, the system opens the submenu. A submenu typically contains command items, but it can also contain items that open nested submenus. By adding such items to submenus, you can nest menus to any depth.
Menu item identifiers and menu handles
Associated with each menu item is a unique integer called a menu item identifier. When user chooses a command item from a menu, plugin calls object labeled as menu_event_handler from the Master Top Layer and puts menu item identifier to the output variable. So the first line of the menu_event_handler script must be:
You can examine the identifier in If...Then statement to determine the menu item that was chosen by user, and processes it accordingly.
Menu items that open submenus or drop-down menus have identifiers just as command items do. These identifiers usually called menu handles, because they point to the menu. In other words, each menu (including popup menus) have its own unique handle which is used to address menu before modifying it. However, plugin does not call menu event handler script when the item that points to the submenu is selected from the menu. Instead, it opens the submenu associated with the menu item.
Menu item position
In addition to having a unique identifier, each menu item in a menu bar or menu has a unique position value. The leftmost item in a menu bar, or the top item in a menu, has position zero. The position value is incremented for subsequent menu items. The system assigns a position value to all items in a menu, including separators. When calling CreateMenuItem command, you can specify the item position.
Enabled and disabled menu items
A menu item can be enabled or disabled. By default, a menu item is enabled. When the user chooses an enabled menu item, plugin calls event handler or displays the corresponding submenu, depending on what kind of menu item it is.
When menu items are not available to the user, they should be disabled. Disabled menu items cannot be chosen. An application grays an unavailable menu item to provide a visual cue to the user that a command is not available. You can use a disabled item when an action is not appropriate. To enable or disable menu item use SetMenuItemEnabled command.
Checked and clear menu items
A menu item can be either checked or clear. The system displays a bitmap next to selected menu items to indicate their selected state. Only menu items that do not open submenu can have checkmarks.
Applications typically check or clear a menu item to indicate whether an option is in effect. For example, suppose an application has a toolbar that the user can show or hide by using a Toolbar command on a menu. When the toolbar is hidden, the Toolbar menu item is clear. When the user chooses the command, the application checks the menu item and shows the toolbar.
You can set or clear a menu item's check mark attribute by using the SetMenuItemChecked command. Sometimes, a group of menu items corresponds to a set of mutually exclusive options. In this case, you can indicate the selected option by using a selected radio menu item (analogous to a radio button control). Selected radio items are displayed with a bullet bitmap instead of a check mark bitmap.
Menu item separators
The system provides a special type of menu item, called a separator, that appears as a horizontal line. You can use a separator to divide a menu into groups of related items. The user cannot select a separator. See CreateMenuItem command to learn how to add separator to menu.