CAknTreeList Class Reference

Link against: aknhlist.lib

#include <akntreelist.h>

Inherited by CAknSingleColumnStyleTreeList, and CAknSingleStyleTreeList.

Detailed Description

Abstract base class for hierarchical lists.

This class functions as a base class for hierarchical lists. It contains the APIs common to all hierarchical lists. The internal structure of the list is not exposed directly to the list clients, instead the structure can be accessed through the APIs in this class. The items in the list are referred with item IDs, which are returned to the client when the items are added to the list.

List items are divided into leaves and nodes, the difference being that nodes have expand and collapse functionality and can contain other tree items as child items, whereas leaves cannot contain other list items. Methods IsLeaf() and IsNode() can be used for checking if items belong into these groups.

The expand and collapse events, among other list events, are send to list observers through MAknTreeListObserver interface. This enables that the whole list does not have to be populated at once, as the content of each node can be added when the node is expanded. To avoid unnecessary memory consumption, the content of each node is removed from the list when the node is collapsed. However, list items can be set persistent, in which case they are not removed from nodes on collapse events.

As the hierarchical list items are list specialisation specific, the specialisations of this class have to provide APIs for constructing and adding new items to the list, and getting and setting specialisation specific properties of the list items.

All the methods that might affect the appearance of the list view have an additional aDrawNow parameter, which can be used to indicate whether the list view should be redrawn to correspond to the modified list structure. This allows consecutive calls to be made without the list view being updated between every call by setting the aDrawNow parameter to EFalse in all of the calls but the last. The normal draw methods inherited from CCoeControl can also be used to draw the updated view.

See also:: MAknTreeListObserver

Dll aknhlist.lib

Since:: S60 v3.2


Public Types
enum	TFocusBehaviour { ESaveFocus, EMoveFocusToFirstItem }
Public Member Functions
virtual	~CAknTreeList ()
	Destructor.
virtual IMPORT_C void	SetFlags (TUint32 aFlags)
	Sets the flags for the hierarchical list.
IMPORT_C TUint32	Flags () const
	Returns the flags set for the list.
IMPORT_C void	MoveItemL (TAknTreeItemID aItem, TAknTreeItemID aTargetNode, TBool aDrawNow)
	Moves an existing list item to specified target node.
IMPORT_C void	RemoveItem (TAknTreeItemID aItem, TBool aDrawNow)
	Removes an item from the hierarchical list.
IMPORT_C void	ExpandNode (TAknTreeItemID aNode, TBool aDrawNow)
	Expands a node in hierarchical list.
IMPORT_C void	CollapseNode (TAknTreeItemID aNode, TBool aDrawNow)
	Collapses a node in hierarchical list.
IMPORT_C TBool	IsExpanded (TAknTreeItemID aNode) const
	Checks whether the specified node is expanded.
IMPORT_C TAknTreeItemID	FocusedItem () const
	Gets the item ID of the focused item.
IMPORT_C void	SetFocusedItem (TAknTreeItemID aItem, TInt aIndex, TBool aDrawNow)
	Sets the focused item and its position on the list view.
IMPORT_C TRect	HighlightRect () const
	Highlight rectangle for the focused item.
IMPORT_C TInt	AddIconL (const TAknsItemID &aId, const TDesC &aFilename, TInt aBitmapId, TInt aMaskId, TScaleMode aScaleMode)
	Adds a new icon to the list to be used by all list items.
IMPORT_C TInt	AddIconL (CFbsBitmap aIcon, CFbsBitmap aMask, TBool aTransferOwnership, TScaleMode aScaleMode)
	Adds a new icon to the list.
IMPORT_C TInt	AddColorIconL (const TAknsItemID &aId, const TAknsItemID &aColorId, TInt aColorIndex, const TDesC &aFilename, TInt aBitmapId, TInt aMaskId, TRgb aDefaultColor, TScaleMode aScaleMode)
	Adds a new icon to the list to be used by all list items.
IMPORT_C void	AssignIconL (TInt aIconId, const TAknsItemID &aId, const TDesC &aFilename, TInt aBitmapId, TInt aMaskId, TScaleMode aScaleMode)
	Assigns an icon to the tree list with the specified ID.
IMPORT_C void	AssignIconL (TInt aIconId, CFbsBitmap aIcon, CFbsBitmap aMask, TBool aTransferOwnership, TScaleMode aScaleMode)
	Assigns an icon to the tree list with the specified ID.
IMPORT_C void	AssignColorIconL (TInt aIconId, const TAknsItemID &aId, const TAknsItemID &aColorId, TInt aColorIndex, const TDesC &aFilename, TInt aBitmapId, TInt aMaskId, TRgb aDefaultColor, TScaleMode aScaleMode)
	Assigns a color icon to the list with the specified ID.
IMPORT_C void	RemoveIconL (TInt aIconId)
	Removes the specified icon from the tree list.
IMPORT_C TInt	ChildCount (TAknTreeItemID aNode) const
	Returns the number of children of a hierarchical list node.
