CAknTreeList Class Reference

Link against: aknhlist.lib

#include <akntreelist.h>

Inherits CAknControl.

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.

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.
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.

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.
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:
Copyright © Nokia Corporation 2001-2007
Back to top