/*

* 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 <e32base.h>

#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