IMPORT_C TAknTreeItemID	Child (TAknTreeItemID aNode, TInt aIndex) const
	Gets the item ID of a child of a hierarcical list node.
IMPORT_C TAknTreeItemID	Parent (TAknTreeItemID aItem) const
	Returns the item ID of the parent of a hierarchical list item.
IMPORT_C TBool	Contains (TAknTreeItemID aItem) const
	Checks whether the hierarchical list contains the list item with specified item ID.
IMPORT_C TBool	IsNode (TAknTreeItemID aItem) const
	Checks whether a hierarchical list item is a node.
IMPORT_C TBool	IsLeaf (TAknTreeItemID aItem) const
	Checks whether a hierarchical list item is a leaf.
IMPORT_C TBool	IsMarked (TAknTreeItemID aItem) const
	Checks whether a hierarchical list item is marked.
IMPORT_C void	SetMarked (TAknTreeItemID aItem, TBool aMarked, TBool aDrawNow)
	Sets an item marked.
IMPORT_C void	EnableMarking (TAknTreeItemID aItem, TBool aEnable)
	Enables or disables marking of specified list item.
IMPORT_C void	GetMarkedItemsL (RArray< TAknTreeItemID > &aMarkedItems) const
	Gets all the marked items from the tree list.
IMPORT_C void	GetMarkedItemsL (TAknTreeItemID aNode, RArray< TAknTreeItemID > &aMarkedItems) const
	Gets all the marked items from the specified node.
IMPORT_C TBool	IsEmpty (TAknTreeItemID aNode) const
	Checks whether the specified node is empty.
IMPORT_C void	SetNonEmpty (TAknTreeItemID aNode, TBool aNonEmpty, TBool aDrawNow)
	Sets a node non-empty.
IMPORT_C TBool	IsPersistent (TAknTreeItemID aItem) const
	Checks if the specified item is set persistent.
IMPORT_C void	SetPersistent (TAknTreeItemID aItem, TBool aPersistent)
	Sets an item persistent.
IMPORT_C void	Sort (MAknCustomTreeOrdering *aOrdering, TBool aDrawNow)
	Sets custom ordering for the hierarchical list and sorts the list with the use of given ordering interface.
IMPORT_C void	Sort (TAknTreeItemID aNode, TBool aSortDescendants, TBool aDrawNow)
	Sorts the specified node with the use of previously set ordering interface.
IMPORT_C void	AddObserverL (MAknTreeListObserver *aObserver)
	Adds an observer for the hierarchical list.
IMPORT_C void	RemoveObserver (MAknTreeListObserver *aObserver)
	Removes an observer from the hierarchical list.
void	NotifyObservers (MAknTreeListObserver::TEvent aEvent, TAknTreeItemID aItem)
	Notifies all of the tree list observers of the specified event.
IMPORT_C TBool	TabModeFunctionIndicators () const
	Checks whether tabulator mode function indicators are enabled.
IMPORT_C void	EnableTabModeFunctionIndicatorsL (TBool aEnable)
	Changes the appearance of collapse and expand function indicators.
IMPORT_C void	SetFocusedItem (TAknTreeItemID aItem)
	Sets the focused item and its position on the list view.
IMPORT_C TInt	FocusedItemIndex () const
	Gets the index of the focused item on the screen.
IMPORT_C TInt	VisibleItemIndex (TAknTreeItemID aItem) const
	Gets the index of the item on the screen.
IMPORT_C void	Sort (MAknCustomTreeOrdering *aOrdering, TFocusBehaviour aFocusBehaviour, TBool aDrawNow)
	Sets custom ordering for the hierarchical list and sorts the list with the use of given ordering interface.
IMPORT_C void	Sort (TAknTreeItemID aNode, TFocusBehaviour aFocusBehaviour, TBool aSortDescendants, TBool aDrawNow)
	Sorts the specified node with the use of previously set ordering interface.
IMPORT_C void	SetEmptyTextL (const TDesC &aText)
	Sets text for the empty list.
TKeyResponse	OfferKeyEventL (const TKeyEvent &aKeyEvent, TEventCode aType)
	From CCoeControl.
void	MakeVisible (TBool aVisible)
	From CCoeControl.
void	SetDimmed (TBool aDimmed)
	From CCoeControl.
void	SetContainerWindowL (const CCoeControl &aContainer)
	From CCoeControl.
void	ActivateL ()
	From CCoeControl.
void	HandleResourceChange (TInt aType)
	From CCoeControl.
TCoeInputCapabilities	InputCapabilities () const
	From CCoeControl.
void	HandlePointerEventL (const TPointerEvent &aPointerEvent)
	From CCoeControl.
TInt	CountComponentControls () const
	From CCoeControl.
CCoeControl *	ComponentControl (TInt aIndex) const
	From CCoeControl.
Protected Member Functions
	CAknTreeList ()
	Constructor.
void	BaseConstructL ()
	Second phase constructor.
void	BaseConstructL (const CCoeControl &aContainer)
	Second phase constructor.
CAknTree &	Tree ()
	Reference to the tree structure.
