Navigation Pane API Specification


1 Overview

The principal use of the navigation pane is to display information about the current state and view, and to help the user navigate in the application. The pane can contain tabs, a navigation label, a navigation image, a hint text, a volume control indicator or editor indicators.

Navigation pane can be used to help switch between different views of the application using tabs, displaying the progress of an ongoing process, or just a note, that gives the user some additional information.

Navigation pane is a sub pane of the Status pane.

API categorypublic
API typec++
Existed sinceLegacy S60 0.9
API librariesavkon.lib

1.1 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.

1.2 Changes

Navigation Pane API is an SDK API and part of S60 release 3.x.


1.3 Use Cases

The main use cases of Navigation Pane API are:

1.4 Class Structure

Summary of API classes and header files
CAknNaviLabel /epoc32/include/mw/aknnavilabel.h CAknNavigationControlContainer /epoc32/include/mw/aknnavi.h CAknNavigationDecorator /epoc32/include/mw/aknnavide.h MAknNaviDecoratorObserver /epoc32/include/mw/AknNaviDecoratorObserver.h MAknNavigationContainerInterface /epoc32/include/mw/aknnavi.h MAknNavigationDecoratorInterface /epoc32/include/mw/aknnavi.h MAknNavigationObserver /epoc32/include/mw/AknNaviObserver.h

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

Navigation Pane API
Navigation Pane API

2 Using The API

2.1 Navigation pane

Navigation pane consists of a navigation decorators, and a navigation decorator controls. The navigation pane decorator control can be a label, tab group, or volume control. The control inside the navigation pane can be accessed by the containing decorator.

2.1.1 Accessing the default navigation pane control

When using Navigation Pane API, the first step is to access a pointer to the application's status pane by calling the CAknAppUi::StatusPane() method. CAknAppUi is the base class of the application UI. After getting a pointer to the Status pane, the default pointer to the Navigation pane can be accessed. iNaviPane is a pointer to CAknNavigationControlContainer .

The status pane layout is read from AVKON resources. The layout resource contains also information about the control that is put inside the sub panes. It depends on the status pane layout if CAknNavigationControlContainer is available.

