/*
* 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