const CAknTree &	Tree () const
	Constant reference to the tree structure.
CAknTreeListView &	View ()
	Reference to the tree list view.
const CAknTreeListView &	View () const
	Constant reference to the tree list view.
void	FocusChanged (TDrawNow aDrawNow)
	From CCoeControl.
void	SizeChanged ()
	From CCoeControl.
void	PositionChanged ()
	From CCoeControl.
TTypeUid::Ptr	MopSupplyObject (TTypeUid aId)
	From CCoeControl.

Member Enumeration Documentation

enum CAknTreeList::TFocusBehaviour

Enumerator:

ESaveFocus
EMoveFocusToFirstItem

Constructor & Destructor Documentation

virtual CAknTreeList::~CAknTreeList ( ) [virtual]

Destructor.

CAknTreeList::CAknTreeList ( ) [protected]

Constructor.

Member Function Documentation

void CAknTreeList::ActivateL

(

)

From CCoeControl.

Sets the control as ready to be drawn.

IMPORT_C TInt CAknTreeList::AddColorIconL	(	const TAknsItemID &	aId,
		const TAknsItemID &	aColorId,
		TInt	aColorIndex,
		const TDesC &	aFilename,
		TInt	aBitmapId,
		TInt	aMaskId,
		TRgb	aDefaultColor,
		TScaleMode	aScaleMode
	)

Adds a new icon to the list to be used by all list items.

The same icon can be used by multiple tree items and it is referenced by the icon ID returned by this function. The given parameters are stored in the tree list, and they are used in reconstructing the bitmaps on skin change events.

Parameters:

	aId	Item ID of the icon to be added.
	aColorId	Item ID of the color table.
	aColorIndex	Index in the color table.
	aFilename	Filename to be used to construct the item, if no matching item was found in the currently active skin.
	aBitmapId	ID of the bitmap in the file. Used only if no matching item was found in the currently active skin.
	aMaskId	ID of the mask in the file. Used only if no matching item was found in the currently active skin.
	aDefaultColor	Color RGB value to be used, if no color is found in the currently active skin.
	aScaleMode	Scale mode used when icon's bitmap is resized.

Returns:: ID assigned for the added icon.

Leave:: KErrNoMemory Not enough memory.

IMPORT_C TInt CAknTreeList::AddIconL	(	CFbsBitmap *	aIcon,
		CFbsBitmap *	aMask,
		TBool	aTransferOwnership,
		TScaleMode	aScaleMode
	)

Adds a new icon to the list.

The ownership of given bitmaps is transferred to the list only if specified with aTransferOwnership parameter. Note that icons added to the list with this method cannot be reconstructed on skin change events by the list. If necessary, previously added icons can be replaced with AssignIconL method.

Parameters:

	aIcon	Pointer to the bitmap.
	aMask	Pointer to the mask bitmap.
	aTransferOwnership	`ETrue`, if ownership of bitmaps is transferred to the list. If the method leaves, it is always on the responsibility of the client code to take care of deleting the bitmaps.
	aScaleMode	The scale mode used when the icon is resized.

Returns:: ID assigned for the added icon.

Leave:: KErrNoMemory Not enough memory.

IMPORT_C TInt CAknTreeList::AddIconL	(	const TAknsItemID &	aId,
		const TDesC &	aFilename,
		TInt	aBitmapId,
		TInt	aMaskId,
		TScaleMode	aScaleMode
	)

Adds a new icon to the list to be used by all list items.

The same icon can be used by multiple tree items and its referenced by the ID returned by this function. The given parameters are also stored in the tree list, which enables the tree list to reconstruct the bitmaps on skin change events. If this behaviour is insufficient for the client, it can always replace the existing icons by itself with AssignIconL or AssignColorIconL method.

Parameters:

	aId	Item ID of the icon to be added.
	aFilename	Filename to be used to construct the item, if no matching item was found in the currently active skin.
	aBitmapId	ID of the bitmap in the file. Used only if no matching item was found in the currently active skin.
	aMaskId	ID of the mask in the file. Used only if no matching item was found in the currently active skin.
	aScaleMode	Scale mode used when icon's bitmap is resized.

Returns:: ID assigned for the added icon.

Leave:: KErrNoMemory Not enough memory.

IMPORT_C void CAknTreeList::AddObserverL

(

MAknTreeListObserver *

aObserver

)

Adds an observer for the hierarchical list.

Notifications of the list events are sent to all observers set with this method. Observers can be removed from the list with RemoveObserver() method.

Note: Hierarchical list also sends a state changed event on every list event through the usual control observer interface that can be set with CCoeControl::SetObserver method.

Parameters:

aObserver

Implementation of the observer interface.

Postcondition:: The given interface is set as the observer of the list. The ownership of the interface is not transferred to the list.

IMPORT_C void CAknTreeList::AssignColorIconL	(	TInt	aIconId,
		const TAknsItemID &	aId,
		const TAknsItemID &	aColorId,
		TInt	aColorIndex,
		const TDesC &	aFilename,
		TInt	aBitmapId,
		TInt	aMaskId,
		TRgb	aDefaultColor,
		TScaleMode	aScaleMode
	)

