1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Data structure class for tree list component

    15  *

    16 */

    17 

    18 

    19 #ifndef C_FSTREE_H

    20 #define C_FSTREE_H

    21 

    22 #include <e32base.h>

    23 

    24 #include "fstreelistconstants.h"

    25 #include "fstreeobserver.h"

    26 #include "fstreenode.h"

    27 #include "fstreeiterator.h"

    28 

    29 class MFsTreeNodeVisualizer;

    30 class MFsTreeItemData;

    31 class MFsTreeItemVisualizer;

    32 

    33 /**

    34  *  Data structure class for the tree list component.

    35  *  It is a specialized tree node (root of a tree), with additional methods

    36  *  useful for executing tree operation based on item ids, that are

    37  *  visible for the component user.

    38  *

    39  *

    40  *  @lib

    41  */

    42 NONSHARABLE_CLASS( CFsTree ) : private CFsTreeNode

    43     {

    44 public:

    45 

    46     /**

    47      * Two-phased constructor

    48      *

    49      * @param aObserver Reference to the tree observer object

    50      * @param aItemD Reference to the tree item data object, that is used

    51      *               to store data displayed when the list is empty

    52      * @param aItemV Reference to the node visualizer object that is used

    53      *               to display info that the list is empty

    54      *

    55      * @return Pointer to the new tree object

    56      */

    57     IMPORT_C static CFsTree* NewL( MFsTreeObserver& aObserver,

    58             MFsTreeItemData& aItemD,

    59             MFsTreeNodeVisualizer& aItemV );

    60 

    61     /**

    62      * C++ destructor

    63      */

    64     virtual ~CFsTree();

    65 

    66 public: // general tree management

    67 

    68     /**

    69      * Inserts new item as a child of parent given by Id at the given

    70      * position.

    71      *

    72      * @param aItemD Pointer to item's data

    73      * @param aItemV Pointer to item's visualizer

    74      * @param aParentId Id of parent node

    75      * @param aIndex Position of new item in the list of parent's children

    76      *               (if omitted, the item is inserted as last child)

    77      *

    78      * @return Id of the inserted item

    79      *

    80      * @panic EFsListPanicParentIdNotFound The specified parent id was not

    81      *                                      found

    82      * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's

    83      *                                      number of children

    84      */

    85     TFsTreeItemId InsertItemL( MFsTreeItemData& aItemD,

    86             MFsTreeItemVisualizer& aItemV,

    87             const TFsTreeItemId aParentId,

    88             const TInt aIndex = KFsTreeChildIndexLast );

    89 

    90     /**

    91      * Inserts new node as a child of parent given by Id at the given

    92      * position.

    93      *

    94      * @param aItemD Pointer to node's data

    95      * @param aItemV Pointer to node's visualizer

    96      * @param aParentId Id of parent node

    97      * @param aIndex Position of new node in the list of parent's children

    98      *               (if omitted, the node is inserted as last)

    99      *

   100      * @return Id of the inserted node

   101      *

   102      * @panic EFsListPanicParentIdNotFound The specified parent id was not

   103      *                                      found

   104      * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's

   105      *                                      number of children

   106      */

   107     TFsTreeItemId InsertNodeL( MFsTreeItemData& aItemD,

   108             MFsTreeNodeVisualizer& aItemV,

   109             const TFsTreeItemId aParentId,

   110             const TInt aIndex = KFsTreeChildIndexLast );

   111 

   112     /**

   113      * Removes the item with given Id from the list. If aItemId is a node all

   114      * its children will be removed as well.

   115      *

   116      * @param aItemId Id of the item to be removed

   117      *

   118      * @return Returns ETrue if operation was succeded, EFalse otherwise

   119      *

   120      * @panic EFsListPanicInvalidItemId The specified item id was not found

   121      *                                  in the tree.

   122      */

   123     TBool RemoveL( const TFsTreeItemId aItem );

   124 

   125     /**

   126      * Moves the specified item to the specified target node. The constant

   127      * @c KFsTreeRootID can be used as the ID of target node, when moving

   128      * the item to the top-most level of the tree.

   129      *

   130      * @param aItemId ID of the item to be moved.

   131      * @param aTargetNodeId ID of the node, where the item is to be moved.

   132      * @param aIndex Index in the target node's children array where item

   133      *               should be placed.

   134      *

   135      * @return Returns ETrue if operation was succeded, EFalse otherwise

   136      *

   137      * @panic EFsListPanicInvalidItemId Specified item id was not found

   138      *                                  in the tree.

   139      * @panic EFsListPanicInvalidItemType Specified target node is not a node.

   140      */

   141     TBool MoveL( const TFsTreeItemId aItemId,

   142             const TFsTreeItemId aTargetNodeId,

   143             const TInt aIndex = KFsTreeChildIndexLast );

   144 

   145     /**

   146      * Function returns the number of elements in the tree.

   147      *

   148      * @return Number of elements in the tree.

   149      */

   150     TUint Count() const;

   151 

   152     /**

   153      * Function checks whether an item with a given id exists in the tree.

   154      *

   155      * @param aItemId Id of an item to look for

   156      *

   157      * @return ETrue if an item with a given id exists in the tree.

   158      */

   159     TBool Contains( const TFsTreeItemId aItemId ) const;

   160 

   161     /**

   162      * Creates an iterator object set to point at the specified node in

   163      * the tree.

   164      *

   165      * @param aNodeId Id of the node that the iterator will initially point

   166      *                at. If omitted, root id is passed.

   167      *

   168      * @return Iterator object, pointing to the node with given id.

   169      *

   170      * @panic EFsListPanicInvalidItemId Specified item id was not found

   171      *                                  in the tree.

   172      */

   173     TFsTreeIterator Iterator(const TFsTreeItemId aNodeId = KFsTreeRootID,

   174             const TFsTreeItemId aCurrentItemId = KFsTreeRootID,

   175             const TUint aFlags = KFsTreeIteratorNullFlag );

   176 

   177     /**

   178      * Checks whether the item with specified id is a node.

   179      *

   180      * @param aItemId Id of an item to check.

   181      *

   182      * @return ETrue if the item is a node, EFalse otherwise.

   183      *

   184      * @panic EFsListPanicInvalidItemId Specified item id was not found

   185      *                                  in the tree.

   186      */

   187     TBool IsNode( const TFsTreeItemId aItemId ) const;

   188 

   189     /**

   190      * Gets the number of children of the given node.

   191      *

   192      * @param aNodeId Id of the node.

   193      *

   194      * @return Number of node's children.

   195      *

   196      * @panic EFsListPanicInvalidItemId The specified item id was not found

   197      *                                  in the list.

   198      * @panic EFsListPanicInvalidItemType Item id was passed instead of the

   199      *                                    node id.

   200      */

   201     TUint CountChildren( const TFsTreeItemId aNodeId ) const;

   202 

   203     /**

   204      * Gets recursively the number of all children under the given node.

   205      * @param aNodeId Id of the node.

   206      * @return Number of node's children.

   207      */

   208     TUint CountChildrenRecursively( const TFsTreeItemId aNodeId ) const;

   209 

   210     /**

   211      * Gets the id of a child of the specified node with the position given.

   212      *

   213      * @param aNodeId Id of a node.

   214      * @param aIndex Index of the child.

   215      *

   216      * @return Id of a child.

   217      *

   218      * @panic EFsListPanicInvalidItemId The specified item id was not found in

   219      *                  the list.

   220      * @panic EFsListPanicInvalidItemType Item id was passed instead of the

   221      *                  node id.

   222      * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's

   223      *                                    number of children.

   224      */

   225     TFsTreeItemId Child( const TFsTreeItemId aNodeId,

   226             const TUint aIndex ) const;

   227 

   228     /**

   229      * Returns the index of a child for a given parent.

   230      *

   231      * @param aNodeId Id of a node.

   232      * @param aItemId Id of a child.

   233      *

   234      * @return Index of a child.

   235      */

   236     TInt ChildIndex( const TFsTreeItemId aNodeId,

   237             const TFsTreeItemId aItemId ) const;

   238 

   239     /**

   240      * Gets a pointer to the node visualizer.

   241      *

   242      * @param aNodeId Id of the node.

   243      *

   244      * @return Pointer to the item visualizer.

   245      *

   246      * @panic EFsListPanicInvalidItemId The specified item id was not found

   247      *                                  in the list.

   248      * @panic EFsListPanicInvalidItemType Item id was passed instead of the

   249      *                  node id.

   250      */

   251     MFsTreeNodeVisualizer* NodeVisualizer(const TFsTreeItemId aNodeId) const;

   252 

   253     /**

   254      * Sets the reference to the node visualizer.

   255      *

   256      * @param aVisualizer Reference to the new node's visualizer

   257      * @param aNodeId Id of the node

   258      *

   259      * @panic EFsListLeaveInvalidItemId The specified item id was not found

   260      *                                  in the list.

   261      * @panic EFsListPanicInvalidItemType Item id was passed instead of the

   262      *                          node id.

   263      */

   264     void SetNodeVisualizer( MFsTreeItemVisualizer& aVisualizer,

   265             const TFsTreeItemId aNodeId );

   266 

   267     /**

   268      * Gets the parent's id for the specified item. If KFsTreeRootID is passed

   269      * then KFsTreeNoneID is returned.

   270      *

   271      * @param aItemId Id of an item.

   272      *

   273      * @return Id of item's parent.

   274      *

   275      * @panic EFsListPanicInvalidItemId The specified item id was not found

   276      *                                  in the list.

   277      */

   278     TFsTreeItemId Parent( const TFsTreeItemId aItemId ) const;

   279 

   280     /**

   281      * Gets a reference to the item visualizer.

   282      *

   283      * @param aItemId Id of the item.

   284      *

   285      * @return Reference to the item visualizer.

   286      *

   287      * @panic EFsListPanicInvalidItemId The specified item id was not found

   288      *                                  in the list.

   289      */

   290     MFsTreeItemVisualizer* ItemVisualizer(const TFsTreeItemId aItemId) const;

   291 

   292     /**

   293      * Gets a reference to the item/node data.

   294      *

   295      * @param aItemId Id of the item/node.

   296      *

   297      * @return Reference to the item/node data.

   298      *

   299      * @panic EFsListPanicInvalidItemId The specified item id was not found

   300      *                                  in the list.

   301      */

   302     MFsTreeItemData& ItemData( const TFsTreeItemId aItemId ) const;

   303 

   304     /**

   305      * Sets a reference to the item visualizer.

   306      *

   307      * @param aVisualizer Reference to the new item's visualizer.

   308      * @param aItemId Id of the item.

   309      *

   310      * @panic EFsListPanicInvalidItemId The specified item id was not found

   311      *                                  in the list.

   312      */

   313     void SetItemVisualizer( MFsTreeItemVisualizer& aVisualizer,

   314             const TFsTreeItemId aItemId );

   315 

   316     /**

   317      * Sets the reference to the item/node data.

   318      *

   319      * @param aData Reference to the item/node data.

   320      * @param aItemId Id of the item/node.

   321      *

   322      * @panic EFsListPanicInvalidItemId The specified item id was not found

   323      *                                  in the list.

   324      */

   325     void SetItemData( MFsTreeItemData& aData, const TFsTreeItemId aItemId );

   326 

   327     /**

   328      * Returns the ID assigned for the specified tree item.

   329      *

   330      * @param aItem An item which id will be returned.

   331      *

   332      * @return Id of the specified item.

   333      */

   334     TFsTreeItemId Id( const CFsTreeItem* aItem ) const;

   335 

   336     /**

   337      * Returns the level of the item in the tree. The returned value matches

   338      * the number of parents in the items parent chain.

   339      *

   340      * @param aItemId Id of the item for which the level should be returned.

   341      *

   342      * @return The level of the item in the tree.

   343      *

   344      * @panic EFsListPanicInvalidItemId The specified item id was not found

   345      *                                  in the list.

   346      */

   347     TUint Level( const TFsTreeItemId aItemId ) const;

   348 

   349 private: // internal methods for operating on the tree

   350 

   351     /**

   352      * Retrieves the specified item from the tree structure.

   353      *

   354      * @param aItemId ID of the item to be retrieved.

   355      *

   356      * @return The retrieved tree item. NULL if the item is not in the tree.

   357      *

   358      * @panic EFsListPanicInvalidItemId The specified item id was not found

   359      *                                  in the list.

   360      */

   361     CFsTreeItem* Item( const TFsTreeItemId aItemId ) const;

   362 

   363     /**

   364      * Retrieves the specified node from the tree structure.

   365      *

   366      * @param aNodeId ID of the node to be retrieved.

   367      *

   368      * @return The retrieved tree node. NULL if the node is not in the tree or

   369      *         it is not a node, but item.

   370      *

   371      * @panic EFsListPanicInvalidItemId The specified item id was not found

   372      *                                  in the list.

   373      * @panic EFsListPanicInvalidItemType Item id was passed instead of the

   374      *                              node id.

   375      */

   376     CFsTreeNode* Node( const TFsTreeItemId aItemId ) const;

   377 

   378     /**

   379      * Notifies the tree observer about an event in the tree.

   380      *

   381      * @param aEvent Tree event.

   382      * @param aItemId    Id of an element associated with the event.

   383      */

   384     void NotifyObserverL( const MFsTreeObserver::TFsTreeEvent aEvent,

   385             const MFsTreeObserver::TFsTreeEventParams& aParams );

   386 

   387     /**

   388      * Inserts given item into given parent at specified positon.

   389      *

   390      * @param aItem Item to be inserted.

   391      * @param aParent A node into which given item should be inserted.

   392      * @param aIndex An index at which given item should be inserted.If omited

   393      *               then item is placed as the last child.

   394      *

   395      * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's

   396      *                                    number of children

   397      */

   398     TFsTreeItemId InsertL( CFsTreeItem* aItem,

   399                           CFsTreeNode* aParent,

   400                           TInt aIndex = KFsTreeChildIndexLast );

   401 

   402 private:

   403 

   404     /**

   405      * C++ constructor

   406      */

   407     CFsTree( MFsTreeObserver& aObserver,

   408              MFsTreeItemData& aItemD,

   409              MFsTreeNodeVisualizer& aItemV );

   410 

   411     /**

   412      * Second phase constructor

   413      */

   414     void ConstructL( );

   415 

   416 private: //member data

   417 

   418     /**

   419      * A observer for the tree.

   420      */

   421     MFsTreeObserver& iTreeObserver;

   422 

   423     /**

   424      * Pointer array containin pointers to all tree items.

   425      * Not owned.

   426      */

   427     RFsTreeItemList iItems;

   428     };

   429 

   430 #endif  // C_FSTREE_H

   431