// Gets a pointer to the status pane
CEikStatusPane* sp = StatusPane();
// Fetch pointer to the default navi pane control
iNaviPane = ( CAknNavigationControlContainer*)sp->ControlL(

2.1.2 Creating navigation pane from resource with a label control

The first step of creating a navigation pane is to specify the status pane and the navigation pane decorator resources. Status pane's ID and type field values are defined in avkon.hrh. Decorator's resource type is defined as ENaviDecoratorLabel since the decorator contains a label control.

    status_pane = r_app_status_pane;
            id = EEikStatusPaneUidNavi;
            type = EAknCtNaviPane;
            resource = r_navi_decorator;
    type = ENaviDecoratorLabel;
    control = NAVI_LABEL

2.2 Navigation pane decorator buttons and events

2.2.1 Manipulating decorator buttons

Navigation pane buttons are shown as arrows at both ends of the navigation pane. Each button's dimness can be changed independently. Note that navigation pane buttons are not visible by default. CAknNavigationDecorator::MakeScrollButtonVisible() must be called to display the two buttons in navigation pane. After setting the visibility, buttons can be dimmed by calling the CAknNavigationDecorator::SetScrollButtonDimmed() method.

// Set the visibility of the buttons
iDecorator->MakeScrollButtonVisible( ETrue );
// Show the left arrow button
iDecorator->SetScrollButtonDimmed(CAknNavigationDecorator::ELeftButton, EFalse);
// Hide the right arrow button
iDecorator->SetScrollButtonDimmed(CAknNavigationDecorator::ERightButton, ETrue);

2.2.2 Observing decorator events

Decorator can send the EAknNaviDecoratorEventRightTabArrow , and EAknNaviDecoratorEventLeftTabArrow events to an observer object. To handle these events, an observer has to be registered to the decorator object. The object that observes decorator events, must derive from the class MAknNaviDecoratorObserver and must implement the HandleNaviDecoratorEventL() method, which will get the decorator's pointer events.

In the example, CMyAppUi observes the decorator events.

class CMyAppUi : public CAknViewAppUi, MAknNaviDecoratorObserver
     // From MAknNaviDecoratorObserver
     void HandleNaviDecoratorEventL( TInt aEventID );

Register this object to decorator, so the object receives events. iDecorator is a pointer to CAknNavigationDecorator .

void CMyAppUi::Construct()
     // Access status pane
     CEikStatusPane* sp = StatusPane();
     // Get a pointer to navi pane
     iNaviPane = (CAknNavigationControlContainer*)sp->ControlL(
     // Get a pointer to the decorator created from resource
     iDecorator = iNaviPane->ResourceDecorator();
     // Register this object as an observer of decorator
     iDecorator->SetNaviDecoratorObserver( this );

HandleNaviDecoratorEventL() now can receive decorator events.

void CMyAppUi::HandleNaviDecoratorEventL( TInt aEventID )
     if ( aEventID == EAknNaviDecoratorEventRightTabArrow )
          // Do Event handling code here…
     else if (aEventID == EAknNaviDecoratorEventRightTabArrow )
          // Do Event handling code here…

2.3 Using navigation pane's control stack

To make navigation pane decorators visible on navigation pane, decorator objects must be put on the navigation pane's control stack. The topmost object on the navigation pane control stack is shown in the pane. The decorators can be popped, replaced, and pushed to the stack. If the same decorator is pushed to the stack, and the same decorator was already on the stack, then that decorator becomes the topmost object on the stack, and is shown in the pane. In the following example iDecorator1 , iDecorator2 , iDecorator3 are pointers to CAknNavigationDecorator .

// Two different decorators are pushed to the control stack
// iDecorator2 will be shown on the navigation pane
iNaviPane->PushL( *iDecorator1 );
iNaviPane->PushL( *iDecorator2 );
// Pushing iDecorator1 again
// iDecorator1 will be shown on the navigation pane
iNaviPane->PushL( *iDecorator1 );
// Pop the topmost opject from the stack ( *iDecorator1 )
// iDecorator2 will be shown on the navigation pane
iNaviPane->Pop( iDecorator1 );
// Replace iDecorator2 with iDecorator3
// iDecorator3 will be shown on the navigation pane
iNaviPane->ReplaceL( *iDecorator2, *iDecorator3 );

2.4 Navigation pane decorator and label control

2.4.1 Creating decorator dynamically from resource with a label control

Create navigation pane decorator in resource file.

RESOURCE NAVI_DECORATOR r_navi_decorator_a
    type = ENaviDecoratorLabel;
    control = NAVI_LABEL

A navigation pane decorator resource identifier is passed to CAknNavigationControlContainer::ConstructNavigationDecoratorFromResourceL() .

In the following example iDecorator is a pointer to CAknNavigationDecorator . This way multiple navigation pane decorators can be defined in the resource file, which later can be used to create navigation pane decorator controls. Navigation pane decorators visibility can be changed using the navigation pane's control stack. See [Navigation_Pane_API_Specification.topic3.3 Using navigation pane's control stack].

TResourceReader reader;
// Read the resource
iEikonEnv->CreateResourceReaderLC( reader, R_NAVI_DECORATOR_A );
// Construct the decorator from resource
iDecorator = iNaviPane->ConstructNavigationDecoratorFromResourceL( reader );
// Destroy the object that was put on CleanupStack by
// CreateResourceReaderLC()

2.4.2 Creating decorator dynamically with a label control

Navigation pane decorator objects can also be created dynamically. First a label object must be created, that later is added to the navigation decorator object. In the example below iNaviLabel is a pointer to CAknNaviLabel .

// Create the label object
iNaviLabel = new( ELeave ) CAknNaviLabel;
// Set label type and label text
iNaviLabel->SetNaviLabelType( CAknNaviLabel:: ENavigationLabel);
iNaviLabel->SetTextL( _L( "label" ) );
// Create the decorator object with the label
iDecorator = CAknNavigationDecorator::NewL( iNaviPane, iNaviLabel, CAknNavigationDecorator::ENaviLabel );

2.4.3 Accessing decorator created from resource

This example shows how to get the decorator object that was constructed from resources as described in the [Navigation_Pane_API3.html API description]. iDecorator is a pointer to CAknNavigationDecorator . Subsequent calling attempts return NULL.

// Get the decorator constructed from resource
iDecorator = iNaviPane->ResourceDecorator();

2.4.4 Setting text of label control in decorator

It is very simple to change the text of the label control.

// Setting the new text of the label
iNaviLabel->SetTextL( _L( "new label" ) );

This example shows how to change the label if the navigation pane was constructed from resource.

// Get the decorator constructed from resource
iDecorator = iNaviPane->ResourceDecorator();
// Getting the control from the decorator object
iNaviLabel = ( CAknNaviLabel* )iDecorator->DecoratedControl();
// Change text
iNaviLabel->SetTextL( _L( "new label" ) );

2.4.5 Getting text of label control in decorator

In this example the text of the label is displayed as an info message.

// Label text as info message
CEikonEnv::Static()->InfoMsg( *iNaviLabel->Text() );

2.4.6 Creating a decorator with a label in a single call

Decorator and the required label control can be created easily with this function. The method CAknNavigationControlContainer::CreateNavigationLabelL() creates a decorator and a label object in a single call. For creating and using tab group controls, see the Tabs API documentation.

// Create the decorator and the label control
iDecorator = iNaviPane->CreateNavigationLabelL( _L("label") );

2.5 Error handling

Navigation Pane API uses standard Symbian OS error reporting mechanism. Possible panic circumstances and panic codes are indicated in class or method descriptions.

Leaves and system wide error codes as function return values are used if the error is recoverable. A client application can handle these errors similarly as a normal Symbian platform application.

2.6 Memory and Performance Considerations

The amount of reserved memory for application owned navigation pane controls depend on the application, but despite the application the amount of reserved memory is relatively small.

3 Glossary

3.1 Abbreviations

Navigation Pane API abbreviations
API Application Programming Interface
AVKON S60 extensions and modifications to Uikon and other parts of the Symbian

OS application framework.

3.2 Definitions

Navigation Pane API definitions
Navigation pane Display information about the current state and view, and

to help the user navigate in the application.

Decorator Decorator contains navigation pane controls.
Control stack Control stack holds decorator object. The topmost decorator is displayed

on the navigation pane.