Tabs API Specification

Contents

1 Overview

The principal use of tab is to display information about the current state and view, and to help the user navigate in the application. Tabs can contain text, images or both.

Tabs can be used to help switch between different views of the application, or just give the user some additional information. Tabs are placed on the navigation pane. The navigation pane is a sub pane of the status pane. For details on navigation pane, see Navigation Pane API documentation.


API categorypublic
API typec++
Existed sinceLegacy S60 0.9
API librariesavkon.lib
Location/sf/mw/classicui/classicui_pub/tabs_api
Buildfiles/sf/mw/classicui/classicui_pub/tabs_api/group/bld.inf


1.1 Description

Tabs API provides support for creating tab group controls on the navigation pane. Tab group controls consists of tabs. Each tab can be accessed, new tabs can be created, or tabs can be replaced.

The navigation pane control contains factory methods for pre-implemented navigation pane tab group control type: CAknNavigationControlContainer::CreateTabGroupL() ). This method returns a navigation decorator object. A decorator object contains the tab group control itself and in addition, it provides support for navigation arrows, etc.

Tabs API 's most important classes are CAknTabGroup and MAknTabObserver . Tab group controls can be created at runtime, or from resource files, using the NAVI_DECORATOR resource headers.

Tabs 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 Tabs API are:

1.4 Class Structure

Summary of API classes and header files
ClassesFiles
CAknTab /epoc32/include/mw/akntabgrp.h CAknTabGroup /epoc32/include/mw/akntabgrp.h MAknTabObserver /epoc32/include/mw/AknTabObserver.h

Tabs API contains small number of classes providing functionality of the interface. The main classes are: CAknTabGroup , MaknTabObserver , MAknNavigationObserver .

Tabs API
Tabs API

2 Using The API

2.1 Creating tab group control from resource

The first step of creating a tab group 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 ENaviDecoratorControlTabGroup since the decorator will contain a label control, tab_width field specifies how many tabs are visible on the tab group. This value can be:

The id field of TAB is defined in the application's HRH file. 

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 = ENaviDecoratorControlTabGroup;
    control = TAB_GROUP
        {
        tab_width = EAknTabWidthWithTwoTabs;
        active = 0;
        tabs = {
            TAB
                {
                id = EAppView1Tab;
                txt = "View1";
                },
            TAB
                {
                id = EAView2Tab;
                txt = "View2";
                }
            };
        };
    }

2.1.1 Accessing tab group control created from resource

This example shows how to get the tab group object that was constructed from resources as described earlier. iDecorator is a pointer to CAknNavigationDecorator , iTabGroup is a pointer to CAknTabGroup . 

// Get the decorator constructed from resource
iDecorator = iNaviPane->ResourceDecorator();
// Get the tab group from decorator
iTabGroup = (CAknTabGroup*)iDecorator->DecoratedControl();
// Add new tab to tabbgroup
iTabGroup->AddTabL(1,_L("NewTab") );

2.2 Creating tab group control dynamically from resource

You need to define tab group control in the resource file as follows. 

