Navigation Pane API Specification
Changes in Navigation Pane API documentation
Changes in Navigation Pane API
Purpose
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.
Classification and release information
Navigation Pane API is an SDK API and part of S60 3rd Edition.
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:
-
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
API class structure
Navigation Pane API contains small number of classes providing functionality
of the interface. The main classes are:
CAknNavigationControlContainer
, CAknNavigationDecorator
, CAknNaviLabel
.
Related APIs
CAknNaviLabel
CAknNavigationControlContainer
CAknNavigationDecorator
Related APIs
CAknNaviLabel
CAknNavigationControlContainer
CAknNavigationDecorator
CreateNavigationImageL()
CreateNavigationLabelL()
CreateTabGroupL()
NAVI_DECORATOR
NAVI_LABEL
Using Navigation Pane API
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.
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));
Related APIs
CAknAppUi
CAknAppUi::StatusPane()
CAknNavigationControlContainer
iNaviPane
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";
};
}
Related APIs
Navigation pane decorator buttons and events
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);
Related APIs
CAknNavigationDecorator::MakeScrollButtonVisible()
CAknNavigationDecorator::SetScrollButtonDimmed()
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…
}
}
Related APIs
CAknNavigationDecorator
CMyAppUi
EAknNaviDecoratorEventLeftTabArrow
EAknNaviDecoratorEventRightTabArrow
HandleNaviDecoratorEventL()
MAknNaviDecoratorObserver
iDecorator
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 );
Related APIs
CAknNavigationDecorator
iDecorator1
iDecorator2
iDecorator3
Navigation pane decorator and label control
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 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();
Related APIs
CAknNavigationControlContainer::ConstructNavigationDecoratorFromResourceL()
CAknNavigationDecorator
iDecorator
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 );
Related APIs
Accessing decorator created from resource
This example shows how to get the decorator object that was constructed
from resources as described in the
API
description. iDecorator
is a pointer to CAknNavigationDecorator
.
Subsequent calling attempts return NULL.
// Get the decorator constructed from resource
iDecorator = iNaviPane->ResourceDecorator();
Related APIs
CAknNavigationDecorator
iDecorator
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" ) );
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() );
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") );
Related APIs
CAknNavigationControlContainer::CreateNavigationLabelL()
Error handling
Navigation Pane API uses standard Symbian platform 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.
Memory overhead
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.
Limitations of the API
None.
Glossary
Abbreviations
Navigation Pane API abbreviations
API |
Application Programming Interface |
AVKON
|
Extensions and modifications to Uikon and other parts of the Symbian
platform application framework.
|
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.
|