Assigns a color icon to the list with the specified ID.

If an icon with specified ID already exists in the list, the existing icon is replaced with the new one. The given parameters are stored in the tree list, and they are used in reconstructing the bitmaps on skin change events.

Parameters:

	aIconId	Icon ID assigned for the icon.
	aId	Item ID of the icon to be added.
	aColorId	Item ID of the color table.
	aColorIndex	Index in the color table.
	aFilename	Filename to be used to construct the item, if no matching item was found in the currently active skin.
	aBitmapId	ID of the bitmap in the file. Used only if no matching item was found in the currently active skin.
	aMaskId	ID of the mask in the file. Used only if no matching item was found in the currently active skin.
	aDefaultColor	Color RGB value to be used, if no color is found in the currently active skin.
	aScaleMode	Scale mode used when icon's bitmap is resized.

Leave:: KErrNoMemory Not enough memory.

Leave:: KErrArgument Specified icon ID is out of allowed range.

IMPORT_C void CAknTreeList::AssignIconL	(	TInt	aIconId,
		CFbsBitmap *	aIcon,
		CFbsBitmap *	aMask,
		TBool	aTransferOwnership,
		TScaleMode	aScaleMode
	)

Assigns an icon to the tree list with the specified ID.

If an icon with specified ID already exists in the list, the existing icon is replaced with the new one. The ownership of bitmaps is transferred to the list only if so specifed with aTransferOnwership parameter. Note that icons added with this method cannot be reconstructed on skin change events by list.

Parameters:

	aIconId	Icon ID assigned for the icon.
	aIcon	Pointer to the bitmap.
	aMask	Pointer to the mask bitmap.
	aTransferOwnership	`ETrue`, if ownership of bitmaps is transferred to the list. If the method leaves, it is always on the responsibility of the client code to take care of deleting the bitmaps.
	aScaleMode	Scale mode used when icon's bitmap is resized.

Leave:: KErrNoMemory Not enough memory.

Leave:: KErrArgument Specified icon ID is out of allowed range.

IMPORT_C void CAknTreeList::AssignIconL	(	TInt	aIconId,
		const TAknsItemID &	aId,
		const TDesC &	aFilename,
		TInt	aBitmapId,
		TInt	aMaskId,
		TScaleMode	aScaleMode
	)

Assigns an icon to the tree list with the specified ID.

Parameters:

	aIconId	Icon ID assigned for the icon.
	aId	Item ID of the icon to be added.
	aFilename	Filename to be used to construct the item, if no matching item was found in the currently active skin.
	aBitmapId	ID of the bitmap in the file. Used only if no matching item was found in the currently active skin.
	aMaskId	ID of the mask in the file. Used only if no matching item was found in the currently active skin.
	aScaleMode	Scale mode used when icon's bitmap is resized.

Leave:: KErrNoMemory Not enough memory.

Leave:: KErrArgument Specified icon ID is out of allowed range.

void CAknTreeList::BaseConstructL ( const CCoeControl & aContainer ) [protected]

Second phase constructor.

Completes the construction of the base class.

Parameters:

aContainer

Container for the list.

void CAknTreeList::BaseConstructL ( ) [protected]

Second phase constructor.

Completes the construction of the base class. When this version of BaseConstructL() is used, new window is created for the list.

IMPORT_C TAknTreeItemID CAknTreeList::Child	(	TAknTreeItemID	aNode,
		TInt	aIndex
	)	const

Gets the item ID of a child of a hierarcical list node.

The specific child is specified with an index. The child count for any hierarchical list node can be get with ChildCount() method.

Parameters:

	aNode	Item ID of the node, whose child is enquiried.
	aIndex	Index of the enquiried child.

Returns:: Item ID of the specified child. Value KAknTreeIIDNone is returned, if the child with specified index does not exist.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified item is not a node.

IMPORT_C TInt CAknTreeList::ChildCount

(

TAknTreeItemID

aNode

)

const

Returns the number of children of a hierarchical list node.

This method, along with Child() method, can be used for enquiring information of the list structure. Constant KAknTreeIIDRoot can be used to get the item count on the top-most level of the list.

Parameters:

aNode

Item ID of a node.

Returns:: Number of children of specified node.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified item is not a node.

IMPORT_C void CAknTreeList::CollapseNode	(	TAknTreeItemID	aNode,
		TBool	aDrawNow
	)

Collapses a node in hierarchical list.

When a node in the hierarchical list is collapsed, either with this method, or with pointer or key event, all its content that is not set persistent is removed from the list to reduce memory consumption. The observer of the hierarchical list is nofied with the respective event. Constant KAknTreeIIDRoot can be used to collapse every node in the tree structure.

Parameters:

	aNode	Item ID of the node to be collapsed.
	aDrawNow	`ETrue` to redraw the list after the node has been collapsed, otherwise `EFalse`.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified item is not a node.

