1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/cnode.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,456 @@
1.4 +/// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +/// All rights reserved.
1.6 +/// This component and the accompanying materials are made available
1.7 +/// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.8 +/// which accompanies this distribution, and is available
1.9 +/// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +///
1.11 +/// Initial Contributors:
1.12 +/// Nokia Corporation - initial contribution.
1.13 +///
1.14 +/// Contributors:
1.15 +///
1.16 +/// Description:
1.17 +/// All rights reserved.
1.18 +/// This component and the accompanying materials are made available
1.19 +/// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.20 +/// which accompanies this distribution, and is available
1.21 +/// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.22 +/// Initial Contributors:
1.23 +/// Nokia Corporation - initial contribution.
1.24 +/// Contributors:
1.25 +/// This contains the definitions of CDataDelete, CDataNoDelete, CIntAttribute, CNode, and CTypedNode.
1.26 +/// CDataNoDelete is a base class to CDataDelete and are essentially a wrapper around an HBufC16.
1.27 +/// The node owns the data that is added to it and therefore is responsible for deleting all its data,
1.28 +/// hence theses two classes allow a user to have non deletable data. Internally to the node it is also
1.29 +/// sometimes necessary to change the data into either deletable or non-deletable data api's are provided
1.30 +/// for this.
1.31 +/// CIntAttribute is wrapper around a TInt, this is provided as the nodes attribute value is a CBase* however
1.32 +/// it might be desirable to store integer's in here. Attribute value is owned by the node therefore the node is
1.33 +/// responsible for deleting it.
1.34 +/// CNode is the basis for constructing a tree. It consists of an array of child nodes, node type, a parent node,
1.35 +/// an array of attributes, and a data member. Internally the data member is defined as CDataNoDelete however
1.36 +/// to the user all the exported api's take an HBufC16*. Data is owned by the node and is destroyed by the node,
1.37 +/// However in certain circumstances this is not desirable hence the api's to make the data non-deletable. The
1.38 +/// node type is defined as a TAny* however normal usage would use the templated node - CTypedNode. The node type
1.39 +/// is used to identify groups of nodes. The attribute array is fairy simple and consists of AttributeType and
1.40 +/// AttributeValue. AttributeType can be defined by using the templated class and should be a 32bit value. AttributeValue
1.41 +/// can be any object derived from CBase and the node takes ownership therefore the node delete's it.
1.42 +/// Basic usage should be to use the templated class in order to make use of the templated types (TNodeType,TAttributeType).
1.43 +/// Create a node for example:
1.44 +/// CTypedNode<CNode*, const TDesC*> *tree = CTypedNode<CNode*, const TDesC*>::NewL(0,0);
1.45 +/// add a new child:
1.46 +/// CNODE *TestChildNode1 = tree->AppendNodeL(aTempNodeForNodeType);
1.47 +/// add some data:
1.48 +/// TestChildNode1->SetDataL(aHBufC16);
1.49 +/// add an attribute:
1.50 +/// TestChildNode1->->AddAttributeL(aTAttributeType,aCBasePointerAttributeValue);
1.51 +/// Explanation of individual api's is documented below.
1.52 +///
1.53 +
1.54 +
1.55 +
1.56 +
1.57 +#ifndef __CNODE_H__
1.58 +#define __CNODE_H__
1.59 +
1.60 +#include <e32base.h>
1.61 +#include <f32file.h>
1.62 +
1.63 +
1.64 +/**
1.65 + @file
1.66 + @publishedAll
1.67 + @released
1.68 +*/
1.69 +
1.70 +//Granularity of arrays
1.71 +const TInt KGranularity = 5;
1.72 +
1.73 +//enum of panic reasons
1.74 +enum TNodePanic
1.75 + {
1.76 + ENodeBadArgument,
1.77 + ENodeNoChildren,
1.78 + ENoData,
1.79 + EAttributeFailure
1.80 + };
1.81 +
1.82 +//node panic function
1.83 +inline void Panic(TNodePanic aPanic);
1.84 +
1.85 +//Wrapper around an HBufC16 doesn't delete data
1.86 +//##ModelId=3B666BCC0303
1.87 +class CDataNoDelete : public CBase
1.88 +/** Provides a wrapper around an HBufC16: the buffer is not deleted when the object is deleted.
1.89 +*/
1.90 + {
1.91 +public:
1.92 + //##ModelId=3B666BCC032D
1.93 + CDataNoDelete(HBufC16* aData);
1.94 + //##ModelId=3B666BCC032C
1.95 + virtual ~CDataNoDelete();
1.96 + //##ModelId=3B666BCC0324
1.97 + HBufC16* SetData(HBufC16* aData);
1.98 + //##ModelId=3B666BCC0322
1.99 + virtual void ResetDataPointer(HBufC16* aData);
1.100 + //##ModelId=3B666BCC0321
1.101 + HBufC16* Data();
1.102 +
1.103 +protected:
1.104 + /** The wrapped buffer. */
1.105 + //##ModelId=3B666BCC0319
1.106 + HBufC16* iData;
1.107 + };
1.108 +
1.109 +//Wrapper around an HBufC16 does delete data
1.110 +//##ModelId=3B666BCC0399
1.111 +class CDataDelete : public CDataNoDelete
1.112 +/** Provides a wrapper around an HBufC16: the buffer is deleted when the
1.113 +object is deleted.
1.114 +*/
1.115 + {
1.116 +public:
1.117 + //##ModelId=3B666BCC03B7
1.118 + CDataDelete(HBufC16* aData);
1.119 + //##ModelId=3B666BCC03B0
1.120 + virtual ~CDataDelete();
1.121 + //##ModelId=3B666BCC03AE
1.122 + virtual void ResetDataPointer(HBufC16* aData);
1.123 + };
1.124 +
1.125 +//Wrapper around an HBufC16 does delete data (FileName)
1.126 +// After Removing referenced File
1.127 +//##ModelId=3B666BC7026F
1.128 +class CFileDataDelete : public CDataNoDelete
1.129 +/** Provides a wrapper around a filename: the referenced file is deleted when the object is deleted.
1.130 +*/
1.131 + {
1.132 +public:
1.133 + //##ModelId=3B666BC7028F
1.134 + CFileDataDelete(HBufC16* aData);
1.135 + //##ModelId=3B666BC7028E
1.136 + virtual ~CFileDataDelete();
1.137 + //##ModelId=3B666BC70285
1.138 + virtual void ResetDataPointer(HBufC16* aData);
1.139 +private:
1.140 + //##ModelId=3B666BC70284
1.141 + void RemoveFile();
1.142 + };
1.143 +
1.144 +//Wrapper around a TInt used for attribute values in order to allow the node to call a dtor
1.145 +//##ModelId=3B666BC6023E
1.146 +class CIntAttribute : public CBase
1.147 +/** Provides an object wrapper around a TInt value. */
1.148 + {
1.149 +public:
1.150 + //##ModelId=3B666BC6025B
1.151 + inline CIntAttribute(TInt aInteger);
1.152 + //##ModelId=3B666BC6025A
1.153 + inline TInt Int() const;
1.154 +private:
1.155 + //##ModelId=3B666BC60264
1.156 + CIntAttribute();
1.157 + //##ModelId=3B666BC60253
1.158 + TInt iInteger;
1.159 + };
1.160 +
1.161 +//
1.162 +// Node class
1.163 +// Normal usage would be to use CTypedNode in order to use specific templated types
1.164 +//
1.165 +
1.166 +//##ModelId=3B666BCD02D2
1.167 +class CNode : public CBase
1.168 + {
1.169 +public:
1.170 + //##ModelId=3B666BCE0139
1.171 + IMPORT_C ~CNode();
1.172 +
1.173 + //NewL parameters aType to indentify the type of node, CNode* to set the parent of this node
1.174 + //##ModelId=3B666BCE0125
1.175 + IMPORT_C static CNode* NewL(TAny* aType,CNode* aParent);
1.176 +
1.177 + //Deletes a child node which is passed in as a parameter
1.178 + //##ModelId=3B666BCE011C
1.179 + IMPORT_C void DeleteChildNode(CNode* aNode);
1.180 +
1.181 + //Deletes all the child nodes haging of this node
1.182 + //##ModelId=3B666BCE011B
1.183 + IMPORT_C void DeleteAllChildNodes();
1.184 +
1.185 + //Creates a new node and adds it to the childlist, reference to new node is returned. Can leave if it can't allocate memory for a new node
1.186 + //Type of node is the parameter
1.187 + //##ModelId=3B666BCE0108
1.188 + IMPORT_C CNode& AppendNodeL(TAny* aType = 0);
1.189 +
1.190 + //Appends a node which is passed in as a parameter to this node, so its added to the childlist
1.191 + //##ModelId=3B666BCE00FD
1.192 + IMPORT_C void AppendNodeToThisNodeL(CNode* aNode);
1.193 +
1.194 + //Sets the data in the node to the parameter that is passed in. It's deletable and the node will delete it in dtor
1.195 + //Push aDataNowNodeOwns onto the CleanupStack before calling then pop off on return
1.196 + //##ModelId=3B666BCE00F3
1.197 + IMPORT_C void SetDataL(HBufC16* aDataNowNodeOwns);
1.198 +
1.199 + //returns the data stored in the node, which is returned as an HBufC16*
1.200 + //##ModelId=3B666BCE00EB
1.201 + IMPORT_C HBufC16* Data() const;
1.202 +
1.203 + //WARNING this function can leave as it deletes the wrapper object and then creates
1.204 + //a new non deletable wrapper object and sets the data pointer inside the new object
1.205 + //IF THIS LEAVES YOU WILL LOSE YOUR DATA
1.206 + //##ModelId=3B666BCE00EA
1.207 + IMPORT_C void SetDataNoDeleteL();
1.208 +
1.209 + //WARNING this function can leave as it deletes the wrapper object and then creates
1.210 + //a new deletable wrapper object then sets the pointer in the new object
1.211 + //##ModelId=3B666BCE00E9
1.212 + IMPORT_C void ClearSetDataNoDeleteL();
1.213 +
1.214 + // Sets the data in the node to the FileName parameter that is passed in.
1.215 + // It's deletable and the node will delete it, and the file it refers to in dtor
1.216 + // Push aDataLocationNowNodeOwns onto the CleanupStack before calling then pop off on return
1.217 + //##ModelId=3B666BCE00DF
1.218 + IMPORT_C void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns);
1.219 +
1.220 + //Resets the data pointer to point to aData parameter will delete the data that is owned by the node
1.221 + //##ModelId=3B666BCE00D5
1.222 + IMPORT_C void ResetDataPointer(HBufC16* aData);
1.223 +
1.224 + //returns a reference to the absolute root of the tree
1.225 + //##ModelId=3B666BCE00CB
1.226 + IMPORT_C const CNode& Root() const;
1.227 +
1.228 + //returns a child node which is stored in the array of children. The child node is accessed by the index that is the parameter.
1.229 + //##ModelId=3B666BCE00C1
1.230 + IMPORT_C CNode* Child(TInt aByIndex) const;
1.231 +
1.232 + //Returns either the first child of this node if the parameter is NULL. Or it returns the next chld in the array after
1.233 + //the child passed in as a parameter
1.234 + //##ModelId=3B666BCE00AE
1.235 + IMPORT_C CNode* NextChild(const CNode* aNode = NULL) const;
1.236 +
1.237 + //returns the previous child to the child passed in as a parameter. The node parameter is a reference because its the child previous
1.238 + //to the node passed in which obviously must exist
1.239 + //##ModelId=3B666BCE00A4
1.240 + IMPORT_C CNode* PrevChild(const CNode& aNode) const;
1.241 +
1.242 + //Returns the parent of this node
1.243 + //##ModelId=3B666BCE00A3
1.244 + IMPORT_C CNode* Parent() const;
1.245 +
1.246 + //WARNING this function can leave as it calls AppendNodeToThisNode. The aParent parameter is the node to which you would like to make
1.247 + //the parent of 'this' node.
1.248 + //It removes itself from the childlist of it's current parent
1.249 + //##ModelId=3B666BCE0099
1.250 + IMPORT_C void ReparentL(CNode* aParent);
1.251 +
1.252 + //Returns the next sibling which means in effect that it asks for the next child of its parent.
1.253 + //Sibling means brother or sister.
1.254 + //##ModelId=3B666BCE0090
1.255 + IMPORT_C CNode* NextSibling() const;
1.256 +
1.257 + //Returns the previous sibling which means in effect that it asks for the previous child of its parent.
1.258 + //Sibling means brother or sister.
1.259 + //##ModelId=3B666BCE008F
1.260 + IMPORT_C CNode* PrevSibling() const;
1.261 +
1.262 + //returns the number of children that this node has
1.263 + //##ModelId=3B666BCE0085
1.264 + IMPORT_C TInt NumberImmediateChildren() const;
1.265 +
1.266 + //Deletes the attribute of which is of aAttributeType (the parameter)
1.267 + //WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper
1.268 + //##ModelId=3B666BCE007C
1.269 + IMPORT_C void DeleteAttribute(TAny* aAttributeType);
1.270 +
1.271 + //Deletes all the attributes of this node
1.272 + //WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper
1.273 + //##ModelId=3B666BCE007B
1.274 + IMPORT_C void DeleteAllAttributes();
1.275 +
1.276 + //remove an attribute without deleting it, this is done by simply setting the attributeValue pointer to NULL
1.277 + //WARNING you are now responsiblefor the destruction of this attribute value
1.278 + //##ModelId=3B666BCE0071
1.279 + IMPORT_C void RemoveAttributeNoDelete(TAny* aAttributeType);
1.280 +
1.281 + // Returns the number of attributes that this node has
1.282 + //##ModelId=3B666BCE0067
1.283 + IMPORT_C TInt AttributeCount() const;
1.284 +
1.285 + //Returns the type of attribute (AttributeType) at a given index...NOT the attributeValue
1.286 + //##ModelId=3B666BCE005D
1.287 + IMPORT_C TAny* AttributeTypeByIndex(TInt aIndex) const;
1.288 +
1.289 + //Returns the value of an attribute (AttributeValue) at a given index...NOT the attributeType
1.290 + //##ModelId=3B666BCE003F
1.291 + IMPORT_C CBase* AttributeByIndex(TInt aIndex) const;
1.292 + //##ModelId=3B666BCE0049
1.293 + IMPORT_C CBase* AttributeByIndex(TInt aIndex,TAny*& aType) const;
1.294 +
1.295 + //Adds an attribute, parameters are the type of attribute and its value
1.296 + //WARNING node takes ownership of aAttributeValue
1.297 + ////Push aAttributeValue onto the CleanupStack before calling then pop off on return
1.298 + //##ModelId=3B666BCE002B
1.299 + IMPORT_C void AddAttributeL(TAny* AttributeType, CBase* aAttributeValue);
1.300 +
1.301 + //Adds data to the node and also adds an attribute, parameters are the Data to be added, the type of attribute and its value
1.302 + //WARNING node takes ownership of aData and aAttributeValue
1.303 + ////Push aAttributeValue and aData onto the CleanupStack before calling then pop off on return
1.304 + //##ModelId=3B666BCE000D
1.305 + IMPORT_C void AddDataAndAttributeL(HBufC16 *aData, TAny* AttributeType, CBase* aAttributeValue);
1.306 +
1.307 + //Returns an attribute value for the given AttributeType(the parameter)
1.308 + //##ModelId=3B666BCE0003
1.309 + IMPORT_C CBase* Attribute(TAny* AttributeType) const;
1.310 +
1.311 + //Returns TRUE if the attribute of the given type exists
1.312 + //##ModelId=3B666BCD03E1
1.313 + IMPORT_C TBool AttributeExists(TAny* aAttributeType) const;
1.314 +
1.315 + //Returns the node type
1.316 + //##ModelId=3B666BCD03D7
1.317 + IMPORT_C TAny* Type() const;
1.318 +
1.319 + //Sets the node type to be aType (the parameter)
1.320 + //##ModelId=3B666BCD03CD
1.321 + IMPORT_C void SetType(TAny* aType);
1.322 +
1.323 +
1.324 +protected:
1.325 + //ctor
1.326 + //##ModelId=3B666BCD03B9
1.327 + CNode(TAny* aType, CNode* aParent);
1.328 +
1.329 + //internal finds a child which is passed in as a parameter
1.330 + //##ModelId=3B666BCD03AF
1.331 + TInt FindChild(const CNode* aNode) const;
1.332 +
1.333 + //##ModelId=3B666BCD03A7
1.334 + HBufC16* SetupDeletableOrNonDeleteableDataLC();
1.335 + //##ModelId=3B666BCD03A6
1.336 + void AdjustBasePointers();
1.337 +private:
1.338 + // Reserved for future expansion
1.339 + //##ModelId=3B666BCD039B
1.340 + virtual void Reserved1();
1.341 + //##ModelId=3B666BCD03A5
1.342 + virtual void Reserved1() const;
1.343 +
1.344 +protected:
1.345 + //the Type of Node
1.346 + //##ModelId=3B666BCD0392
1.347 + TAny* iType;
1.348 +
1.349 + //This Nodes parent
1.350 + //##ModelId=3B666BCD037E
1.351 + CNode *iParent;
1.352 +
1.353 + // stores attribute type and value. iTypes must be Flat array
1.354 + //##ModelId=3B666BCD0372
1.355 + CArrayPtrFlat<CBase> iValues;
1.356 + //##ModelId=3B666BCD034C
1.357 + CArrayPtrFlat<TAny> iTypes;
1.358 +
1.359 + //##ModelId=3B666BCD0324
1.360 + TInt32* iTypesBasePtr;
1.361 + //##ModelId=3B666BCD0310
1.362 + CDataNoDelete* iDataValue;
1.363 +//
1.364 + //An array of child nodes
1.365 + //##ModelId=3B666BCD02FC
1.366 + CArrayPtr<CNode> *iChildList;
1.367 +private:
1.368 + //##ModelId=3B666BCD02DF
1.369 + TAny* iReserved; // Reserved for future expansion
1.370 + };
1.371 +
1.372 +
1.373 +//CTypedNode is derived from CNode and is a thin template. TNodeType you should define as a 32 bit value
1.374 +//TAttributeType should be defined as a 32 bit value
1.375 +//FOR EXPLANATION OF API'S SEE ABOVE
1.376 +//##ModelId=3B666BCC01A4
1.377 +template <class TNodeType, class TAttributeType>
1.378 +class CTypedNode : public CNode
1.379 +/** Template class for a node in a node tree.
1.380 +
1.381 +The node type is set to the template parameter TNodeType and the attribute type to
1.382 +TAttributeType. These parameters should be pointers to the type required to store
1.383 +the type value: e.g. for a string, a const TDesC*.
1.384 +
1.385 +The class is thin template over CNode. */
1.386 + {
1.387 +public:
1.388 + //##ModelId=3B666BCC024A
1.389 + inline static CTypedNode* NewL(TNodeType aType,CNode* aParent);
1.390 + //##ModelId=3B666BCC0248
1.391 + inline void DeleteChildNode(CNode* aNode);
1.392 + //##ModelId=3B666BCC0247
1.393 + inline void DeleteAllChildNodes();
1.394 + //##ModelId=3B666BCC0245
1.395 + inline CTypedNode<TNodeType,TAttributeType>& AppendNodeL(TNodeType aType);
1.396 + //##ModelId=3B666BCC023B
1.397 + inline void AppendNodeToThisNodeL(CNode* aNode);
1.398 + //##ModelId=3B666BCC0228
1.399 + inline void SetDataL(HBufC16* aDataNowNodeOwns);
1.400 + //##ModelId=3B666BCC0227
1.401 + inline void SetDataNoDeleteL();
1.402 + //##ModelId=3B666BCC0221
1.403 + inline void ClearSetDataNoDeleteL();
1.404 + //##ModelId=3B666BCC021F
1.405 + inline void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns);
1.406 + //##ModelId=3B666BCC021D
1.407 + inline void ResetDataPointer(HBufC16* aData);
1.408 + //##ModelId=3B666BCC0215
1.409 + inline HBufC16* Data() const;
1.410 + //##ModelId=3B666BCC0214
1.411 + inline const CTypedNode& Root() const;
1.412 + //##ModelId=3B666BCC020B
1.413 + inline CTypedNode* Child(TInt aByIndex) const;
1.414 + //##ModelId=3B666BCC0209
1.415 + inline CTypedNode* NextChild(const CNode* aNode = NULL) const;
1.416 + //##ModelId=3B666BCC0201
1.417 + inline CTypedNode* PrevChild( const CNode& aNode) const;
1.418 + //##ModelId=3B666BCC0200
1.419 + inline CTypedNode* Parent() const;
1.420 + //##ModelId=3B666BCC01FE
1.421 + inline void ReparentL(CNode* aParent);
1.422 + //##ModelId=3B666BCC01F5
1.423 + inline CTypedNode* NextSibling() const;
1.424 + //##ModelId=3B666BCC01F4
1.425 + inline CTypedNode* PrevSibling() const;
1.426 + //##ModelId=3B666BCC01EE
1.427 + inline TInt NumberImmediateChildren() const;
1.428 + //##ModelId=3B666BCC01EC
1.429 + inline void DeleteAttribute(TAttributeType aAttributeType);
1.430 + //##ModelId=3B666BCC01EB
1.431 + inline void DeleteAllAttributes();
1.432 + //##ModelId=3B666BCC01E5
1.433 + inline void RemoveAttributeNoDelete(TAttributeType aAttributeType);
1.434 + //##ModelId=3B666BCC01E4
1.435 + inline TInt AttributeCount() const; // Returns the number of attributes
1.436 + //##ModelId=3B666BCC01E2
1.437 + inline TAttributeType AttributeTypeByIndex(TInt aIndex) const;
1.438 + //##ModelId=3B666BCC01DC
1.439 + inline CBase* AttributeByIndex(TInt aIndex) const;
1.440 + //##ModelId=3B666BCC01DE
1.441 + inline CBase* AttributeByIndex(TInt aIndex,TAttributeType& aType) const;
1.442 + //##ModelId=3B666BCC01D9
1.443 + inline void AddAttributeL(TAttributeType aAttributeType, CBase* aAttributeValue);
1.444 + //##ModelId=3B666BCC01D0
1.445 + inline void AddDataAndAttributeL(HBufC16 *aData, TAttributeType aAttributeType, CBase* aAttributeValue);
1.446 + //##ModelId=3B666BCC01CE
1.447 + inline CBase* Attribute(TAttributeType aAttributeType) const;
1.448 + //##ModelId=3B666BCC01CC
1.449 + inline TBool AttributeExists(TAttributeType aAttributeType) const;
1.450 + //##ModelId=3B666BCC01C9
1.451 + inline TNodeType Type() const;
1.452 + //##ModelId=3B666BCC01C7
1.453 + inline void SetType(TNodeType aType);
1.454 +protected:
1.455 + //##ModelId=3B666BCC01C4
1.456 + CTypedNode(TNodeType aType, CNode* aParent);
1.457 + };
1.458 +#include <cnode.inl>
1.459 +#endif