1 /*

     2 * Copyright (c) 2006-2009 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:  Abstract base class for hierarchical list nodes.

    15 *

    16 */

    17 

    18 

    19 #ifndef C_AKNTREENODE_H

    20 #define C_AKNTREENODE_H

    21 

    22 

    23 #include "akntreeitem.h"

    24 

    25 

    26 /**

    27  *  Abstract base class for hierarchical list nodes.

    28  *

    29  *  The items in tree structure are divided into leaves and nodes. The

    30  *  division does not represent the dynamic states of the tree items;

    31  *  nodes are tree items that can have children, while leaves cannot.

    32  *

    33  *  @lib aknhlist.lib

    34  *  @since S60 v3.2

    35  */

    36 NONSHARABLE_CLASS( CAknTreeNode ) : public CAknTreeItem

    37     {

    38 

    39 public:

    40 

    41     /** Tree node flags. */

    42     enum TAknTreeNodeFlags

    43         {

    44         /** Node is marked. */

    45         EMarked                     = 0x01,

    46         /** Node has marked descendants. */

    47         EHasMarkedDescendants       = 0x02,

    48         /** Node is persistent. */

    49         EPersistent                 = 0x04,

    50         /** Node has persistent descendants. */

    51         EHasPersistenDescendants    = 0x08,

    52         /** Node is expanded. */

    53         EExpanded                   = 0x10,

    54         /** Node appears non-empty, even if it is empty. */

    55         ENonEmpty                   = 0x20,

    56         /** Marking change for the node is disabled. */

    57         EMarkingDisabled            = 0x40

    58         };

    59 

    60     /**

    61      * Destructor.

    62      */

    63     virtual ~CAknTreeNode();

    64 

    65     /**

    66      * Returns the number of children the node has.

    67      *

    68      * @return Number of children.

    69      */

    70     TInt ChildCount() const;

    71 

    72     /**

    73      * Returs the number of descendants the node has.

    74      *

    75      * @return Number of descendants.

    76      */

    77     TInt DescendantCount() const;

    78 

    79     /**

    80      * Returns the number of visible descendants the node has.

    81      *

    82      * @return Number of visible descendants.

    83      */

    84     TInt VisibleDescendantCount() const;

    85 

    86     /**

    87      * Returns the child item specified with the index.

    88      *

    89      * @param aIndex The index of the child.

    90      *

    91      * @return A child.

    92      */

    93     CAknTreeItem* Child( TInt aIndex ) const;

    94 

    95     /**

    96      * Return the index of the specified child. Negative if not found.

    97      *

    98      * @return The index of the specified child.

    99      */

   100     TInt Index( const CAknTreeItem* aItem ) const;

   101 

   102     /**

   103      * Adds the child to the node. This does not change the parent of the

   104      * added child, thus it has to be done separately with the

   105      * @c CAknTreeItem::SetParent() method. The child are compared

   106      * to determine the correct position of the item within the array.

   107      *

   108      * @param aItem The child item to be added to the node.

   109      *

   110      * @leave KErrNoMemory Not enough memory to add the child to the node.

   111      *

   112      * @post The ownership of the item is transferred to the parent node.

   113      */

   114     void AddChildL( CAknTreeItem* aItem );

   115 

   116     /**

   117      * Adds the child to the node at a specified position. This does not

   118      * change the parent of the added child, thus it has to be done

   119      * separately with the @c CAknTreeItem::SetParent() method.

   120      *

   121      * @param aItem The child item to be added to the node.

   122      *

   123      * @param aPosition The position of the child within the array. Z

   124      *

   125      * @leave KErrNoMemory Not enough memory to add the child to the node.

   126      *

   127      * @post The ownership of the item is transferred to the parent node.

   128      */

   129     void AddChildL( CAknTreeItem* aItem, TInt aPosition );

   130 

   131     /**

   132      * Removes the child from the node.

   133      *

   134      * @param aItem The child item to be removed from the node.

   135      *

   136      * @return @c KErrNotFound, if the specified child is not found, 

   137      *      otherwise @c KErrNone.

   138      */

   139     TInt RemoveChild( CAknTreeItem* aItem );

   140 

   141     /**

   142      * Checks whether the node is expanded.

   143      *

   144      * @return @c ETrue, if the node is expanded.

   145      */

   146     TBool IsExpanded() const;

   147 

   148     /**

   149      * Changes the state of the node to expanded.

   150      */

   151     virtual void Expand();

   152 

   153     /**

   154      * Changes the state of the node to collapsed.

   155      */

   156     virtual void Collapse();

   157 

   158     /**

   159      * Checks whether node is empty. The node is not empty, when it contains

   160      * children, or is explicitly set non-empty with @c SetNonEmpty method.

   161      *

   162      * @return @c ETrue, if the node is empty.

   163      */

   164     TBool IsEmpty() const;

   165 

   166     /**

   167      * Sets the node non-empty. When the node is set non-empty, it can have an

   168      * appearance of an non-empty node, even if it does not actually contain

   169      * any children.

   170      *

   171      * Note: Setting the node empty with this method does not remove the

   172      * contents of the node, it only removes the non-empty flag from the node.

   173      *

   174      * @param aNonEmpty @c ETrue to set node appear non-empty, @c EFalse to

   175      *      to remove the flag.

   176      */

   177     void SetNonEmpty( TBool aNonEmpty );

   178 

   179     /**

   180      * Sorts the children of this node.

   181      */

   182     void Sort();

   183 

   184 // from base class CAknTreeItem

   185 

   186     /**

   187      * From CAknTreeItem.

   188      * Returns a pointer to this node.

   189      *

   190      * @return @c CAknTreeNode pointer to this object.

   191      */

   192     CAknTreeNode* Node();

   193 

   194     /**

   195      * From CAknTreeItem.

   196      * Returns a pointer this node.

   197      *

   198      * @return @c CAknTreeNode pointer to this object. 

   199      */

   200     const CAknTreeNode* Node() const;

   201 

   202     /**

   203      * From CAknTreeItem.

   204      * Checks whether the node is marked.

   205      *

   206      * @return @c ETrue, if the node is marked.

   207      */

   208     TBool IsMarked() const;

   209 

   210     /**

   211      * From CAknTreeItem.

   212      * Sets the node marked or unmarked.

   213      *

   214      * @param aMarked @c ETrue to set node marked, @c EFalse to unmarked.

   215      */

   216     void SetMarked( TBool aMarked );

   217 

   218     /**

   219      * From CAknTreeItem.

   220      * Checks whether the node is markable.

   221      *

   222      * @return @c ETrue if marking is enabled, otherwise @c EFalse.

   223      */

   224     TBool IsMarkable() const;

   225 

   226     /**

   227      * From CAknTreeItem.

   228      * Enabled or disables the marking changes for the node. By default,

   229      * each node is set markable.

   230      *

   231      * @param aMarkable @c ETrue to enable marking, @c EFalse to disable it.

   232      */

   233     void SetMarkable( TBool aMarkable );

   234 

   235     /**

   236      * From CAknTreeItem.

   237      * Checks whether the node is persistent.

   238      *

   239      * @return @c ETrue, if the node is persistent.

   240      */

   241     TBool IsPersistent() const;

   242 

   243     /**

   244      * From CAknTreeItem.

   245      * Sets whether the node is persistent.

   246      *

   247      * @param aPersistent @c ETrue to set node persistent, @c EFalse to set

   248      *      node non-persistent.

   249      */

   250     void SetPersistent( TBool aPersistent );

   251 

   252     /**

   253      * From CAknTreeItem.

   254      * Checks whether the node has any persistent descendants.

   255      *

   256      * @return @c ETrue, if node has persistent descendants.

   257      */

   258     TBool HasPersistentDescendants() const;

   259 

   260     /**

   261      * From CAknTreeItem.

   262      * Checks whether the item can be removed from the tree when its parent

   263      * node is being collapsed.

   264      *

   265      * Nodes that have been set marked or persistent, or contain marked or

   266      * persistent descendants cannot be removed from the tree automatically

   267      * on collapse events.

   268      * 

   269      * @return @c ETrue, if the node can be removed from the tree.

   270      */

   271     TBool IsRemovableFromCollapsedNode() const;

   272 

   273 protected:

   274 

   275     /**

   276      * Default C++ constructor.

   277      */

   278     CAknTreeNode();

   279 

   280     /**

   281      * C++ constructor.

   282      *

   283      * @param aFlags Flags for the tree node. The possible flags are defined

   284      *      in the @c TAknTreeNodeFlags enumeration.

   285      */

   286     CAknTreeNode( TUint32 aFlags );

   287 

   288     /**

   289      * Returns the flags set for the node.

   290      *

   291      * @return Flags.

   292      */

   293     TUint32 Flags() const;

   294 

   295     /**

   296      * Sets flags for the node.

   297      *

   298      * @param aFlags Flags for the node. First 16 flags are reserved for use

   299      *      of @c CAknTreeNode class, but the other 16 flags can be used by

   300      *      derived classes.

   301      */

   302     void SetFlags( TUint32 aFlags );

   303 

   304 private: // data

   305 

   306     /**

   307      * Array for children of the node.

   308      * Own.

   309      */

   310     RPointerArray<CAknTreeItem> iChild;

   311 

   312     /**

   313      * Flags.

   314      */

   315     TUint32 iFlags;

   316 

   317     };

   318 

   319 

   320 #endif // C_AKNTREENODE_H