Precondition:: The specified item exists in the hierarchical list and it is a node.

Postcondition:: The specified item is collapsed and all of its children, which are not set persistent, are removed from the list.

CCoeControl* CAknTreeList::ComponentControl

(

TInt

aIndex

)

const

From CCoeControl.

Gets an indexed component of a compound control.

Parameters:

aIndex

The index of the control.

Returns:: The component control with an index of aIndex.

IMPORT_C TBool CAknTreeList::Contains

(

TAknTreeItemID

aItem

)

const

Checks whether the hierarchical list contains the list item with specified item ID.

The returned value for constant KAknTreeIIDRoot will always be ETrue, and for constant KAknTreeIIDNone EFalse.

Parameters:

aItem

Item ID.

Returns:: ETrue, if the list contains the specified item.

TInt CAknTreeList::CountComponentControls

(

)

const

From CCoeControl.

Gets the number of controls contained in a compound control.

Returns:: The number of component controls contained by this control.

IMPORT_C void CAknTreeList::EnableMarking	(	TAknTreeItemID	aItem,
		TBool	aEnable
	)

Enables or disables marking of specified list item.

By default, marking is enabled for every list item.

When marking is enabled for an item, its marking can be changed from unmarked to marked, and vice versa, with SetMarked() method, and for markable list, the marking can also change as a result of user action.

When marking is disabled, the item can still be either unmarked or marked, but the marking cannot be changed in any way, until it has been enabled again for the item.

Parameters:

	aItem	Item ID of the list item.
	aEnable	`ETrue` to enable marking, `EFalse` to disable it.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C void CAknTreeList::EnableTabModeFunctionIndicatorsL

(

TBool

aEnable

)

Changes the appearance of collapse and expand function indicators.

The appearance of default function indicators suggest that left and right arrow keys expand and collapse the focused nodes, but when the list is used with tabulators, those keys are used in changing tabulators. Alternate representation for function indicator can be set by enabling tabulator mode indicator with this method.

Parameters:

aEnable ETrue to enable tabulator mode function indicators, EFalse to use the default function indicators.

IMPORT_C void CAknTreeList::ExpandNode	(	TAknTreeItemID	aNode,
		TBool	aDrawNow
	)

Expands a node in hierarchical list.

When a node in the hierarchical list is expanded, either with this method, or with pointer or key event, the observer of the list is notified with respective event. The client of the list can then update the content of the expanded node. Constant KAknTreeIIDRoot can be used to expand every node in the tree structure.

Parameters:

	aNode	Item ID of the node to be expanded.
	aDrawNow	`ETrue` to redraw the list after the node has been expanded, otherwise `EFalse`.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified item is not a node.

Precondition:: The specified item exists in the hierarchical list and it is a node.

Postcondition:: The specified node is expanded. The updated list is drawn, when it is requested with the aDrawNow parameter.

IMPORT_C TUint32 CAknTreeList::Flags

(

)

const

Returns the flags set for the list.

Returns:: Flags.

void CAknTreeList::FocusChanged ( TDrawNow aDrawNow ) [protected]

From CCoeControl.

Handles focus change.

Parameters:

aDrawNow EDrawNow to redraw the list.

IMPORT_C TAknTreeItemID CAknTreeList::FocusedItem

(

)

const

Gets the item ID of the focused item.

Returns:: Item ID of the focused item. Value KAknTreeIIDNone is returned if no item is focused.

IMPORT_C TInt CAknTreeList::FocusedItemIndex

(

)

const

Gets the index of the focused item on the screen.

Possible values are from 0 to max. number of visible lines - 1. Value -1 is returned if no item is focused or focused item is not visible.

Returns:: index of the focused item on the screen.

IMPORT_C void CAknTreeList::GetMarkedItemsL	(	TAknTreeItemID	aNode,
		RArray< TAknTreeItemID > &	aMarkedItems
	)	const

Gets all the marked items from the specified node.

The marked items are appended to the end of the array passed as parameter.

Parameters:

	aNode	Item ID of a node from where the marked items are retrieved.
	aMarkedItems	On return, contains item IDs of marked items in the specified node.

Leave:: KErrNoMemory Appending item to the array fails.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified item is not a node.

IMPORT_C void CAknTreeList::GetMarkedItemsL

(

RArray< TAknTreeItemID > &

aMarkedItems

)

const

Gets all the marked items from the tree list.

The marked items are appended to the end of the array passed as parameter.

Parameters:

aMarkedItems

On return, contains item IDs of all marked items.

Leave:: KErrNoMemory Appending item to the array fails.

void CAknTreeList::HandlePointerEventL

(

const TPointerEvent &

aPointerEvent

)

From CCoeControl.

Handles pointer events.

Parameters:

aPointerEvent

Pointer event.

void CAknTreeList::HandleResourceChange

(

TInt

aType

)

From CCoeControl.

Handles resource changes.

Parameters:

aType

Reimplemented in CAknSingleColumnStyleTreeList.

IMPORT_C TRect CAknTreeList::HighlightRect

(

)

const

