Working with Toolbar API - S60 Touch UI

Comments

23 Sep
2009

Article Review by User:FireSwarog (20090923)

This article illustrates how to use one more new API of S60 5th: Toolbar API. With the help of this API you can orginize buttons on the screen and easy process events.

The code snippets contain detailed comments - such approach is a very convinient for newbies. Also author provides demo projects - it is a useful thing for experiments with new features.

---

Log in or Join to leave comments.

Article Metadata

---

Code Example

Source file: Media:Toolbar.zip

---

Article

Created: kiran10182 (02 Nov 2008)

Last edited: hamishwillee (08 Feb 2012)

Overview

Toolbar API is a new feature offered by S60 5th edition Touch UI concept. In this article we will learn how to play with Toolbar API with different methods.

What is Toolbar API

As shown in the above figure, Toolbar is a placeholder for different UI components. It can be fixed or float. You can place buttons on Toolbar.

Creating Toolbar using resource

Define resource

RESOURCE EIK_APP_INFO
	{
	menubar = r_menubar;
	cba = R_AVKON_SOFTKEYS_OPTIONS_EXIT;
	custom_app_info_extension = r_toolbar_ext; // This is the line we need to include to enable Toolbar
	}
 
// Add following resource definition for toolbar declared in EIK_APP_INFO
RESOURCE EIK_APP_INFO_EXT r_toolbar_ext
	{
		popup_toolbar = r_test_toolbar;
	}
 
RESOURCE AVKON_TOOLBAR r_test_toolbar
{
	flags = KAknToolbarFixed;
	items =
	{
		TBAR_CTRL
		{
		type = EAknCtButton;
		id = ECommand1; // In this example, we are using same set of commands as of used in AppUi:HandleCommandL
		control = AVKON_BUTTON
			{
			flags = KAknButtonTextInsideFrame;
			states =
				{
				AVKON_BUTTON_STATE
					{
					txt = "button1";
					helptxt = "help text1";
					}
				};
			};
		},
		TBAR_CTRL
		{
		type = EAknCtButton;
		id = ECommand2; // In this example, we are using same set of commands as of used in AppUi:HandleCommandL
		control = AVKON_BUTTON
			{
			flags = KAknButtonTextInsideFrame;
			states =
				{
				AVKON_BUTTON_STATE
					{
					txt = "button2";
					helptxt = "help text2";
					}
				};
			};
		}
	};
}

Implementing Toolbar API

• We need to derive from Toolbar observer to get notification on the Toolbar events. The mixin class is MAknToolbarObserver and the callback function we might be interested in are:

1. virtual void OfferToolbarEventL( TInt aCommand ) = 0;
2. virtual void DynInitToolbarL( TInt aResourceId, CAknToolbar* aToolbar );

Here virtual void OfferToolbarEventL( TInt aCommand ) = 0; is a pure virtual function hence we need to define it at least in our application. It will be called when any event occurs on the Toolbar item.

ToolbarAppUi.h

#include <akntoolbarobserver.h> // Include this header file for MAknToolbarObserver and Link against: eikcoctl.lib
.....
.....
class CToolbarAppUi : public CAknAppUi, public MAknToolbarObserver
{
....
....
//From MAknToolbarObserver
	void OfferToolbarEventL(TInt aCommand);
....
....	
};

ToolbarAppUi.cpp

void CToolbarAppUi::ConstructL()
{
    ......
 
    //Set "this" to toolbar observer - We will receive events in OfferToolbarEventL
    if(CurrentFixedToolbar())
        CurrentFixedToolbar()->SetToolbarObserver(this);
    .......
    .......
}
 
//From MAknToolbarObserver
void CToolbarAppUi::OfferToolbarEventL(TInt aCommand)
{
    HandleCommandL(aCommand); // In this example we are simply calling HandleCommandL by passing received command
}

Creating Toolbar using resource with Toolbar Extension

Define resource with toolbar extension

RESOURCE EIK_APP_INFO
{
    menubar = r_menubar;
    cba = R_AVKON_SOFTKEYS_OPTIONS_EXIT;
    custom_app_info_extension = r_toolbar_ext; // This is the line we need to include to enable Toolbar
}
 
// Add following resource definition for toolbar declared in EIK_APP_INFO
RESOURCE EIK_APP_INFO_EXT r_toolbar_ext
{
    popup_toolbar = r_test_toolbar;
}
 
