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.
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));
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";
};
}
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);
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…
}
}
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 );
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();
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 );
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();
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" ) );
In this example the text of the label is displayed as an info message.
// Label text as info message CEikonEnv::Static()->InfoMsg( *iNaviLabel->Text() );
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") );
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.
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.
None.