Overview

Hierarchical Lists API is used to present data in a hierarchical list using text and graphics. It is new component being offered by S60 Touch UI family. In this article we will learn how to create Single Style Tree List using Hierarchical List API.

What is Hierarchical Lists API

• It is used for presenting row data in more manageable hierarchical list using text and graphics.
• There are generally three types of lists provided:
  • A general-purpose hierarchical tree list
  • A single-column style list
  • A single-style tree
• To observe the list items in your application, use the MAknTreeListObserver observer interface.

Implementing SingleStyleTreeList component

HierarchicalListsAppView.h

• We will inherit our class from MAknTreeListObserver interface and implement its pure virtual method HandleTreeListEvent() to receive and handle events for SingleStyleTreeList.
• Declare object of CAknSingleStyleTreeList and use it to set observer for this class and handle events on SingleStyleTreeList.

...
...
#include <aknsinglestyletreelist.h>
#include <akntreelist.h>
 
// CLASS DECLARATION
class CHierarchicalListsAppView : public CCoeControl, public MAknTreeListObserver
	{
		.....
		.....
		//From MAknTreeListObserver
		virtual void HandleTreeListEvent( CAknTreeList& aList, TAknTreeItemID aItem, TEvent aEvent );
 
		//For SingleStyleTreeList
		void CreateHierarchicalSingleStyleListL();
		void AddNodeL();
		void AddLeafL();
		void DeleteNodeL();
		void DeleteLeafL();
		void DeleteTreeL();
 
		//From CCoeControl
		TInt CountComponentControls() const;
		CCoeControl* ComponentControl(TInt aIndex) const;
		.....
	private:
		CAknSingleStyleTreeList* iSingleStyleTreeList;
		....
	};

HierarchicalListsAppView.cpp

• Call to create Single Style Tree List function from ConstructL() as shown below.

// -----------------------------------------------------------------------------
// CHierarchicalListsAppView::ConstructL()
// Symbian 2nd phase constructor can leave.
// -----------------------------------------------------------------------------
//
void CHierarchicalListsAppView::ConstructL(const TRect& aRect)
	{
	// Create a window for this application view
	CreateWindowL();
 
	CreateHierarchicalSingleStyleListL(); //We will create our Single Style Tree List in this function
	....
	....
 
	// Set the windows size
	SetRect(aRect);
 
	// Activate the window, which makes it ready to be drawn
	ActivateL();
	}

• Create Single Style Tree List and fill the default items.
• Set "this" as an observer for SingleStyleTreeList and eventually we will receive callbacks in HandleTreeListEvent()

void CHierarchicalListsAppView::CreateHierarchicalSingleStyleListL()
	{
		iSingleStyleTreeList = CAknSingleStyleTreeList::NewL();
		iSingleStyleTreeList->SetContainerWindowL(*this);
		iSingleStyleTreeList->SetRect(Rect());
		iSingleStyleTreeList->MakeVisible(ETrue);
		iSingleStyleTreeList->ActivateL();
 
		//Setting this class as an observer to receive events for tree list
		iSingleStyleTreeList->AddObserverL(this);
 
		// Flags used while adding the items on Single Style Tree List.
		const TInt KPersistent = CAknSingleStyleTreeList::EPersistent;
		const TInt KExpanded = CAknSingleStyleTreeList::EExpanded;
 
		// Creating first parent node on the root level
		_LIT( KNodeText1, "Parent folder" );
		TAknTreeItemID parentNode1 = iSingleStyleTreeList->AddNodeL( KAknTreeIIDRoot,KNodeText1, KPersistent | KExpanded, ETrue );
 
/* begin by chen
		// Setting icon for the first leaf in first parent node
		iSingleStyleTreeList->SetIcon( leaf1, CAknSingleStyleTreeList::ELeaf, id1, EFalse );
end by chen */
// begin by chen
		iSingleStyleTreeList->SetIcon( leaf1, CAknSingleStyleTreeList::EHighlightedLeaf, id1, EFalse);
		iSingleStyleTreeList->SetFocus(ETrue);
// end by chen
													AknIconUtils::AvkonIconFileName(), 
													EMbmAvkonQgn_prop_nrtyp_video,
													EMbmAvkonQgn_prop_nrtyp_video_mask, 
													EAspectRatioPreserved );
 
		// Creating leaves for first parent node
		_LIT( KLeafText1, "Leaf with Icon!!!" );
		TAknTreeItemID leaf1 = iSingleStyleTreeList->AddLeafL( parentNode1, KLeafText1,KPersistent, ETrue );		
		_LIT( KLeafText2, "Leaf item2" );
		TAknTreeItemID leaf2 = iSingleStyleTreeList->AddLeafL( parentNode1, KLeafText2,KPersistent, ETrue );
		_LIT( KLeafText3, "Leaf item3" );
		TAknTreeItemID leaf3 = iSingleStyleTreeList->AddLeafL( parentNode1, KLeafText3,KPersistent, ETrue );
 
		// Setting icon for the first leaf in first parent node
		iSingleStyleTreeList->SetIcon( leaf1, CAknSingleStyleTreeList::ELeaf, id1, EFalse );
 
 
		// Creating second parent node on the root level and creating its leaves
		_LIT( KNodeText2, "Parent folder" );
		TAknTreeItemID parentNode2 = iSingleStyleTreeList->AddNodeL( KAknTreeIIDRoot,KNodeText2, KPersistent | KExpanded, ETrue );
		_LIT( KLeafText4, "Leaf item4" );
		TAknTreeItemID leaf4 = iSingleStyleTreeList->AddLeafL( parentNode2, KLeafText4,KPersistent, ETrue );		
		_LIT( KLeafText5, "Leaf item5" );
		TAknTreeItemID leaf5 = iSingleStyleTreeList->AddLeafL( parentNode2, KLeafText5,KPersistent, ETrue );
 
	}