RESOURCE NAVI_DECORATOR r_navi_decorator2
    {
    type = ENaviDecoratorControlTabGroup;
    control = TAB_GROUP
        {
        tab_width = EAknTabWidthWithTwoTabs;
        active = 0;
        tabs = {
            TAB
                {
                id = EAhdemoappView1Tab;
                txt = "ResView1";
                },
            TAB
                {
                id = EAhdemoappView2Tab;
                txt = "ResView2";
                }
            };
     };

A tab group resource identifier can directly be passed to CreateResourceReaderLC() , a new navigation pane decorator object is created by ConstructNavigationDecoratorFromResourceL() , and the created decorator, that contains the tab group control is pushed to the navigation pane, so it becomes visible on the pane. In the following example iDecorator is a pointer to CAknNavigationDecorator , and iNaviPane is a pointer to CAknNavigationControlContainer . This way multiple navigation pane decorators can be defined in the resource file, which contains tab group controls. 

TResourceReader reader;

// Read the resource
iEikonEnv->CreateResourceReaderLC( reader, R_AHDEMO_NAVI_DECORATOR2 );

// Construct the decorator from resource
iDecorator = iNaviPane->ConstructNavigationDecoratorFromResourceL( reader );
// Destroy the object that was put on CleanupStack by
// CreateResourceReaderLC()
CleanupStack::PopAndDestroy();

// Display the tab group on navigation pane
iNaviPane->PushL( *iDecorator );

2.3 Creating tab group control dynamically

First a tab group is created, then navigation pane decorator object is created with the tab group. The decorator must be pushed to the navigator pane. Note: SetActiveTabByIndex() must be called to make tab group visible. In the following example iDecorator is a pointer to CAknNavigationDecorator , iNaviPane is a pointer to CAknNavigationControlContainer and iTabGroup is a pointer to CAknTabGroup . 

// Create tab group
iTabGroup = CAknTabGroup::NewL( *iNaviPane );
// Set tab width
iTabGroup->SetTabFixedWidthL ( EAknTabWidthWithTwoLongTabs );
// Add tabs to tab group
iTabGroup->AddTabL(0,_L("Tab1") );
iTabGroup->AddTabL(1,_L("Tab2") );
// Create a navipane decorator containing the tab group
iDecorator = CAknNavigationDecorator::NewL( iNaviPane, iTabGroup, CAknNavigationDecorator::ETabGroup );
iNaviPane->PushL( *iDecorator );
// Activate the first tab
iTabGroup->SetActiveTabByIndex(0);

2.4 Creating a pre-implemented tab group

Decorator and the required tab group control can be created easily with method CAknNavigationControlContainer::CreateTabGroupL() . In the following example iDecorator is a pointer to CAknNavigationDecorator , iNaviPane is a pointer to CAknNavigationControlContainer and iTabGroup is a pointer to CAknTabGroup . 

// Create the decorator and the tab group control
iDecorator = iNaviPane->CreateTabGroupL(this);
iTabGroup = ( CAknTabGroup* ) iDecoratedTabGroup->DecoratedControl();
// Set tab width
iTabGroup->SetTabFixedWidthL ( EAknTabWidthWithTwoLongTabs );
// Add tabs to tab group
iTabGroup->AddTabL(0,_L("Tab1") );
iTabGroup->AddTabL(1,_L("Tab2") );
// Activate the first tab
iTabGroup->SetActiveTabByIndex(0);

2.5 Modifying tabs of tab group control

Tabs in tab group can be accessed by ID, or index. Index is the position of the tab in the tab group. Tab indexes are zero based. Tab ID can be any integer value. In the following example iTabGroup is a pointer to CAknTabGroup . Note: SetActiveTabByIndex() or SetActiveTabById() method must be called after adding the tabs, to make the tab group visible.

Adds a tab to a tab group with text. 

enum TabId
     {
     ETabFirst,
     ETabSecond,
     ETabThird
     };

iTabGroup->AddTabL( ETabFirst,_L( "Tab1" ) );
iTabGroup->AddTabL( ETabSecond,_L( "Tab2" ) );
iTabGroup->SetActiveTabByIndex(ETabFirst );

Adds a tab to the tab group with text and image. 

CFbsBitmap* bitmap1 = iEikonEnv->CreateBitmapL( _L( "c:\image.mbm" ), 0 );
CFbsBitmap* bitmap2 = iEikonEnv->CreateBitmapL( _L( "c:\image.mbm" ), 1 );
iTabGroup->AddTabL( ETabFirst, _L("tab1" ), bitmap1 );
iTabGroup->AddTabL( ETabSecond, _L("tab2" ), bitmap2 );

Replaces a tab with a new tab at tab with ID: ETabThird . 

iTabGroup->ReplaceTabL ( ETabThird, _L( "NewTab" ) );

Deletes a tab at tab with ID: ETabThird . 

iTabGroup->ReplaceTabL ( ETabThird, _L( "NewTab" ) );

Activates a tab with ID: ETabThird . 

iTabGroup->SetActiveTabById( ETabThird );

Gets the ID of the active tab. 

TInt actveTabId = iTabGroup->ActiveTabId();
if ( actveTabId == ETabThird )
     {
     // your code here…
     }

Gets the index of tab with ID: ETabThird . 

TInt tabIndex = iTabGroup->TabIndexFromId ( ETabThird );
if (tabIndex == 2 )
     {
     // your code here…
     }

Gets the IDof tab from index. 

TInt tabId = iTabGroup->TabIdFromIndex( 2 );
if ( tabId == ETabThird )
     {
     // your code here…
     }

Dims tab with ID: ETabThird . 

iTabGroup->DimTab( ETabThird, ETrue );

Gets the number of tabs in tab group. 

TInt numOfTabs = iTabGroup-> TabCount();

2.6 Observing tab group control events

There are two types of tab group events: tab events, and tab navigation events.

2.6.1 Tab events

This requires that the observing class must be derived from MAknTabObserver , and the observer must implement the method TabChangedL() . This event notifies the observer that the active tab has changed.

In the example, CMyAppUi observes the tab events. 

class CMyAppUi : public CAknViewAppUi, MAknTabObserver
     {
     …
     // From MAknTabObserver
     void TabChangedL( TInt aIndex );
     …
     };

In the following example, tab group has been defined in resources. So this tab group is accessed and then observer is registered. iDecorator is a pointer to CAknNavigationDecorator and iTabGroup is a pointer to CAknTabGroup . 

void CMyAppUi::Construct()
     {
     …
     // Get the decorator from resource
     iDecorator = iNaviPane->ResourceDecorator();
     if ( iDecoratedTabGroup )
        {
        // Get the tab group from decorator
        iTabGroup = ( CAknTabGroup* )iDecoratedTabGroup
->DecoratedControl();
        }

     // Register this object as a tab observer
     iTabGroup->SetObserver( this );
     …
     }

The TabChangedL() method receives tab events. 

void CMyAppUi::TabChangedL( TInt aIndex )
     {
     // Do event handling code here…
     }

2.6.2 Tab navigation events

The observer class must be derived from MCoeControlObserver , and the observer must implement the method HandleControlEventL() . This event notifies the observer about the position of the current tab in the tab group. The events are:

In the example, CMyAppUi observes the tab events. 

class CMyAppUi : public CAknViewAppUi, MCoeControlObserver
     {
     …
     // From MCoeControlObserver
     void HandleControlEventL( CCoeControl* aControl, TCoeEvent aEventType );
     …
     };

The following example accesses the tab group defined in resource, and then registers the observer. iDecorator is a pointer to CAknNavigationDecorator and iTabGroup is a pointer to CAknTabGroup . The observer is registered in the base class of the tab group. 

void CMyAppUi::Construct()
     {
     …
     // Get the decorator from resource
     iDecorator = iNaviPane->ResourceDecorator();
     if ( iDecoratedTabGroup )
        {
        // Get the tab group from decorator
        iTabGroup = ( CAknTabGroup* ) iDecoratedTabGroup->DecoratedControl();
        }

     // Register this object in the base class as a tab event observer
     CCoeControl* baseControl =  ( CCoeControl* )iTabGroup;
     baseControl->SetObserver( ( MCoeControlObserver* )this );
     …
     }

HandleControlEventL() receives tab navigation events. 

void CMyAppUi:: HandleControlEventL( CCoeControl* /*aControl*/,TCoeEvent aEventType )
     {
     switch (aEventType)
         {
         case MAknNavigationObserver::ENaviEventLeftMostItemReached:

             // Do event handling code here…

             break;
         default:
             break;
     }

2.7 Error handling

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

2.8 Memory and Performance Considerations

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

3 Glossary

3.1 Abbreviations

Tabs API abbreviations
API Application Programming Interface