RESOURCE AVKON_TOOLBAR r_test_toolbar
{
	flags = KAknToolbarFixed;
	items =
	{
	TBAR_CTRL
		{
		type = EAknCtButton;
		id = ECommand1; // We are using same set of commands as of used in AppUi:HandleCommandL
		control = AVKON_BUTTON
			{
			flags = KAknButtonTextInsideFrame;
			states =
				{
				AVKON_BUTTON_STATE
					{
					txt = "button1";
					helptxt = "help text1";
					}
				};
			};
		},
	TBAR_CTRL
		{
		type = EAknCtButton;
		id = ECommand2;
		control = AVKON_BUTTON
			{
			flags = KAknButtonTextInsideFrame;
			states =
				{
				AVKON_BUTTON_STATE
					{
					txt = "button2";
					helptxt = "help text2";
					}
				};
			};
		},
	TBAR_CTRL
		{
		type = EAknCtToolbarExtension; // Here are we are using Toolbar Extension which contains another set of buttons
		control = AVKON_TOOLBAR_EXTENSION
			{
			flags = KAknTbExtensionTransparent;
			items =
			{
				TBAR_CTRL
				{
					type = EAknCtButton;
					id = ECommand2;
					control = AVKON_BUTTON
						{
						flags = KAknButtonTextInsideFrame;
						states =
							{
							AVKON_BUTTON_STATE
								{
								txt = "b2";
								helptxt = "help text2";
								}
							};
						};
				},
				TBAR_CTRL
				{
					type = EAknCtButton;
					id = ECommand2;
					control = AVKON_BUTTON
						{
						flags = KAknButtonTextInsideFrame;
						states =
							{
							AVKON_BUTTON_STATE
								{
								txt = "b2";
								helptxt = "help text2";
								}
							};
						};
				},
				TBAR_CTRL
				{
					type = EAknCtButton;
					id = ECommand2;
					control = AVKON_BUTTON
						{
						flags = KAknButtonTextInsideFrame;
						states =
							{
							AVKON_BUTTON_STATE
								{
								txt = "b2";
								helptxt = "help text2";
								}
							};
						};
				},
				TBAR_CTRL
				{
					type = EAknCtButton;
					id = ECommand2;
					control = AVKON_BUTTON
						{
						flags = KAknButtonTextInsideFrame;
						states =
							{
							AVKON_BUTTON_STATE
								{
								txt = "b2";
								helptxt = "help text2";
								}
							};
						};
 
	                         }
			};
			};
		}
	};
}

ToolbarAppUi.cpp

• Here we are handling commands of toolbar items.
• We should make Toolbar extension invisible when we perform any action on the items which are on Toolbar extension.

//From MAknToolbarObserver
void CToolbarAppUi::OfferToolbarEventL(TInt aCommand)
{
    //Check this condition for toolbar extension visibility and hide it when receiving events from item in it
    if(CurrentFixedToolbar()->ToolbarExtension()->IsShown())
        CurrentFixedToolbar()->ToolbarExtension()->SetShown(EFalse);
    HandleCommandL(aCommand);
}

Limitations of Toolbar API

• Maximum three items can be placed on Toolbar, including Toolbar extension.
• In Toolbar Extension, maximum 12 items can be placed.
• This limitation is comfromted with User Interface experience.

Useful funtions

CAknToolbar

• AddItemL()
• RemoveItemL()
• SetToolbarVisibility()
• IsShown()
• DisableToolbarL()
• IsToolbarDisabled()

CAknToolbarExtension

• AddItemL()
• RemoveItemL()
• IsShown()
• SetShown()

MAknToolbarObserver

• DynInitToolbarL()
• OfferToolbarEventL()

Keywords

Headers

• #include <AknToolbarObserver.h>
• #include <AknToolbar.h>

Classes

• CAknToolbar
• MAknToolbarObserver

Libraries

• eikcoctl.lib

Example Application

• Toolbar.zip

Related links

• A tour to the S60 Touch UI components
• Working with LongTapDetector API - S60 Touch UI
• Working with Stylus Pop-up Menu API - S60 Touch UI
• Working with Tactile Feedback Client API - S60 Touch UI
• Working with Adaptive Search feature - S60 Touch UI
• Working with ChoiceList API - S60 Touch UI
• Working with Generic Button API - S60 Touch UI
• Working with SingleStyleTreeList with Hierarchical Lists API - S60 Touch UI
• Working with SingleColumnStyleTreeList with Hierarchical Lists API - S60 Touch UI

Reference list

• S60 5th edition SDK help
• S60 5th Edition C++ Developer's Library v1.0