/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Abstract base class for all tree items.

*

*/

#ifndef C_AKNTREEITEM_H

#define C_AKNTREEITEM_H

#include <e32base.h>

#include <akntreelistconstants.h>

class CAknTreeNode;

class CAknTreeLeaf;

class CAknTree;

class CWindowGc;

class TAknWindowComponentLayout;

struct TPointerEvent; // w32std.h

/**

 *  Abstract base class for all tree items.

 *

 *  @lib aknhlist.lib

 *  @since S60 v3.2

 */

NONSHARABLE_CLASS( CAknTreeItem ) : public CBase

    {

public:

    /**

     * Destructor.

     */

    virtual ~CAknTreeItem();

    /**

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

     * class must provide implementation for this method that returns the

     * constant defining the type of the concrete item class.

     * 

     * @return Item type.

     */

    virtual TInt Type() const = 0;

    /**

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

     *

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

     */

    CAknTreeNode* Parent();

    /**

     * Returns a pointer to the items parent node.

     *

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

     */

    const CAknTreeNode* Parent() const;

    /**

     * Sets the items parent node.

     *

     * @param aParent Parent node.

     */

    void SetParent( CAknTreeNode* aParent );

    /**

     * Returns a pointer to the root of the tree.

     *

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

     *      chain to root node is broken.

     */

    virtual CAknTree* Root() const;

    /**

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

     * number of parents in the items parent chain.

     *

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

     */

    TInt Level() const;

    /**

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

     * is not derived from @c CAknTreeLeaf.

     *

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

     */

    virtual CAknTreeLeaf* Leaf();

    /**

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

     * is not derived from @c CAknTreeLeaf.

     *

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

     */

    virtual const CAknTreeLeaf* Leaf() const;

    /**

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

     * is not derived from @c CAknTreeNode.

     *

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

     */

    virtual CAknTreeNode* Node();

    /**

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

     * is not derived from @c CAknTreeNode.

     *

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

     */

    virtual const CAknTreeNode* Node() const;

    /**

     * Checks whether the item is a leaf.

     *

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

     */

    TBool IsLeaf() const;

    /**

     * Checks whether the item is a node.

     *

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

     */

    TBool IsNode() const;

    /**

     * Checks whether the item is marked.

     *

     * Proper implementations for this pure virtual function are provided by

     * @c CAknTreeLeaf and @c CAknTreeNode classes.

     *

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

     */

    virtual TBool IsMarked() const = 0;

    /**

     * Sets the item marked or unmarked.

     *

     * Proper implementations for this pure virtual function are provided by

     * @c CAknTreeLeaf and @c CAknTreeNode classes.

     *

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

     */

    virtual void SetMarked( TBool aMarked ) = 0;

    /**

     * Checks whether item is markable.

     *

     * Proper implementations for this pure virtual function are provided by

     * @c CAknTreeLeaf and @c CAknTreeNode classes.

     *

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

     */

    virtual TBool IsMarkable() const = 0;

    /**

     * Enables or disables marking changes for the item.

     *

     * Proper implementations for this pure virtual function are provided by

     * @c CAknTreeLeaf and @c CAknTreeNode classes.

     *

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

     */

    virtual void SetMarkable( TBool aMarkable ) = 0;

    /**

     * Checks whether the item is persistent.

     *

     * Proper implementations for this pure virtual function are provided by

     * @c CAknTreeLeaf and @c CAknTreeNode classes.

     *

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

     */

    virtual TBool IsPersistent() const = 0;

    /**

     * Sets whether the item is persistent.

     *

     * Proper implementations for this pure virtual function are provided by

     * @c CAknTreeLeaf and @c CAknTreeNode classes.

     *

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

     *      it non-persistent.

     */

    virtual void SetPersistent( TBool aPersistent ) = 0;

    /**

     * Checks whether the item has any persistent descendants. Implementations

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

     * classes.

     *

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

     */

    virtual TBool HasPersistentDescendants() const = 0;

    /**

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

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

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

     * tree automatically on collapse events. Implementations for this method

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

     * 

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

     */

    virtual TBool IsRemovableFromCollapsedNode() const = 0;

    /**

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

     * view with the current layout.

     *

     * @return Minimum size.

     */

    virtual TSize MinimumSize() const;

    /**

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

     * implemented by each item specialisation.

     *

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

     * to specified graphics context, whenever the changes in hierarchical

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

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

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

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

     * when drawing the required part of the item.

     *

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

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

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

     *

     * Notes:

     *

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

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

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

     * the items.

     *

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

     *

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

     *

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

     *      that needs to be redrawn.

     *

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

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

     */

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

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

    /**

     * Handles pointer events. Default implementation does nothing.

     *

     * @param aPointerEvent Pointer event.

     *

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

     */

    virtual void HandlePointerEventL( const TPointerEvent& aPointerEvent,

        const TRect& aItemRect );

    /**

     * Static function for comparing two tree items.

     *

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

     * the comparison function to work properly.

     *

     * @param aFirst First item.

     *

     * @param aSecond Second item.

     *

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

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

     *      and zero, if the items are equal.

     */

    static TInt Compare( const CAknTreeItem& aFirst,

        const CAknTreeItem& aSecond );

protected:

    /**

     * Default C++ constructor.

     */

    CAknTreeItem();

    /**

     * Utility function for acquiring a rectangle for layout component based

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

     *

     * @param aParent Rectangle of parent layout component.

     *

     * @param aComponentLayout Layout for required component.

     *

     * @return Rectangle for required component.

     */

    TRect RectFromLayout( const TRect& aParent,

        const TAknWindowComponentLayout& aComponentLayout ) const;

private: // data

    /**

     * Pointer to parent node.

     * Not own.

     */

    CAknTreeNode* iParent;

    };

#endif // C_AKNTREEITEM_H