1 /*

     2 * Copyright (c) 2006, 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:  Abstract base class for all tree items.

    15 *

    16 */

    17 

    18 

    19 #ifndef C_AKNTREEITEM_H

    20 #define C_AKNTREEITEM_H

    21 

    22 

    23 #include <e32base.h>

    24 #include <akntreelistconstants.h>

    25 

    26 class CAknTreeNode;

    27 class CAknTreeLeaf;

    28 class CAknTree;

    29 class CWindowGc;

    30 class TAknWindowComponentLayout;

    31 struct TPointerEvent; // w32std.h

    32 

    33 

    34 /**

    35  *  Abstract base class for all tree items.

    36  *

    37  *  @lib aknhlist.lib

    38  *  @since S60 v3.2

    39  */

    40 NONSHARABLE_CLASS( CAknTreeItem ) : public CBase

    41     {

    42 

    43 public:

    44 

    45     /**

    46      * Destructor.

    47      */

    48     virtual ~CAknTreeItem();

    49 

    50     /**

    51      * Returns the type of the item. Each concrete class derived from this

    52      * class must provide implementation for this method that returns the

    53      * constant defining the type of the concrete item class.

    54      * 

    55      * @return Item type.

    56      */

    57     virtual TInt Type() const = 0;

    58 

    59     /**

    60      * Returns a pointer to the item's parent node.

    61      *

    62      * @return Parent node. @c NULL, if the parent node has not been set.

    63      */

    64     CAknTreeNode* Parent();

    65 

    66     /**

    67      * Returns a pointer to the items parent node.

    68      *

    69      * @return Parent node. @c NULL, if the parent node has not been set.

    70      */

    71     const CAknTreeNode* Parent() const;

    72 

    73     /**

    74      * Sets the items parent node.

    75      *

    76      * @param aParent Parent node.

    77      */

    78     void SetParent( CAknTreeNode* aParent );

    79 

    80     /**

    81      * Returns a pointer to the root of the tree.

    82      *

    83      * @return Pointer to the root of the tree. @c NULL, if the the parent

    84      *      chain to root node is broken.

    85      */

    86     virtual CAknTree* Root() const;

    87 

    88     /**

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

    90      * number of parents in the items parent chain.

    91      *

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

    93      */

    94     TInt Level() const;

    95 

    96     /**

    97      * Return pointer to leaf object. Returned value is @c NULL, if the item

    98      * is not derived from @c CAknTreeLeaf.

    99      *

   100      * @return @c CAknTreeLeaf pointer, if the item is a leaf.

   101      */

   102     virtual CAknTreeLeaf* Leaf();

   103 

   104     /**

   105      * Return pointer to leaf object. Returned value is @c NULL, if the item

   106      * is not derived from @c CAknTreeLeaf.

   107      *

   108      * @return @c CAknTreeLeaf pointer, if the item is a leaf.

   109      */

   110     virtual const CAknTreeLeaf* Leaf() const;

   111 

   112     /**

   113      * Return pointer to node object. Returned value is @c NULL, if the item

   114      * is not derived from @c CAknTreeNode.

   115      *

   116      * @return @c CAknTreeNode pointer, if the item is a node.

   117      */

   118     virtual CAknTreeNode* Node();

   119 

   120     /**

   121      * Return pointer to node object. Returned value is @c NULL, if the item

   122      * is not derived from @c CAknTreeNode.

   123      *

   124      * @return @c CAknTreeNode pointer, if the item is a node.

   125      */

   126     virtual const CAknTreeNode* Node() const;

   127 

   128     /**

   129      * Checks whether the item is a leaf.

   130      *

   131      * @return @c ETrue, if the item is a leaf.

   132      */

   133     TBool IsLeaf() const;

   134 

   135     /**

   136      * Checks whether the item is a node.

   137      *

   138      * @return @c ETrue, if the item is a node.

   139      */

   140     TBool IsNode() const;

   141 

   142     /**

   143      * Checks whether the item is marked.

   144      *

   145      * Proper implementations for this pure virtual function are provided by

   146      * @c CAknTreeLeaf and @c CAknTreeNode classes.

   147      *

   148      * @return @c ETrue, if the item is marked.

   149      */

   150     virtual TBool IsMarked() const = 0;

   151 

   152     /**

   153      * Sets the item marked or unmarked.

   154      *

   155      * Proper implementations for this pure virtual function are provided by

   156      * @c CAknTreeLeaf and @c CAknTreeNode classes.

   157      *

   158      * @param aMarked @c ETrue to set item marked, @c EFalse to unmarked.

   159      */

   160     virtual void SetMarked( TBool aMarked ) = 0;

   161 

   162     /**

   163      * Checks whether item is markable.

   164      *

   165      * Proper implementations for this pure virtual function are provided by

   166      * @c CAknTreeLeaf and @c CAknTreeNode classes.

   167      *

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

   169      */

   170     virtual TBool IsMarkable() const = 0;

   171 

   172     /**

   173      * Enables or disables marking changes for the item.

   174      *

   175      * Proper implementations for this pure virtual function are provided by

   176      * @c CAknTreeLeaf and @c CAknTreeNode classes.

   177      *

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

   179      */

   180     virtual void SetMarkable( TBool aMarkable ) = 0;

   181 

   182     /**

   183      * Checks whether the item is persistent.

   184      *

   185      * Proper implementations for this pure virtual function are provided by

   186      * @c CAknTreeLeaf and @c CAknTreeNode classes.

   187      *

   188      * @return @c ETrue, if the item is persistent.

   189      */

   190     virtual TBool IsPersistent() const = 0;

   191 

   192     /**

   193      * Sets whether the item is persistent.

   194      *

   195      * Proper implementations for this pure virtual function are provided by

   196      * @c CAknTreeLeaf and @c CAknTreeNode classes.

   197      *

   198      * @param aPersistent @c ETrue to set item persistent, @c EFalse to set

   199      *      it non-persistent.

   200      */

   201     virtual void SetPersistent( TBool aPersistent ) = 0;

   202 

   203     /**

   204      * Checks whether the item has any persistent descendants. Implementations

   205      * for this method are provided by @c CAknTreeLeaf and @c CAknTreeNode

   206      * classes.

   207      *

   208      * @return @c ETrue, if the item has persistent descendants.

   209      */

   210     virtual TBool HasPersistentDescendants() const = 0;

   211 

   212     /**

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

   214      * node is being collapsed. Items that have been set marked or persistent,

   215      * or contain marked or persistent descendants cannot be removed from the

   216      * tree automatically on collapse events. Implementations for this method

   217      * are provided by @c CAknTreeLeaf and @c CAknTreeNode classes.

   218      * 

   219      * @return @c ETrue, if the item can be removed from the tree.

   220      */

   221     virtual TBool IsRemovableFromCollapsedNode() const = 0;

   222 

   223     /**

   224      * Returns the minimum size required to display the item completely in the

   225      * view with the current layout.

   226      *

   227      * @return Minimum size.

   228      */

   229     virtual TSize MinimumSize() const;

   230 

   231     /**

   232      * Draws the item. This is a pure virtual function that should be

   233      * implemented by each item specialisation.

   234      *

   235      * This method is called by hierarchical list framework to draw the item

   236      * to specified graphics context, whenever the changes in hierarchical

   237      * list's view require it. In addition to the graphic context, the item

   238      * receives a rectangle aItemRect that specifes the size and position of

   239      * the item, a rectangle aRect that specifies the graphics context area

   240      * that needs to be redraw. The co-ordinates of the rect should be used

   241      * when drawing the required part of the item.

   242      *

   243      * When this method is called for the item, the framework has already drawn

   244      * the background and possible highlight for the item, so it not necessary,

   245      * and not even recommended, to draw every pixel in the specifed rect.

   246      *

   247      * Notes:

   248      *

   249      * Due to the nature of hierarchical list, the size and position of the

   250      * item are most likely different each time the item is drawn, so in order

   251      * to avoid unnecessary memory consumption, they should not be stored in

   252      * the items.

   253      *

   254      * @param aGc The graphic context in which the item should draw itself.

   255      *

   256      * @param aItemRect A rectangle defining the size and position of the item.

   257      *

   258      * @param aRect A rectangle specifying the part of the item's rectangle

   259      *      that needs to be redrawn.

   260      *

   261      * @param aFocused @c ETrue, if the item is currently focused, that is, it

   262      *      has highlight in the list view and should be drawn accordingly.

   263      */

   264     virtual void Draw( CWindowGc& aGc, const TRect& aItemRect,

   265         const TRect& aRect, TBool aFocused ) const = 0;

   266 

   267     /**

   268      * Handles pointer events. Default implementation does nothing.

   269      *

   270      * @param aPointerEvent Pointer event.

   271      *

   272      * @param aItemRect A rectangle defining the size and position of the item.

   273      */

   274     virtual void HandlePointerEventL( const TPointerEvent& aPointerEvent,

   275         const TRect& aItemRect );

   276 

   277     /**

   278      * Static function for comparing two tree items.

   279      *

   280      * Note: Either one of the items must already be inserted to the tree for

   281      * the comparison function to work properly.

   282      *

   283      * @param aFirst First item.

   284      *

   285      * @param aSecond Second item.

   286      *

   287      * @return Positive, if the first item is greater than the second item;

   288      *      negative, if the first item is less than the second item;

   289      *      and zero, if the items are equal.

   290      */

   291     static TInt Compare( const CAknTreeItem& aFirst,

   292         const CAknTreeItem& aSecond );

   293 

   294 protected:

   295 

   296     /**

   297      * Default C++ constructor.

   298      */

   299     CAknTreeItem();

   300 

   301     /**

   302      * Utility function for acquiring a rectangle for layout component based

   303      * on the component's parent rectangle and layout data.

   304      *

   305      * @param aParent Rectangle of parent layout component.

   306      *

   307      * @param aComponentLayout Layout for required component.

   308      *

   309      * @return Rectangle for required component.

   310      */

   311     TRect RectFromLayout( const TRect& aParent,

   312         const TAknWindowComponentLayout& aComponentLayout ) const;

   313 

   314 private: // data

   315 

   316     /**

   317      * Pointer to parent node.

   318      * Not own.

   319      */

   320     CAknTreeNode* iParent;

   321 

   322     };

   323 

   324 

   325 #endif // C_AKNTREEITEM_H