• We will handle callback events on Single Style Tree List control as shown below in the HandleTreeListEvent

void CHierarchicalListsAppView::HandleTreeListEvent( CAknTreeList& aList, TAknTreeItemID aItem, TEvent aEvent )
	{
		//Process list items on appropriate events
	}

• Definition for the following functions to return SingleStyleTreeList control.

TInt CHierarchicalListsAppView::CountComponentControls() const
{
	return 1; // return number of controls inside this container
}
 
CCoeControl* CHierarchicalListsAppView::ComponentControl(TInt aIndex) const
{
	switch ( aIndex )
    {
		case 0:
			return iSingleStyleTreeList;
		default:
			return NULL;
    }
}

• Make sure to delete iSingleStyleTreeList in the destructor of the class.

// -----------------------------------------------------------------------------
// CHierarchicalListsAppView::~CHierarchicalListsAppView()
// Destructor.
// -----------------------------------------------------------------------------
//
CHierarchicalListsAppView::~CHierarchicalListsAppView()
{
	....
	....
	if(iSingleStyleTreeList)
	{
		delete iSingleStyleTreeList;
		iSingleStyleTreeList = NULL;
	}
}

Adding node to the list

void CHierarchicalListsAppView::AddNodeL()
	{
		// Add expanded node to the topmost level of the list.
		_LIT( KNewNodeText, "New Node" );
		TAknTreeItemID parentNode1 = iSingleStyleTreeList->AddNodeL( KAknTreeIIDRoot,KNewNodeText, KPersistent | KExpanded, ETrue );
	}

Deleting focused node from the list

void CHierarchicalListsAppView::DeleteNodeL()
	{
		TAknTreeItemID focusedItem = iSingleStyleTreeList->FocusedItem();
		if(iSingleStyleTreeList->IsNode(focusedItem))
		{
			iSingleStyleTreeList->RemoveItem(focusedItem,ETrue);
		}
	}

Adding leaf to the focused node

void CHierarchicalListsAppView::AddLeafL()
	{
		TAknTreeItemID focusedItem = iSingleStyleTreeList->FocusedItem();
		if(iSingleStyleTreeList->IsNode(focusedItem))
		{
			_LIT( KNewLeafText, "New Leaf" );
			TAknTreeItemID leaf1 = iSingleStyleTreeList->AddLeafL( focusedItem, KNewLeafText,KPersistent, ETrue );	
		}
	}

Deleting leaf from the focused node

void CHierarchicalListsAppView::DeleteLeafL()
	{
		TAknTreeItemID focusedItem = iSingleStyleTreeList->FocusedItem();
		if(iSingleStyleTreeList->IsLeaf(focusedItem))
		{
			iSingleStyleTreeList->RemoveItem(focusedItem,ETrue);	
		}		
	}

Deleting whole tree

void CHierarchicalListsAppView::DeleteTreeL()
	{
		if(! iSingleStyleTreeList->IsEmpty(KAknTreeIIDRoot))
		{
			iSingleStyleTreeList->RemoveItem(KAknTreeIIDRoot,ETrue);
		}

Useful functions

CAknSingleStyleTreeList

• AddNodeL()
• AddLeafL()
• SortL()
• SetTextL()
• SetIcon()

CAknTreeList

• RemoveItem()
• ExpandNode()
• CollapseNode()
• FocusedItem()
• AddIconL()

MAknTreeListObserver

• HandleTreeListEvent()

Keywords

Headers

• #include <aknSingleStyleTreeList.h>
• #include <akntreelist.h>

Classes

• CAknSingleStyleTreeList
• CAknTreeList
• MAknTreeListObserver

Libraries

• aknhlist.lib

Example Application

Media:HierarchicalLists.zip

Related links

• A tour to the S60 Touch UI components
• Working with Toolbar API - S60 Touch UI
• 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 Generic Button 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