Menus in the Windows API

Menus are a fundamental part of the graphical user interface (GUI) in Windows applications. They provide a structured way for users to select commands and options within an application. The Windows API offers a comprehensive set of functions and structures for creating, managing, and displaying menus.

Overview of Menu Concepts

A menu is typically composed of:

• Menu Bar: The horizontal bar at the top of a window containing top-level menu items (e.g., "File", "Edit", "View").
• Pop-up Menu: A menu that appears when a user clicks on a top-level menu item or performs an action like a right-click.
• Menu Item: An individual entry within a menu that represents a command or a sub-menu.
• Sub-menu: A menu that appears when a user selects a menu item that has an associated pop-up menu.

Key Structures and Functions

Structures

• MENUITEMINFO: This structure is used to specify or receive information about a menu item, including its text, state, type, and handle.
• TPMPARAMS: Used with TrackPopupMenuEx to specify the horizontal and vertical position of the menu.

Core Functions

• CreateMenu: Creates a new, empty menu. Returns a handle to the menu.
• CreatePopupMenu: Creates a new, empty pop-up menu.
• DestroyMenu: Destroys a menu and frees all memory associated with it.
• AppendMenu: Adds a new item to the end of a menu.
• InsertMenuItem: Inserts a new menu item at a specified position.
• GetMenuItemInfo: Retrieves information about a specific menu item.
• SetMenuItemInfo: Modifies information for a specific menu item.
• CheckMenuItem: Checks or unchecks a menu item.
• EnableMenuItem: Enables or disables a menu item.
• TrackPopupMenu / TrackPopupMenuEx: Displays a pop-up menu at a specified location on the screen. TrackPopupMenuEx offers more control over positioning and behavior.
• GetMenu: Retrieves the handle to the menu bar associated with a specified window.
• GetSubMenu: Retrieves the handle to a pop-up menu associated with a specified menu item.

Creating a Simple Menu

The process of creating a menu typically involves:

1. Creating the main menu handle using CreateMenu.
2. Creating pop-up menus for top-level items using CreatePopupMenu.
3. Adding menu items to the pop-up menus using AppendMenu or InsertMenuItem.
4. Associating the pop-up menus with the main menu using AppendMenu.
5. Assigning the main menu to the window using SetMenu.

Example: Adding a "File" Menu

Here's a conceptual C++ snippet showing how to add a simple "File" menu:

// Assume hwnd is the handle to your window
HMENU hMenu = CreateMenu();
HMENU hFileMenu = CreatePopupMenu();

// Add items to the File menu
AppendMenu(hFileMenu, MF_STRING, IDM_FILE_NEW, TEXT("New"));
AppendMenu(hFileMenu, MF_STRING, IDM_FILE_OPEN, TEXT("Open"));
AppendMenu(hFileMenu, MF_SEPARATOR, 0, NULL); // Add a separator
AppendMenu(hFileMenu, MF_STRING, IDM_FILE_EXIT, TEXT("Exit"));

// Add the File menu to the main menu bar
AppendMenu(hMenu, MF_POPUP | MF_STRING, (UINT_PTR)hFileMenu, TEXT("File"));

// Set the menu for the window
SetMenu(hwnd, hMenu);
            

Handling Menu Commands

When a user selects a menu item, the system sends a WM_COMMAND message to the window procedure of the window that owns the menu. The wParam of this message contains the identifier of the selected menu item.

LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam) {
    switch (uMsg) {
        case WM_COMMAND: {
            int wmId = LOWORD(wParam);
            // Parse the menu selections:
            switch (wmId) {
                case IDM_FILE_NEW:
                    // Handle "New" command
                    MessageBox(hwnd, TEXT("New command selected!"), TEXT("Info"), MB_OK);
                    break;
                case IDM_FILE_EXIT:
                    PostQuitMessage(0);
                    break;
                default:
                    return DefWindowProc(hwnd, uMsg, wParam, lParam);
            }
            break;
        }
        // ... other messages
        default:
            return DefWindowProc(hwnd, uMsg, wParam, lParam);
    }
    return 0;
}
            

Advanced Menu Features

• Checkmarks and Glyphs: Use MF_CHECKED or custom bitmaps to indicate selected options.
• Graying and Disabling: Use MF_GRAYED or MF_DISABLED to indicate unavailable options.
• Owner-Drawn Menus: For highly customized menu items, you can use owner-drawing with the MENUINFO structure and the WM_DRAWITEM message.
• Context Menus: Menus that appear on right-click, typically created using TrackPopupMenuEx.