47.1.4 Menu Items

This section provides detailed information about menu items.

47.1.4.1 Menu-Item Types

A menu can contain two main types of menu items: command items and pop-up items. When the user chooses a command item, Windows sends a WM_COMMAND or WM_SYSCOMMAND message to the window procedure of the menu's owner window. (A command item in a System menu generates a WM_SYSCOMMAND message, all other command items generate WM_COMMAND messages.) When the user chooses a pop-up item, Windows displays a pop-up menu but doesn't send a command message to the window procedure.

Typically, the menu items in an application's menu bar consist of pop-up items, and the menu items in a pop-up menu consist of a command items. Since a pop-up menu can contain pop-up items, pop-up menus can originate from within pop-up menus, producing the cascading effect shown in the following illustration.

When you include a pop-up item in a pop-up menu, windows automatically adds a small arrow to the right of the menu item's string or bitmap (see the Word Processing and Spreadsheet items in the preceding illustration). The arrow is a cue to the user that selecting the item displays another pop-up menu.

47.1.4.2 Menu-Item Identifier

Each command item has an identifier associated with it. An identifier is an application-defined integer value that Windows sends to the window procedure of the menu's owner window when the user selects a command item. Windows sends the identifier as part of a WM_COMMAND message. The window procedure examines the identifier to determine the source of the message, then processes the message accordingly.

A menu identifier must be a value from 0 to 65,535 even though it is a 32-bit integer. This is because the WM_COMMAND message passes a menu identifier as the low-order word of its wParam parameter.

A pop-up item has no identifier. A pop-up item doesn't need an identifier because Windows doesn't send a WM_COMMAND message when the user selects a pop-up item. Instead, Windows invokes the pop-up menu associated with the pop-up item.

47.1.4.3 Checked and Unchecked Menu Items

A menu item can be either checked or unchecked. When a menu item is checked, Windows displays a check mark bitmap to the left of the menu item. When the menu item is unchecked, Windows doesn't display the check mark bitmap. Only menu-items in a pop-up menu can be checked—menu items in a menu bar can't be checked.

An application typically uses check marks to indicate options that are in effect. For example, when the user chooses paragraph formatting options in the menu of a word-processing application, the application would check the chosen options. The following illustration shows check marks next to the Left and Single Space options in an application's Paragraph menu.

A menu item has a check mark attribute that controls whether the item is checked or unchecked. You can set a menu item's check mark attribute by using the CheckMenuItem function. You can find out whether a menu item is currently checked or unchecked by calling the GetMenuState function.

Windows provides a default check mark bitmap that it displays next to a checked menu item. If you need to, you can substitute your own bitmaps and direct Windows to use them instead of the default. You can associate two bitmaps with each menu item—one for when the menu item is checked, and another for when it is unchecked. You can use the SetMenuItemBitmaps function to associate the check mark bitmaps with a menu item.

Windows requires that your check mark bitmaps have the same dimensions as the default check mark bitmap. You can use the GetMenuCheckMarkDimensions function to retrieve these dimensions.

You can provide check mark bitmaps as bitmap resources, or you can create the bitmaps at run time by using the GDI bitmap functions. Be aware that a bitmap resource won't be suitable for all video resolutions and aspect ratios, so you'll need to size the bitmap as appropriate. Also, the check mark bitmaps can be either monochrome or color; however, on a color display the bitmap colors are inverted when the menu item is highlighted, and the result my be undesirable. For more information about using bitmaps, see Chapter 63, “Bitmaps.”

47.1.4.4 Enabled, Disabled, and Grayed Menu Items

A menu item can be enabled, disabled, or grayed. By default, a menu item is enabled. When the user chooses an enabled menu item, Window sends a command message to the corresponding window procedure or displays the corresponding pop-up menu (depending on whether the menu item is a command item or a pop-up item).

A disabled menu item and a grayed menu item are similar—neither generates a command message or displays a pop-up menu when the user chooses it. The difference is that the text of a grayed menu item is dimmed and the text of a disabled menu item isn't. You should gray or disable menu items that aren't available to the user. Typically, applications gray an unavailable menu item rather than disable it, because graying provides a visual cue to the user that the item isn't available; disabling the item doesn't provide this cue. The following illustration shows grayed items in an Edit menu.

You can use the EnableMenuItem function to enable, disable, or gray a menu item. You can find out whether a menu item is enabled, disabled, or grayed by calling the GetMenuState state function.

47.1.4.5 Menu-Item Separators and Breaks

Windows provides a special type of menu item, called a separator, that consists of a horizontal rule line. You can use a separator menu item in a pop-up menu to divide a menu into groups of related items. A separator item cannot be used in a menu bar. The user cannot select a separator menu item, and a separator does not send command messages to the window procedure.

When a menu bar contains more items than will fit on one line in a menu bar, Windows automatically breaks the menu into two or more lines. You can force a line break in a menu bar by assigning the MF_MENUBREAK break flag to an item in the menu bar. Windows places that item and all remaining items on a new line.

You can use the MF_MENUBREAK and MF_MENUBARBREAK flags with items in a pop-up menu to divide the items into multiple columns. When an item has been assigned the MF_MENUBREAK flag, Windows places that item and all remaining items in a new column. The MF_MENUBARBREAK flag creates a similar effect except that Windows includes a vertical line in the menu to separate the new column from the old one.

47.1.4.6 Menu-Item Position

Windows assigns an integer position-value to each item in a menu and uses the value to keep track of each item's position within the menu. The position values are zero-based. That is, the first item in a menu occupies position zero, the next item occupies position one, and so on. In a menu bar, the leftmost menu item is considered the first item, so it occupies position zero. In a pop-up menu, the topmost menu item occupies position zero. The following illustration shows the position values of items in a menu bar and a pop-up menu.

Note:

Note that Windows also assigns position values to menu-item separators.

Windows includes a number of functions that you can use to add an item to a menu, delete an item from a menu, or modify an existing item in a menu. When you call one of these functions, you can identify the item to be modified either by its position value or, if it is a command item, by its identifier. You do so by specifying either the MF_BYPOSITION flag or the MF_BYCOMMAND flag along with the position value or menu-item identifier. For more information about modifying the contents of a menu, see Section 0.1.10, “Menu Modifications.”

47.1.4.7 Highlighted Menu Items

Windows automatically highlights menu items as the user selects them. If you need to, you can explicitly highlight or remove the highlighting from a menu item in the menu bar by calling the HiliteMenuItem function. This function has no effect on menu items in pop-up menus. Note that when you use HiliteMenuItem to highlight a menu item, the menu item appears to be selected but isn't (so if the user presses ENTER, the highlighted item isn't chosen).

47.1.4.8 Owner-drawn Menu Items

Your application can take complete control over the appearance of a menu item by using an owner-drawn item. An owner-drawn item is one for which your application has total responsibility for drawing in its normal, selected (highlighted), checked, and unchecked states.

For example, suppose your application provides a menu from which the user can choose a font. Your application could draw each item by using the font that the item represents; the item for roman would be drawn with a roman font, the item for italic would be drawn in italic, and so on.

For information on how to create owner-drawn menu items, see Section 0.2.4, “Creating Owner-drawn Menu Items.”

47.1.4.9 The Help Item

To present a standard interface to the novice user, your application should include a Help item in its menu bars. The item should read “Help” and it should be the rightmost item in the menu bar.