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 category | public |
| API type | c++ |
| Existed since | Legacy S60 0.9 |
| API libraries | avkon.lib |
| Location | /sf/mw/classicui/classicui_pub/navigation_pane_api
|
| Buildfiles | /sf/mw/classicui/classicui_pub/navigation_pane_api/group/bld.inf
|
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.
None.
1.3 Use Cases
The main use cases of Navigation Pane API are:
- Accessing the default navigation pane control
- Creating navigation pane from resource with a label control
- Manipulating decorator buttons
- Observing decorator events
- Using the navigation pane's control stack
- Creating decorator dynamically from resource with a label control
- Creating decorator dynamically with a label control
- Accessing decorator created from resource
- Setting text of label control in decorator
- Getting text of label control in decorator
- Creating a decorator with a label in a single call
1.4 Class Structure
| Classes | Files |
|---|---|
|
/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 .
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(
TUid::Uid(EEikStatusPaneUidNavi));
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.
RESOURCE EIK_APP_INFO
{
status_pane = r_app_status_pane;
}
RESOURCE STATUS_PANE_APP_MODEL r_app_status_pane
{
panes=
{
SPANE_PANE
{
id = EEikStatusPaneUidNavi;
type = EAknCtNaviPane;
resource = r_navi_decorator;
}
};
}
RESOURCE NAVI_DECORATOR r_navi_decorator
{
type = ENaviDecoratorLabel;
control = NAVI_LABEL
{
txt="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(
TUid::Uid(EEikStatusPaneUidNavi));
// 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
{
txt="label_a";
};
}
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() CleanupStack::PopAndDestroy();
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
| 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 | 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. |