Working with SingleStyleTreeList with Hierarchical Lists API - S60 Touch UI

Comments

29 Sep
2009

Article Review by deepikagohil (20090929)

Hierarchical List is a type of list to represent data in a structured, systematic and tree-style manner. And it is widely used for standard representation of data. This article mainly deals with Hierarchical Lists API and shows the use of its CAknSingleStyleTreeList class to create the list in S60 5th Edition.

The article first gives a brief overview for the same and then represents the code snippests to create the list with CAknSingleStyleTreeList class. The code snippests are presented with necessary explainations and well-describing comments. Basic functions like adding nodes/ leaf, deleating nodes/ leaf/ the whole tree etc. are all covered by the given article. Some useful functions of the mentioned class are also mentioned in the ned of the article.

Apart from that, the article also provides a demostrated example to study the API in more detail. This article can be very beneficial to the developers who are intending to create a Hierarchical List in their application. It can specially benefit beginners.

---

This paper is very helpful. But I have a problem that the tree does not work well on real phone, I tested it on 5800 and n97. The folder can't expand or collapse after several clicks. I have [a topic on the discuss board][1]. Is there some thing I make wrong? --xuelanding 8 Nov 2010

Log in or Join to leave comments.

Article Metadata

---

Code Example

Source file: Media:HierarchicalLists.zip

---

Article

Created: kiran10182 (10 Nov 2008)

Last edited: hamishwillee (08 Feb 2012)

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