How to Define a Menu

Menus are defined in the application resource file using a resource of type MENU_BAR together with one or more resources of type MENU_PANE. The items on a menu pane are defined with the resource MENU_ITEM. When a menu item is chosen by the user, the command associated with that item is invoked, resulting in a call to HandleCommandL() in the View class.

For a basic menu, no code is needed in the application's C++ source; the framework builds the menu from the resource file.

The resource file defines the static features of a menu, including

• the text on the menu bar,

• the number of menu panes,

• the number of items in the menu panes,

• the text of the menu items and

• the commands invoked by the menu items.

The following example defines a menu bar with three panes: "UIQApp" (the application pane), "Edit" and "Folder".

RESOURCE MENU_BAR r_qapp_list_menubar
    {
    titles=
        {
        MENU_TITLE { menu_pane=r_qapp_list_qapp_menu; txt="UIQApp"; },
        MENU_TITLE { menu_pane=r_qapp_list_edit_menu; txt="Edit";},
        MENU_TITLE { menu_pane=r_qapp_list_cat_menu; txt="Folder"; DECLARE_CATEGORY_MENU_TITLE;}
        };
    }

The DECLARE_CATEGORY_MENU_TITLE macro can be used to give the category menu "folder" the correct look.

Next, define the menu items for the menu panes. For example, the "UIQApp" menu pane has the menu item "New":

RESOURCE MENU_PANE r_qapp_list_qapp_menu
    {
    items=
        {
        MENU_ITEM
            {
            command=EUIQAppCmdNew;
            txt="New";
            }
        };
    }

EUIQAppCmdNew is declared in the application's .hrh file.

Separators, check boxes and radio buttons can be used in menu items. To do this, set the flags field of the MENU_ITEM resource:

• EEikMenuItemSeparatorAfter for a separator,

• EEikMenuItemCheckBox for a check box,

• EEikMenuItemRadioStart, EEikMenuItemRadioMiddle or EEikMenuItemRadioEnd for a radio button.

RESOURCE MENU_PANE r_example_menu
 {
 items=
    {
    // Item followed by separator
    MENU_ITEM
    {
    command=EExampleCmd1;
    txt="Command1";
    flags=EEikMenuItemSeparatorAfter;
    },
    // Item with a checkbox
    MENU_ITEM
    {
    command=EExampleCmdStop;
    txt="Stop";
    flags=EEikMenuItemCheckBox;
    }
  };
 }

• Cascading menus are supported but the use of multiple levels is not recommended.

• The application has to set the state of check boxes and radio buttons before they are displayed; see How to use menus dynamically.

• "Close" is not required by UIQ applications and should not be provided. However, a close option may be used in debug builds when testing for memory and resource leaks; see the example code in How to use menus dynamically.

• For guidelines on menu design, see the UIQ Style Guide.