Navigation Pane API: API description

Navigation Pane API provides support for accessing the application’s navigation pane. Each application has its own navigation pane.

The navigation pane control contains factory methods for each pre-implemented navigation pane control type: CreateTabGroupL(), CreateNavigationLabelL() and CreateNavigationImageL(). These methods return navigation decorator objects. A decorator object contains the control itself and in addition it provides support for navigation arrows, etc.

The navigation pane contains an object stack. The navigation decorator objects can be pushed in and popped out to/from the navigation pane stack. The topmost object on the navigation pane control stack is shown in the pane. Only the editor indicators have priority over others. The editor indicator control is always on top if it exists in the stack.

When a navigation decorator object is deleted, it is popped out from the navigation pane control stack automatically. Explicit pop operation is not needed.

Navigation Pane API’s most important classes are CAknNavigationControlContainer, CAknNavigationDecorator and CAknNaviLabel. The container control contains a stack of objects and the top item is shown on the pane. The decorator decorates the actual navigation pane controls. Label is the actual control decoration on the navigation pane.

Navigation pane controls can be created at runtime, or from resource files, using the NAVI_DECORATOR and NAVI_LABEL resource headers.

Navigation Pane API can be used by any application that is designed to show information outside the view area of the application.

Use cases

The main use cases of Navigation Pane API are:

1. Accessing the default navigation pane control
2. Creating navigation pane from resource with a label control
3. Manipulating decorator buttons
4. Observing decorator events
5. Using the navigation pane's control stack
6. Creating decorator dynamically from resource with a label control
7. Creating decorator dynamically with a label control
8. Accessing decorator created from resource
9. Setting text of label control in decorator
10. Getting text of label control in decorator
11. Creating a decorator with a label in a single call

API class structure

Navigation Pane API contains small number of classes providing functionality of the interface. The main classes are: CAknNavigationControlContainer, CAknNavigationDecorator, CAknNaviLabel.