Highlight rectangle for the focused item.

The returned rectangle is screen relative and it can be used, for example, when positioning pop-up for focused item. If the focused item is not visible, the method returns an empty rectangle.

Returns:: Highlight rectangle of focused list item.

TCoeInputCapabilities CAknTreeList::InputCapabilities

(

)

const

From CCoeControl.

Gets the control's input capabilities.

Returns:: The control's input capabilities.

IMPORT_C TBool CAknTreeList::IsEmpty

(

TAknTreeItemID

aNode

)

const

Checks whether the specified node is empty.

To decrease memory consumption, the descendants of tree nodes can be removed from the hierarchical list when the node is collapsed. As the empty nodes may have different appearances in the list view, the collapsed nodes can be set to appear as non-empty with SetNonEmpty() method to indicate that nodes will have some content when expanded.

Parameters:

aNode

Item ID of checked item.

Returns:: ETrue, if the item has been set non-empty.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified target item is not a node.

IMPORT_C TBool CAknTreeList::IsExpanded

(

TAknTreeItemID

aNode

)

const

Checks whether the specified node is expanded.

Parameters:

aNode

Item ID of a node.

Returns:: ETrue if the node is expanded.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified item is not a node.

IMPORT_C TBool CAknTreeList::IsLeaf

(

TAknTreeItemID

aItem

)

const

Checks whether a hierarchical list item is a leaf.

Parameters:

aItem

Item ID of checked item.

Returns:: ETrue, if the specified item is a leaf.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C TBool CAknTreeList::IsMarked

(

TAknTreeItemID

aItem

)

const

Checks whether a hierarchical list item is marked.

Parameters:

aItem

Item ID of checked item.

Returns:: ETrue for marked item.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C TBool CAknTreeList::IsNode

(

TAknTreeItemID

aItem

)

const

Checks whether a hierarchical list item is a node.

Parameters:

aItem

Item ID of checked item.

Returns:: ETrue, if the specified item is a node.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C TBool CAknTreeList::IsPersistent

(

TAknTreeItemID

aItem

)

const

Checks if the specified item is set persistent.

If an item is set persistent, it is not removed from the list, when its parent or any of its ancestors is collapsed. This means also that a node cannot be automatically removed from the list on collapse event, if any of its descendants is set persistent.

Parameters:

aItem

Item ID.

Returns:: ETrue, if item is set persistent.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

void CAknTreeList::MakeVisible

(

TBool

aVisible

)

From CCoeControl.

Changes the visibility of the hierarchical list.

Parameters:

aVisible ETrue to make the list visible, EFalse to make it invisible.

TTypeUid::Ptr CAknTreeList::MopSupplyObject ( TTypeUid aId ) [protected]

From CCoeControl.

Retrieves an object of the same type as that encapsulated in aId.

Parameters:

aId

An encapsulated object type ID.

Returns:: Encapsulates the pointer to the object provided. Note that the encapsulated pointer may be NULL

IMPORT_C void CAknTreeList::MoveItemL	(	TAknTreeItemID	aItem,
		TAknTreeItemID	aTargetNode,
		TBool	aDrawNow
	)

Moves an existing list item to specified target node.

The moved item and the target node have to be specified with the item IDs returned when the items were added to the hierarchical list. The target node cannot be a descendant of the moved node. Otherwise, the moving would break the hierarchical structure. Constant KAknTreeIIDRoot can be used as an ID for the target node when the item is to be moved to the top-most level of the list.

Parameters:

	aItem	Item ID of the item to be moved.
	aTargetNode	ID of the node, where the item is to be moved.
	aDrawNow	`ETrue` to redraw the list after the item has been moved, otherwise `EFalse`.

Leave:: KErrArgument The specified item is the same as the target node or one of the ancestors of target node.

Leave:: KErrNoMemory Not enough memory is available for adding the specified item to the target node.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified target item is not a node.

Precondition:: The moved item and the target node exist in the list, and the target node is not a descendant of the moved item.

Postcondition:: The item is moved to the specified target node and into a such position that the children of the target node remain in sorted order. The updated list is redrawn, if it is requested with the aDrawNow parameter.

void CAknTreeList::NotifyObservers	(	MAknTreeListObserver::TEvent	aEvent,
		TAknTreeItemID	aItem
	)

Notifies all of the tree list observers of the specified event.

This method is not exported, as it is intended for internal use only.

Parameters:

	aEvent	The event to be notified.
	aItem	ID of the tree item related to the event.

TKeyResponse CAknTreeList::OfferKeyEventL	(	const TKeyEvent &	aKeyEvent,
		TEventCode	aType
	)

From CCoeControl.

Handles key events. The method will return EKeyWasNotConsumed, if the list is not focused.

Parameters:

	aKeyEvent	The key event.
	aType	The type of key event: `EEventKey`, `EEventKeyUp` or `EEventKeyDown`.

IMPORT_C TAknTreeItemID CAknTreeList::Parent

(

TAknTreeItemID

aItem

)

const

Returns the item ID of the parent of a hierarchical list item.

