Overview

Single Column Style Tree List is created with Hierarchical Lists API to present data in a hierarchical list using text and graphics. In this article we will learn how to create Single Column 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 grphics.
• To observe the list items in your application, use the MAknTreeListObserver observer interface.

Implementing SingleColumnStyleTreeList component

SingleColumnStyleTreeListAppView.h

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

...
...
#include <aknSingleColumnStyleTreeList.h>
#include <akntreelist.h>
 
// CLASS DECLARATION
class CSingleColumnStyleTreeListAppView : public CCoeControl, public MAknTreeListObserver
	{
		.....
		.....
		//From MAknTreeListObserver
		virtual void HandleTreeListEvent( CAknTreeList& aList, TAknTreeItemID aItem, TEvent aEvent );
 
		//For SingleColumnStyleTreeList
		void CreateHierarchicalSingleColumnStyleListL();
		void AddSubTitleL();
		void AddCoreDataRowL();
		void DeleteSubTitleL();
		void DeleteCoreDataRowL();
		void DeleteTreeL();
 
		//From CCoeControl
		TInt CountComponentControls() const;
		CCoeControl* ComponentControl(TInt aIndex) const;
		.....
	private:
		CAknSingleColumnStyleTreeList* iSingleColumnStyleTreeList;
		....
	};

SingleColumnStyleTreeListAppView.cpp

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

