Options Menu API: API description

Options Menu API provides support for a number of menus (called menu panes), each attached to a main menu bar or a menu item.

The menu support is implemented in two main classes: CEikMenuBar and CEikMenuPane. The menu structure is defined in the resource file as a menu bar structure (MENU_BAR), which references one or more menu panes in a list of MENU_TITLE structures. The menu bar itself is usually referenced in the application information resource structure (EIK_APP_INFO) or in the view resource structure (AVKON_VIEW), but can also be referenced in AVKON_SETTING_PAGE resource structure or a menu bar resource structure can directly be passed to CAknDialog’s ConstructL().

In S60, all of the menu pane resources of a menu bar are read on construction and joined to form a single menu pane. This ensures that the menu panes are stacked on top of each other, with the first pane at the bottom of the menu pane, and the last at the top. The txt fields of MENU_TITLEs are omitted. This allows S60 applications to specify menus based on a set of individual menu option groups.

When the application is started, the menu bar is constructed and the menu bar resource is read. Whenever the menu is displayed, or the user navigates between menu panes, a menu pane is constructed and the appropriate menu pane resource is read.

Use cases

The main use cases of the Options Menu API are:

1. Specifying menus in resource files
2. Initializing menus
   • Adding menu items
   • Removing menu items
   • Testing the existence of menu items
3. Handling command IDs
4. Context sensitive menus
5. Opening menus
6. Closing menus
7. Marquee
8. Indicating items
   • Items with check mark
   • Radio button group
9. Application-level hotkeys

API class structure

Options menu API contains little number of classes providing functionality of the interface. In the following class diagrams, the API classes are grouped together according to their roles and functionality.

Class diagram in Figure 1 shows that the API consists mainly from the CEikMenuBar and the CEikMenuPane classes. CEikMenuBar represents the first level of the menu and encapsulates a number of menu panes through the nested class CItemArray. An item in it (CEikMenuPaneItem) refers to the resource ID of the relevant menu pane CEikMenuPane.

The most often used API part is CEikMenuPane. Menu manipulation is usually done with this. In case of this class, CItemArray cannot be got. An item or item data can be queried directly with the methods of the CEikMenuPane class.

The Figure shows, that each menu pane item either generates a command to the menu observer, or opens a submenu pane (cascading).

Each menu bar has one observer: MEikMenuObserver. Clients of the API cannot change or add observers after menu bar and menu pane construction. MEikMenuObserver is implemented by the UI components that support menu. They have been listed already above.