The constant KAknTreeIIDRoot is returned for all the items on the top-most level of the tree, and constant KaknTereIIDNone for the items that have no parent, that is, the root node.

Parameters:

aItem

Item ID of the item, whose parent is enquiried.

Returns:: Item ID of the parent node.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

void CAknTreeList::PositionChanged ( ) [protected]

From CCoeControl.

Responds to changes in the position of this control.

IMPORT_C void CAknTreeList::RemoveIconL

(

TInt

aIconId

)

Removes the specified icon from the tree list.

The specified icon cannot be any of the default tree list icon, in which case the leaves with value KErrArgument. If the specified icon is not found, the function does nothing.

Parameters:

aIconId

Icon ID of the removed icon.

Leave:: KErrArgument if specified icon is one of the default icons.

IMPORT_C void CAknTreeList::RemoveItem	(	TAknTreeItemID	aItem,
		TBool	aDrawNow
	)

Removes an item from the hierarchical list.

The item to be removed has to be specified with the ID value returned when the item was added to the hierarchical list. If the removed item is a node containing other list items, those items are removed from the list as well. Constant KAknTreeIIDRoot can be used to remove every item from the list.

Parameters:

	aItem	Item ID of the item to be removed.
	aDrawNow	`ETrue` to redraw the list after the item has been removed, othewise `EFalse`.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Precondition:: The specified item exists in the hierarchical list.

Postcondition:: The specified item and all of its descendants are removed from the list. The updated list is drawn, when it is requested with the aDrawNow parameter.

IMPORT_C void CAknTreeList::RemoveObserver

(

MAknTreeListObserver *

aObserver

)

Removes an observer from the hierarchical list.

Parameters:

aObserver

The observer interface to be removed.

void CAknTreeList::SetContainerWindowL

(

const CCoeControl &

aContainer

)

From CCoeControl.

Sets the control's containing window by copying it from aContainer.

Parameters:

aContainer

The compound control that is the container for this control.

void CAknTreeList::SetDimmed

(

TBool

aDimmed

)

From CCoeControl.

Sets whether the list is dimmed.

Parameters:

aDimmed ETrue to set list dimmed, otherwise EFalse.

IMPORT_C void CAknTreeList::SetEmptyTextL

(

const TDesC &

aText

)

Sets text for the empty list.

This text is visible if the list box has no items.

Parameters:

aText

The text for the empty list.

virtual IMPORT_C void CAknTreeList::SetFlags ( TUint32 aFlags ) [virtual]

Sets the flags for the hierarchical list.

Flags KAknTreeListLooping, KAknTreeListNoStructureLines, KAknTreeListMarqueeScrolling, KAknTreeListNoIndention, and KAknTreeListMarkable can be used to change the behaviour of the list.

Note: Specialisations may override this method in order to restrict the use of some of the flags in specialised list or to handle specialisation specific flags.

Parameters:

aFlags

Flags.

Reimplemented in CAknSingleColumnStyleTreeList, and CAknSingleStyleTreeList.

IMPORT_C void CAknTreeList::SetFocusedItem

(

TAknTreeItemID

aItem

)

Sets the focused item and its position on the list view.

When the focused item is changed, the vertical position of the view is changed as follows:

If the focused item is set on the first page, view is changed to the beginning of the list.

If the focused item is not set on the first page, view is changed so that focused item is at the lowest line on the screen.

(In this context first page means actual lines from 0 to max. number of visible lines - 1)

The horizontal position of the view is changed so that the the beginning of the focused item is visible.

Parameters:

aItem

Item ID of the item to be focused.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C void CAknTreeList::SetFocusedItem	(	TAknTreeItemID	aItem,
		TInt	aIndex,
		TBool	aDrawNow
	)

Sets the focused item and its position on the list view.

When the focused item is changed, the vertical position of the view is changed so that the position of the focused item on the view matches the given index. The horizontal position of the view is changed so that the the beginning of the focused item is visible.

Parameters:

	aItem	Item ID of the item to be focused.
	aIndex	The position of the focused item on the list view. If the index does not refer to any visible view location, that is, the index is less than zero or greater than or equal to the number of items in the view, the focused item is changed to specified item, but the position of the view is not changed.
	aDrawNow	`ETrue` to redraw the list after the focused item has been changed, otherwise `EFalse`.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C void CAknTreeList::SetMarked	(	TAknTreeItemID	aItem,
		TBool	aMarked,
		TBool	aDrawNow
	)

Sets an item marked.

If the marked item is a node, all of its descendants are also set marked.

Note that item marking can be changed with this method, even if the list itself is not set markable. Marking changes can be enabled and disabled with EnableMarking() method.

Parameters:

	aItem	Item ID of the item to be modified.
	aMarked	`ETrue` to set item marked, `EFalse` to unmarked.
	aDrawNow	`ETrue` to redraw the list after the item has been set marked, otherwise `EFalse`.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C void CAknTreeList::SetNonEmpty	(	TAknTreeItemID	aNode,
		TBool	aNonEmpty,
		TBool	aDrawNow
	)

