Purpose
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.
Classification and release information
Navigation Pane API
is an SDK API and part of S60 3rd Edition.
API 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.
Use Cases
The main use cases of Tabs API are:
-
Creating tab group control from resource
-
Accessing tab group control created from resource
-
Creating tab group control dynamically from resource
-
Creating tab group control dynamically
-
Creating a pre-implemented tab group
-
Modifying tabs of tab group control
-
Observing tab group control events
API Class Structure
Tabs API contains small number of classes providing functionality of the
interface. The main classes are:
CAknTabGroup
,
MaknTabObserver
,
MAknNavigationObserver
.
Related APIs
-
CAknTabGroup
-
MAknNavigationObserver
-
MaknTabObserver
Related APIs
-
CAknNavigationControlContainer::CreateTabGroupL()
-
CAknTabGroup
-
MAknTabObserver
-
NAVI_DECORATOR
Using Tabs API
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:
-
EAknTabWidthWithTwoTabs
-
EAknTabWidthWithTwoLongTabs
-
EAknTabWidthWithThreeTabs
-
EAknTabWidthWithThreeLongTabs
-
EAknTabWidthWithFourTabs
-
EAknTabWidthWithOneTab
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";
}
};
};
}
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") );
Related APIs
-
CAknNavigationDecorator
-
CAknTabGroup
-
iDecorator
-
iTabGroup
Related APIs
-
EAknTabWidthWithFourTabs
-
EAknTabWidthWithOneTab
-
EAknTabWidthWithThreeLongTabs
-
EAknTabWidthWithThreeTabs
-
EAknTabWidthWithTwoLongTabs
-
EAknTabWidthWithTwoTabs
-
ENaviDecoratorControlTabGroup
-
id
-
tab_width
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 );
Related APIs
-
CAknNavigationControlContainer
-
CAknNavigationDecorator
-
ConstructNavigationDecoratorFromResourceL()
-
CreateResourceReaderLC()
-
iDecorator
-
iNaviPane
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);
Related APIs
-
CAknNavigationControlContainer
-
CAknNavigationDecorator
-
CAknTabGroup
-
SetActiveTabByIndex()
-
iDecorator
-
iNaviPane
-
iTabGroup
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);
Related APIs
-
CAknNavigationControlContainer
-
CAknNavigationControlContainer::CreateTabGroupL()
-
CAknNavigationDecorator
-
CAknTabGroup
-
iDecorator
-
iNaviPane
-
iTabGroup
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();
Related APIs
-
CAknTabGroup
-
ETabThird
-
SetActiveTabById()
-
SetActiveTabByIndex()
-
iTabGroup
Observing tab group control events
There are two types of tab group events: tab events, and tab navigation
events.
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…
}
Related APIs
-
CAknNavigationDecorator
-
CAknTabGroup
-
CMyAppUi
-
MAknTabObserver
-
TabChangedL()
-
iDecorator
-
iTabGroup
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:
-
ENaviEventHandleNavigation
-
ENaviEventLeftMostItemReached
-
ENaviEventRightMostItemReached
-
ENaviEventOneItemExists
-
ENaviEventRedrawNeeded
-
ENaviEventAlreadyLeftmostItem
-
ENaviEventAlreadyRightmostItem
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;
}
Related APIs
-
CAknNavigationDecorator
-
CAknTabGroup
-
CMyAppUi
-
ENaviEventAlreadyLeftmostItem
-
ENaviEventAlreadyRightmostItem
-
ENaviEventHandleNavigation
-
ENaviEventLeftMostItemReached
-
ENaviEventOneItemExists
-
ENaviEventRedrawNeeded
-
ENaviEventRightMostItemReached
-
HandleControlEventL()
-
MCoeControlObserver
-
iDecorator
-
iTabGroup
Error handling
Tabs API uses the standard Symbian platform error reporting mechanism. Possible
panic circumstances and panic codes are indicated in class or method descriptions.
Memory overhead
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.
Limitations of the API
None.
