1 /*

     2 * Copyright (c) 2002-2005 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:  Class definitions for XCFW Tree

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CXCFWTREE_H

    21 #define CXCFWTREE_H

    22 

    23 //  INCLUDES

    24 #include <s32std.h>

    25 //#include <gecoobjectbase.h>

    26 #include "xcfwnodeinterface.h"

    27 

    28 // FORWARD DECLARATIONS

    29 class CGECOObjectBase;

    30 class CXCFWNode;

    31 

    32 

    33 // DATA TYPES

    34 typedef RPointerArray<MXCFWNode> RNodeArray;

    35 typedef RPointerArray<CXCFWNode> RInternalNodeArray;

    36 

    37 // CLASS DECLARATION

    38 /**

    39 *  XCFW Tree interface

    40 *  Provides access to tree functions

    41 *

    42 *  @lib XCFW.lib

    43 *  @since Series 60 3.1

    44 */

    45 class MXCFWTree

    46     {

    47     public:

    48     /**

    49     * Adds new node to content tree. Returns reference to added node. 

    50     * Three overloads are provided to allow use without parent when creating 

    51     * root, or use without insertbefore reference to allow adding nodes as 

    52     * last child of the given parent.

    53     * aData ownership is transferred at the beginning of the method!

    54     * @since Series60 3.1

    55     * @param aData The CXCFWObjectParser (derived) object to be added to tree

    56     * @param aParent Parent node for the added node

    57     * @param aInsertBefore Reference node - new node will be inserted before 

    58     *  this node in the siblings of given parent.

    59     * @return pointer to newly added node

    60     */

    61     virtual MXCFWNode* AddNodeL( CGECOObjectBase* aData, MXCFWNode* aParent, 

    62         MXCFWNode* aInsertBefore ) = 0;

    63     virtual MXCFWNode* AddNodeL( CGECOObjectBase* aData, 

    64         MXCFWNode* aParent ) = 0;

    65     virtual MXCFWNode* AddNodeL( CGECOObjectBase* aData ) = 0;

    66 

    67     /**

    68     * Returns child nodes of the given parentm from tree

    69     * @since Series60 3.1

    70     * @param aParent Parent node whose child nodes will be returned

    71     * @param aNodeList Reference to array where child nodes are added

    72     */

    73     virtual void GetChildNodesL( MXCFWNode* aParent, 

    74         RNodeArray& aNodeList ) = 0;

    75     

    76     /**

    77     * Returns nodes of certain type from tree

    78     * @since Series60 3.1

    79     * @param aType Node type identifier that corresponds to a XML tag

    80     * @param aNodeList Reference to array where found nodes are added

    81     * @param aParent Parent node where the search is started from

    82     * @param aRecursive Determines if search is done recursively 

    83     *   (finds also grandchildren)

    84     */

    85     virtual void GetNodesOfTypeL( const TDesC& aType, RNodeArray& aNodeList, 

    86         MXCFWNode* aParent, TBool aRecursive ) = 0;

    87 

    88     /**

    89     * Moves a node to another position in tree

    90     * @since Series60 3.1

    91     * @param aNodeToMove Node that is to be repositioned

    92     * @param aNewParent New parent for node to be repositioned

    93     * @param aInsertBefore New node will be inserted before this node 

    94     *  among the given parents children

    95     */ 

    96     virtual void MoveNodeL( MXCFWNode* aNodeToMove, MXCFWNode* aNewParent, 

    97         MXCFWNode* aInsertBefore ) = 0;

    98     

    99     /**

   100     * Returns all tree nodes in an array of MXCFWNode pointers

   101     * NOTE: node order does not necessarily 

   102     * reflect the current order in tree, as nodes may have been moved.

   103     * @since Series60 3.1

   104     * @return Array of MXCFWNode pointers

   105     */

   106     virtual RNodeArray& Nodes() = 0;

   107     

   108     /**

   109     * Removes a node from the tree

   110     * @since Series60 3.1

   111     * @param aNodeToRemove Node to be removed from tree

   112     */

   113     virtual void RemoveNodeL( MXCFWNode* aNodeToRemove ) = 0;

   114 

   115     

   116     /**

   117     * Returns root node of the tree

   118     * @since Series60 3.1

   119     * @return Tree root

   120     */

   121     virtual MXCFWNode* Root() = 0;

   122 

   123     /**

   124     * Sets tree lock status

   125     * If tree is locked, nodes cannot be added/moved/removed

   126     * @param aLockStatus sets the lock status

   127     */

   128     virtual void SetLocked( TBool aLockStatus ) = 0;

   129 

   130     /**

   131     * Returns tree lock status

   132     * @return ETrue, if tree structure is locked

   133     */

   134     virtual TBool IsLocked() = 0;

   135 

   136     /**

   137     * Returns name of localization DTD file (by default without path)

   138     * @return name of localization DTD file, if set

   139     */

   140     virtual const TDesC& DTDName() = 0;

   141 

   142     /**

   143     * Sets localization dtd name for this content tree

   144     * This information is used when saving the tree if 

   145     * no DTD is specified in SaveL command

   146     * @param aName DTD file name (by default without path)

   147     */

   148     virtual void SetDTDNameL( const TDesC& aName ) = 0;

   149 

   150     };

   151 

   152 

   153 /**

   154 *  CXCFWTree implements MXCFWTree interface. It owns the actual tree nodes.

   155 *

   156 *  @lib XCFW.lib

   157 *  @since Series 60 3.1

   158 */

   159 class CXCFWTree : public CBase, public MXCFWTree

   160     {

   161     public:  // Constructors and destructor

   162         

   163         /**

   164         * Two-phased constructor.

   165         */

   166         IMPORT_C static CXCFWTree* NewL();

   167         

   168         /**

   169         * Destructor.

   170         */

   171         IMPORT_C virtual ~CXCFWTree();

   172 

   173     public: // Functions from base classes

   174 

   175         /**

   176         * From MXCFWTree. Adds a node to tree.

   177         * aData ownership is transferred at the beginning of the method!

   178         */

   179         IMPORT_C MXCFWNode* AddNodeL( CGECOObjectBase* aData, 

   180             MXCFWNode* aParent, MXCFWNode* aInsertBefore );

   181 

   182         /**

   183         * From MXCFWTree. Adds a node to tree.

   184         * aData ownership is transferred at the beginning of the method!

   185         */

   186         IMPORT_C MXCFWNode* AddNodeL( CGECOObjectBase* aData, 

   187             MXCFWNode* aParent );

   188 

   189         /**

   190         * From MXCFWTree. Adds a node to tree.

   191         * aData ownership is transferred at the beginning of the method!

   192         */

   193         IMPORT_C MXCFWNode* AddNodeL( CGECOObjectBase* aData );

   194 

   195         /**

   196         * From MXCFWTree. Gets list of child nodes for a parent

   197         */

   198         IMPORT_C void GetChildNodesL( MXCFWNode* aParent, 

   199             RNodeArray& aNodeList );

   200 

   201         /**

   202         * From MXCFWTree. Gets list of certain type nodes.

   203         */

   204         IMPORT_C void GetNodesOfTypeL( const TDesC& aType, 

   205             RNodeArray& aNodeList, 

   206             MXCFWNode* aParent, 

   207             TBool aRecursive );

   208 

   209         /**

   210         * From MXCFWTree. Moves a node in tree to another position.

   211         */

   212         IMPORT_C void MoveNodeL( MXCFWNode* aNodeToMove, 

   213             MXCFWNode* aNewParent, 

   214             MXCFWNode* aInsertBefore );

   215         

   216         /**

   217         * From MXCFWTree. Returns tree nodes in an MXCFWNode pointer array

   218         */

   219         IMPORT_C RNodeArray& Nodes();

   220         

   221         /**

   222         * From MXCFWTree. Removes a node from tree.

   223         */

   224         IMPORT_C void RemoveNodeL( MXCFWNode* aNodeToRemove );

   225 

   226         /**

   227         * From MXCFWTree. Returns tree root node.

   228         */

   229         IMPORT_C MXCFWNode* Root();

   230         

   231         /**

   232         * From MXCFWTree. Sets tree structure lock status

   233         */        

   234         IMPORT_C void SetLocked( TBool aLockStatus );

   235 

   236         /**

   237         * From MXCFWTree. Returns lock status

   238         */

   239         IMPORT_C TBool IsLocked();

   240         

   241         /**

   242         * From MXCFWTree. Returns default DTD name for this tree's content

   243         */

   244         const TDesC& DTDName();

   245 

   246         /**

   247         * From MXCFWTree. Sets DTD name for this tree content

   248         */

   249         void SetDTDNameL( const TDesC& aName );

   250         

   251     private:

   252 

   253         /**

   254         * C++ default constructor.

   255         */

   256         CXCFWTree();

   257 

   258         /**

   259         * By default Symbian 2nd phase constructor is private.

   260         */

   261         void ConstructL();

   262 

   263     private: // new functions 

   264     

   265         /**

   266         * Removes a tree node branch starting from given node recursively

   267         * @since Series 60 3.1

   268         * @param Node to remove (whole branch will be removed)

   269         */

   270         void RemoveNodeRecursiveL( MXCFWNode* aNode) ;

   271 

   272         /**

   273         * Removes a tree node branch starting from given node recursively

   274         * @since Series 60 3.1

   275         * @param Node to remove (whole branch will be removed)

   276         */

   277         void RemoveFromNodeList( MXCFWNode* aNode );

   278 

   279     private:    // Data

   280         //tree node array for client ( MXCFWNode pointer array )

   281         RInternalNodeArray      iNodeList;  

   282         //root node (owned in the node array)

   283         CXCFWNode*              iRoot;

   284         //node list for client (array of MXCFWNodes). Populated at request.

   285         RNodeArray              iNodeListForClient;

   286         //marks client node list dirty =>needs to be updated on next request.

   287         TBool                   iClientListDirty;

   288         //Lock status. If locked, no changes to tree structure are allowed

   289         TBool                   iLocked;

   290         //DTD file name related to this content (engine needs to know this)

   291         HBufC*                  iDTDName;

   292 

   293     private:

   294         friend class CXCFWEngine;

   295 

   296     

   297 

   298     };

   299 

   300 #endif      // CXCFWTREE_H   

   301             

   302 // End of File