Sets a node non-empty.

Parameters:

	aNode	Item ID of the item to be modified.
	aNonEmpty	`ETrue` to set node non-empty, `EFalse` to empty.
	aDrawNow	`ETrue` to redraw the list after the setting has been change, otherwise `EFalse`.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified target item is not a node.

IMPORT_C void CAknTreeList::SetPersistent	(	TAknTreeItemID	aItem,
		TBool	aPersistent
	)

Sets an item persistent.

If the specified item is a node, the state of all its descendants is also changed accordingly.

Parameters:

	aItem	Item ID.
	aPersistent	`ETrue` to set item persistent.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

void CAknTreeList::SizeChanged ( ) [protected]

From CCoeControl.

Responds to changes to the size and position of this control.

IMPORT_C void CAknTreeList::Sort	(	TAknTreeItemID	aNode,
		TFocusBehaviour	aFocusBehaviour,
		TBool	aSortDescendants,
		TBool	aDrawNow
	)

Sorts the specified node with the use of previously set ordering interface.

The sorting can be restricted to the specified node, or the sorting can be set to include also every descendant node of the specified node. Whole list can be sorted by giving the constant KAknTreeIIDRoot as the aNode parameter. This method has no effect, if no ordering has been set for the list.

Parameters:

	aNode	Item ID of the node that has to be sorted.
	aFocusBehaviour	Tells how focus should be handled after sorting. `ESaveFocus` saves focus in the item where it was before sorting, `EMoveFocusToFirstItem` changes view to the beginning of the list and moves focus to the first item.
	aSortDescendants	`ETrue` to sort the content of the specified node including the content of its descendant nodes, `EFalse` to sort only the child items within the specified node.
	aDrawNow	`ETrue` to redraw the list after sorting.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified item is not a node.

IMPORT_C void CAknTreeList::Sort	(	MAknCustomTreeOrdering *	aOrdering,
		TFocusBehaviour	aFocusBehaviour,
		TBool	aDrawNow
	)

Sets custom ordering for the hierarchical list and sorts the list with the use of given ordering interface.

The given interface is used until it is replaced with some other ordering.

Parameters:

	aOrdering	Custom ordering interface used in list sorting.
	aFocusBehaviour	Tells how focus should be handled after sorting. `ESaveFocus` saves focus in the item where it was before sorting, `EMoveFocusToFirstItem` changes view to the beginning of the list and moves focus to the first item.
	aDrawNow	`ETrue` to redraw the list after sorting.

IMPORT_C void CAknTreeList::Sort	(	TAknTreeItemID	aNode,
		TBool	aSortDescendants,
		TBool	aDrawNow
	)

Sorts the specified node with the use of previously set ordering interface.

Parameters:

	aNode	Item ID of the node that has to be sorted.
	aSortDescendants	`ETrue` to sort the content of the specified node including the content of its descendant nodes, `EFalse` to sort only the child items within the specified node.
	aDrawNow	`ETrue` to redraw the list after sorting.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified item is not a node.

IMPORT_C void CAknTreeList::Sort	(	MAknCustomTreeOrdering *	aOrdering,
		TBool	aDrawNow
	)

Sets custom ordering for the hierarchical list and sorts the list with the use of given ordering interface.

The given interface is used until it is replaced with some other ordering.

Note: Ownership of the interface is not transferred to the list.

Note: When custom ordering is set to the list, new items are added to the end of their parent nodes, because the interface cannot be used for determining the position for inserted item, as the client receives its identifier only after it has been inserted. Sort(TAknTreeItemID, TBool, TBool) method can be used for sorting the node with custom ordering interface after new items have been inserted in the list.

Parameters:

	aOrdering	Custom ordering interface used in list sorting.
	aDrawNow	`ETrue` to redraw the list after sorting.

IMPORT_C TBool CAknTreeList::TabModeFunctionIndicators

(

)

const

Checks whether tabulator mode function indicators are enabled.

Returns:: ETrue if tabulator mode is enabled.

const CAknTree& CAknTreeList::Tree ( ) const [protected]

Constant reference to the tree structure.

Returns:: Constant reference to tree structure.

CAknTree& CAknTreeList::Tree ( ) [protected]

Reference to the tree structure.

Returns:: Reference to tree structure.

const CAknTreeListView& CAknTreeList::View ( ) const [protected]

Constant reference to the tree list view.

Returns:: Constant reference to tree list view.

CAknTreeListView& CAknTreeList::View ( ) [protected]

Reference to the tree list view.

Returns:: Reference to tree list view.

IMPORT_C TInt CAknTreeList::VisibleItemIndex

(

TAknTreeItemID

aItem

)

const

Gets the index of the item on the screen.

Possible values are from 0 to max. number of visible lines - 1. Value -1 is returned if the requested item is not visible on the screen.

Returns:: index of the requested item.

The documentation for this class was generated from the following file:

akntreelist.h

CAknTreeList Class Reference

Detailed Description

Public Types

Public Member Functions

Protected Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation