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));
              
             

• 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";
               

                       };
               

                   }
              
             

• ENaviDecoratorLabel

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);
              
             

• 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…          
               

                         }
               

                    }
              
             

• CAknNavigationDecorator
• CMyAppUi
• EAknNaviDecoratorEventLeftTabArrow
• EAknNaviDecoratorEventRightTabArrow
• HandleNaviDecoratorEventL()
• MAknNaviDecoratorObserver
• iDecorator

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();
              
             

• 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 );
              
             

• CAknNaviLabel
• iNaviLabel

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();
              
             

• 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") );
              
             

• CAknNavigationControlContainer::CreateNavigationLabelL()