diff -r 000000000000 -r 8466d47a6819 emailuis/uicomponents/inc/fstree.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/emailuis/uicomponents/inc/fstree.h Thu Dec 17 08:39:21 2009 +0200 @@ -0,0 +1,431 @@ +/* +* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Data structure class for tree list component + * +*/ + + +#ifndef C_FSTREE_H +#define C_FSTREE_H + +#include + +#include "fstreelistconstants.h" +#include "fstreeobserver.h" +#include "fstreenode.h" +#include "fstreeiterator.h" + +class MFsTreeNodeVisualizer; +class MFsTreeItemData; +class MFsTreeItemVisualizer; + +/** + * Data structure class for the tree list component. + * It is a specialized tree node (root of a tree), with additional methods + * useful for executing tree operation based on item ids, that are + * visible for the component user. + * + * + * @lib + */ +NONSHARABLE_CLASS( CFsTree ) : private CFsTreeNode + { +public: + + /** + * Two-phased constructor + * + * @param aObserver Reference to the tree observer object + * @param aItemD Reference to the tree item data object, that is used + * to store data displayed when the list is empty + * @param aItemV Reference to the node visualizer object that is used + * to display info that the list is empty + * + * @return Pointer to the new tree object + */ + IMPORT_C static CFsTree* NewL( MFsTreeObserver& aObserver, + MFsTreeItemData& aItemD, + MFsTreeNodeVisualizer& aItemV ); + + /** + * C++ destructor + */ + virtual ~CFsTree(); + +public: // general tree management + + /** + * Inserts new item as a child of parent given by Id at the given + * position. + * + * @param aItemD Pointer to item's data + * @param aItemV Pointer to item's visualizer + * @param aParentId Id of parent node + * @param aIndex Position of new item in the list of parent's children + * (if omitted, the item is inserted as last child) + * + * @return Id of the inserted item + * + * @panic EFsListPanicParentIdNotFound The specified parent id was not + * found + * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's + * number of children + */ + TFsTreeItemId InsertItemL( MFsTreeItemData& aItemD, + MFsTreeItemVisualizer& aItemV, + const TFsTreeItemId aParentId, + const TInt aIndex = KFsTreeChildIndexLast ); + + /** + * Inserts new node as a child of parent given by Id at the given + * position. + * + * @param aItemD Pointer to node's data + * @param aItemV Pointer to node's visualizer + * @param aParentId Id of parent node + * @param aIndex Position of new node in the list of parent's children + * (if omitted, the node is inserted as last) + * + * @return Id of the inserted node + * + * @panic EFsListPanicParentIdNotFound The specified parent id was not + * found + * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's + * number of children + */ + TFsTreeItemId InsertNodeL( MFsTreeItemData& aItemD, + MFsTreeNodeVisualizer& aItemV, + const TFsTreeItemId aParentId, + const TInt aIndex = KFsTreeChildIndexLast ); + + /** + * Removes the item with given Id from the list. If aItemId is a node all + * its children will be removed as well. + * + * @param aItemId Id of the item to be removed + * + * @return Returns ETrue if operation was succeded, EFalse otherwise + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the tree. + */ + TBool RemoveL( const TFsTreeItemId aItem ); + + /** + * Moves the specified item to the specified target node. The constant + * @c KFsTreeRootID can be used as the ID of target node, when moving + * the item to the top-most level of the tree. + * + * @param aItemId ID of the item to be moved. + * @param aTargetNodeId ID of the node, where the item is to be moved. + * @param aIndex Index in the target node's children array where item + * should be placed. + * + * @return Returns ETrue if operation was succeded, EFalse otherwise + * + * @panic EFsListPanicInvalidItemId Specified item id was not found + * in the tree. + * @panic EFsListPanicInvalidItemType Specified target node is not a node. + */ + TBool MoveL( const TFsTreeItemId aItemId, + const TFsTreeItemId aTargetNodeId, + const TInt aIndex = KFsTreeChildIndexLast ); + + /** + * Function returns the number of elements in the tree. + * + * @return Number of elements in the tree. + */ + TUint Count() const; + + /** + * Function checks whether an item with a given id exists in the tree. + * + * @param aItemId Id of an item to look for + * + * @return ETrue if an item with a given id exists in the tree. + */ + TBool Contains( const TFsTreeItemId aItemId ) const; + + /** + * Creates an iterator object set to point at the specified node in + * the tree. + * + * @param aNodeId Id of the node that the iterator will initially point + * at. If omitted, root id is passed. + * + * @return Iterator object, pointing to the node with given id. + * + * @panic EFsListPanicInvalidItemId Specified item id was not found + * in the tree. + */ + TFsTreeIterator Iterator(const TFsTreeItemId aNodeId = KFsTreeRootID, + const TFsTreeItemId aCurrentItemId = KFsTreeRootID, + const TUint aFlags = KFsTreeIteratorNullFlag ); + + /** + * Checks whether the item with specified id is a node. + * + * @param aItemId Id of an item to check. + * + * @return ETrue if the item is a node, EFalse otherwise. + * + * @panic EFsListPanicInvalidItemId Specified item id was not found + * in the tree. + */ + TBool IsNode( const TFsTreeItemId aItemId ) const; + + /** + * Gets the number of children of the given node. + * + * @param aNodeId Id of the node. + * + * @return Number of node's children. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + * @panic EFsListPanicInvalidItemType Item id was passed instead of the + * node id. + */ + TUint CountChildren( const TFsTreeItemId aNodeId ) const; + + /** + * Gets recursively the number of all children under the given node. + * @param aNodeId Id of the node. + * @return Number of node's children. + */ + TUint CountChildrenRecursively( const TFsTreeItemId aNodeId ) const; + + /** + * Gets the id of a child of the specified node with the position given. + * + * @param aNodeId Id of a node. + * @param aIndex Index of the child. + * + * @return Id of a child. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found in + * the list. + * @panic EFsListPanicInvalidItemType Item id was passed instead of the + * node id. + * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's + * number of children. + */ + TFsTreeItemId Child( const TFsTreeItemId aNodeId, + const TUint aIndex ) const; + + /** + * Returns the index of a child for a given parent. + * + * @param aNodeId Id of a node. + * @param aItemId Id of a child. + * + * @return Index of a child. + */ + TInt ChildIndex( const TFsTreeItemId aNodeId, + const TFsTreeItemId aItemId ) const; + + /** + * Gets a pointer to the node visualizer. + * + * @param aNodeId Id of the node. + * + * @return Pointer to the item visualizer. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + * @panic EFsListPanicInvalidItemType Item id was passed instead of the + * node id. + */ + MFsTreeNodeVisualizer* NodeVisualizer(const TFsTreeItemId aNodeId) const; + + /** + * Sets the reference to the node visualizer. + * + * @param aVisualizer Reference to the new node's visualizer + * @param aNodeId Id of the node + * + * @panic EFsListLeaveInvalidItemId The specified item id was not found + * in the list. + * @panic EFsListPanicInvalidItemType Item id was passed instead of the + * node id. + */ + void SetNodeVisualizer( MFsTreeItemVisualizer& aVisualizer, + const TFsTreeItemId aNodeId ); + + /** + * Gets the parent's id for the specified item. If KFsTreeRootID is passed + * then KFsTreeNoneID is returned. + * + * @param aItemId Id of an item. + * + * @return Id of item's parent. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + */ + TFsTreeItemId Parent( const TFsTreeItemId aItemId ) const; + + /** + * Gets a reference to the item visualizer. + * + * @param aItemId Id of the item. + * + * @return Reference to the item visualizer. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + */ + MFsTreeItemVisualizer* ItemVisualizer(const TFsTreeItemId aItemId) const; + + /** + * Gets a reference to the item/node data. + * + * @param aItemId Id of the item/node. + * + * @return Reference to the item/node data. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + */ + MFsTreeItemData& ItemData( const TFsTreeItemId aItemId ) const; + + /** + * Sets a reference to the item visualizer. + * + * @param aVisualizer Reference to the new item's visualizer. + * @param aItemId Id of the item. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + */ + void SetItemVisualizer( MFsTreeItemVisualizer& aVisualizer, + const TFsTreeItemId aItemId ); + + /** + * Sets the reference to the item/node data. + * + * @param aData Reference to the item/node data. + * @param aItemId Id of the item/node. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + */ + void SetItemData( MFsTreeItemData& aData, const TFsTreeItemId aItemId ); + + /** + * Returns the ID assigned for the specified tree item. + * + * @param aItem An item which id will be returned. + * + * @return Id of the specified item. + */ + TFsTreeItemId Id( const CFsTreeItem* aItem ) const; + + /** + * Returns the level of the item in the tree. The returned value matches + * the number of parents in the items parent chain. + * + * @param aItemId Id of the item for which the level should be returned. + * + * @return The level of the item in the tree. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + */ + TUint Level( const TFsTreeItemId aItemId ) const; + +private: // internal methods for operating on the tree + + /** + * Retrieves the specified item from the tree structure. + * + * @param aItemId ID of the item to be retrieved. + * + * @return The retrieved tree item. NULL if the item is not in the tree. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + */ + CFsTreeItem* Item( const TFsTreeItemId aItemId ) const; + + /** + * Retrieves the specified node from the tree structure. + * + * @param aNodeId ID of the node to be retrieved. + * + * @return The retrieved tree node. NULL if the node is not in the tree or + * it is not a node, but item. + * + * @panic EFsListPanicInvalidItemId The specified item id was not found + * in the list. + * @panic EFsListPanicInvalidItemType Item id was passed instead of the + * node id. + */ + CFsTreeNode* Node( const TFsTreeItemId aItemId ) const; + + /** + * Notifies the tree observer about an event in the tree. + * + * @param aEvent Tree event. + * @param aItemId Id of an element associated with the event. + */ + void NotifyObserverL( const MFsTreeObserver::TFsTreeEvent aEvent, + const MFsTreeObserver::TFsTreeEventParams& aParams ); + + /** + * Inserts given item into given parent at specified positon. + * + * @param aItem Item to be inserted. + * @param aParent A node into which given item should be inserted. + * @param aIndex An index at which given item should be inserted.If omited + * then item is placed as the last child. + * + * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's + * number of children + */ + TFsTreeItemId InsertL( CFsTreeItem* aItem, + CFsTreeNode* aParent, + TInt aIndex = KFsTreeChildIndexLast ); + +private: + + /** + * C++ constructor + */ + CFsTree( MFsTreeObserver& aObserver, + MFsTreeItemData& aItemD, + MFsTreeNodeVisualizer& aItemV ); + + /** + * Second phase constructor + */ + void ConstructL( ); + +private: //member data + + /** + * A observer for the tree. + */ + MFsTreeObserver& iTreeObserver; + + /** + * Pointer array containin pointers to all tree items. + * Not owned. + */ + RFsTreeItemList iItems; + }; + +#endif // C_FSTREE_H +