// -----------------------------------------------------------------------------
// CSingleColumnStyleTreeListAppView::ConstructL()
// Symbian 2nd phase constructor can leave.
// -----------------------------------------------------------------------------
//
void CSingleColumnStyleTreeListAppView::ConstructL(const TRect& aRect)
	{
	// Create a window for this application view
	CreateWindowL();
 
	CreateHierarchicalSingleColumnStyleListL(); //We will create our Single Column 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 Column Style Tree List and fill the default items.
• Set "this" as an observer for SingleColumnStyleTreeList and eventually we will receive callbacks in HandleTreeListEvent()

void CSingleColumnStyleTreeListAppView::CreateHierarchicalSingleColumnStyleListL()
{
	iSingleColumnStyleTreeList = CAknSingleColumnStyleTreeList::NewL();
	iSingleColumnStyleTreeList->SetContainerWindowL(*this);
	iSingleColumnStyleTreeList->SetRect(Rect());
	iSingleColumnStyleTreeList->MakeVisible(ETrue);
	iSingleColumnStyleTreeList->ActivateL();
 
	//Setting this class as an observer to receive events for tree list
	iSingleColumnStyleTreeList->AddObserverL(this);
 
	// Add simple data row to the topmost level of the list.
	_LIT( KDataRowText, "Simple Data" );
	TAknTreeItemID simpleDataRow = iSingleColumnStyleTreeList->AddSimpleDataRowL( KAknTreeIIDRoot, KDataRowText, KColumnStylePersistent, ETrue );
 
	// Adding first subtitle row for the parent data row
	_LIT( KSubtitleRowTextA, "First Subtitle" );
	TAknTreeItemID subtitleRowA = iSingleColumnStyleTreeList->AddSubtitleRowL( KAknTreeIIDRoot, KSubtitleRowTextA, NULL, ETrue );
 
	// Add row values for first subtitle row
	_LIT( KColumnText1, "Column1a" );
	_LIT( KColumnText2, "Column2a" );
	TAknTreeItemID coreDataRowA = iSingleColumnStyleTreeList->AddCoreDataRowL(subtitleRowA, KColumnText1, KColumnText2, KColumnStylePersistent, ETrue );
 
	// Adding second subtitle row for the parent data row
	_LIT( KSubtitleRowTextB, "Second Subtitle" );
	TAknTreeItemID subtitleRowB = iSingleColumnStyleTreeList->AddSubtitleRowL( KAknTreeIIDRoot, KSubtitleRowTextB, NULL, ETrue );
 
	// Add row values for second subtitle row
	_LIT( KColumnText3, "Column3b" );
	_LIT( KColumnText4, "Column4b" );
	TAknTreeItemID coreDataRowB = iSingleColumnStyleTreeList->AddCoreDataRowL( subtitleRowB, KColumnText3, KColumnText4, KColumnStylePersistent, ETrue );
 
	// Adding third subtitle row for the parent data row
	_LIT( KSubtitleRowTextC, "Third Subtitle" );
	TAknTreeItemID subtitleRowC = iSingleColumnStyleTreeList->AddSubtitleRowL( KAknTreeIIDRoot, KSubtitleRowTextC, NULL, ETrue );
 
	// Add row values for third subtitle row
	_LIT( KColumnText5, "Column5c" );
	_LIT( KColumnText6, "Column6c" );
	TAknTreeItemID coreDataRowC = iSingleColumnStyleTreeList->AddCoreDataRowL( subtitleRowC, KColumnText5, KColumnText6, KColumnStylePersistent, ETrue );
}

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

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

• Definition for the following functions to return SingleColumnStyleTreeList control.

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

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

// -----------------------------------------------------------------------------
// CSingleColumnStyleTreeListAppView::~CSingleColumnStyleTreeListAppView()
// Destructor.
// -----------------------------------------------------------------------------
//
CSingleColumnStyleTreeListAppView::~CSingleColumnStyleTreeListAppView()
{
	....
	....
	if(iSingleColumnStyleTreeList)
	{
		delete iSingleColumnStyleTreeList;
		iSingleColumnStyleTreeList = NULL;
	}
}

Adding Subtitle to the list

void CSingleColumnStyleTreeListAppView::AddSubTitleL()
{
    // Adding third subtitle row for the parent data row
    _LIT( KNewSubtitleRow, "New Subtitle" );
    TAknTreeItemID newSubtitleRow = iSingleColumnStyleTreeList->AddSubtitleRowL( KAknTreeIIDRoot, KNewSubtitleRow, NULL, ETrue );	
}

Deleting focused subtitle node from the list

void CSingleColumnStyleTreeListAppView::DeleteSubTitleL()
{
    TAknTreeItemID focusedItem = iSingleColumnStyleTreeList->FocusedItem();
    if(iSingleColumnStyleTreeList->IsNode(focusedItem))
        iSingleColumnStyleTreeList->RemoveItem(focusedItem,ETrue);
}

Adding Core Data Row to the focused subtitle node

void CSingleColumnStyleTreeListAppView::AddCoreDataRowL()
{
    TAknTreeItemID focusedItem = iSingleColumnStyleTreeList->FocusedItem();
    if(iSingleColumnStyleTreeList->IsNode(focusedItem))
    {
        // Add row values for third subtitle row
       _LIT( KNewColumnText1, "NewColumn1" );
       _LIT( KNewColumnText2, "NewColumn2" );
       TAknTreeItemID newCoreDataRow = iSingleColumnStyleTreeList->AddCoreDataRowL( focusedItem, KNewColumnText1, KNewColumnText2, KColumnStylePersistent, ETrue );
    }
}

Deleting core data row from the focused subtitle node

void CSingleColumnStyleTreeListAppView::DeleteCoreDataRowL()
{
    TAknTreeItemID focusedItem = iSingleColumnStyleTreeList->FocusedItem();
    if(iSingleColumnStyleTreeList->IsLeaf(focusedItem))
        iSingleColumnStyleTreeList->RemoveItem(focusedItem,ETrue);	
}

Deleting whole tree

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

Useful functions

CAknSingleColumnStyleTreeList

• AddSubtitleRowL()
• AddCoreDataRowL()
• EnableThirdColumn()
• IsThirdColumnEnabled()
• SetTextL()
• SetIcon()

CAknTreeList

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

MAknTreeListObserver

• HandleTreeListEvent()

Keywords

Headers

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

Classes

• CAknSingleColumnStyleTreeList
• CAknTreeList
• MAknTreeListObserver

Libraries

• aknhlist.lib

Example Application

• SingleColumnStyleTreeList.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 SingleStyleTreeList with Hierarchical Lists API - S60 Touch UI

Reference list

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