/*

* 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 hierarchical lists.

*

*/

#ifndef C_AKNTREELIST_H

#define C_AKNTREELIST_H

#include <AknControl.h>

#include <w32std.h>

#include <akntreelistobserver.h>

#include <AknIconUtils.h> // TScaleMode

class CAknTree;

class CAknTreeListView;

class MAknCustomTreeOrdering;

class TAknsItemID;

/** Flag to indicate that hierarchical list is looping. */

const TUint32 KAknTreeListLooping = 0x0001;

/** Flag to indicate that hierarchical list structure lines are not visible. */

const TUint32 KAknTreeListNoStructureLines = 0x0002;

/** Flag to set marquee scrolling on. */

const TUint32 KAknTreeListMarqueeScrolling = 0x0004;

/** Flag to disable indention of hierarchical list items. Setting this flag

    also forces the tree structure lines invisible. */

const TUint32 KAknTreeListNoIndention = 0x0008;

/** Flag to set hierarchical list markable. The list items can always be

    marked by list client with API methods, but when list is set markable,

    it responds to specified pointer and key event by marking/unmarking

    items as required. */

const TUint32 KAknTreeListMarkable = 0x0010;

/** Flag to enalbe smiley in tree list. */

const TUint32 KAknTreeListSmiley = 0x0020;

/**

 *  Abstract base class for hierarchical lists.

 *

 *  This class functions as a base class for hierarchical lists. It contains

 *  the APIs common to all hierarchical lists. The internal structure of the

 *  list is not exposed directly to the list clients, instead the structure

 *  can be accessed through the APIs in this class. The items in the list are

 *  referred with item IDs, which are returned to the client when the items

 *  are added to the list.

 *

 *  List items are divided into leaves and nodes, the difference being that

 *  nodes have expand and collapse functionality and can contain other tree

 *  items as child items, whereas leaves cannot contain other list items.

 *  Methods @c IsLeaf() and @c IsNode() can be used for checking if items

 *  belong into these groups.

 *

 *  The expand and collapse events, among other list events, are send to list

 *  observers through @c MAknTreeListObserver interface. This enables that

 *  the whole list does not have to be populated at once, as the content of

 *  each node can be added when the node is expanded. To avoid unnecessary

 *  memory consumption, the content of each node is removed from the list

 *  when the node is collapsed. However, list items can be set persistent,

 *  in which case they are not removed from nodes on collapse events.

 *

 *  As the hierarchical list items are list specialisation specific, the

 *  specialisations of this class have to provide APIs for constructing and

 *  adding new items to the list, and getting and setting specialisation

 *  specific properties of the list items.

 *

 *  All the methods that might affect the appearance of the list view have an

 *  additional @c aDrawNow parameter, which can be used to indicate whether

 *  the list view should be redrawn to correspond to the modified list

 *  structure. This allows consecutive calls to be made without the list view

 *  being updated between every call by setting the @c aDrawNow parameter to

 *  @c EFalse in all of the calls but the last. The normal draw methods 

 *  inherited from @c CCoeControl can also be used to draw the updated view.

 *

 *  @see MAknTreeListObserver

 *

 *  @lib aknhlist.lib

 *  @since S60 v3.2

 */

NONSHARABLE_CLASS( CAknTreeList ) : public CAknControl

    {

public:

    // for focus handling after Sort

   enum TFocusBehaviour

            {

            ESaveFocus,

            EMoveFocusToFirstItem

            };

    /**

     * Destructor.

     */

    virtual ~CAknTreeList();

    /**

     * Sets the flags for the hierarchical list.

     *

     * Flags @c KAknTreeListLooping, @c KAknTreeListNoStructureLines,

     * @c KAknTreeListMarqueeScrolling, @c KAknTreeListNoIndention, and

     * @c KAknTreeListMarkable can be used to change the behaviour

     * of the list.

     *

     * Note: Specialisations may override this method in order to restrict the

     * use of some of the flags in specialised list or to handle specialisation

     * specific flags.

     *

     * @param aFlags Flags.

     */

    IMPORT_C virtual void SetFlags( TUint32 aFlags );

    /**

     * Returns the flags set for the list.

     *

     * @return Flags.

     */

    IMPORT_C TUint32 Flags() const;

    /**

     * Moves an existing list item to specified target node. The moved item

     * and the target node have to be specified with the item IDs returned

     * when the items were added to the hierarchical list. The target node

     * cannot be a descendant of the moved node. Otherwise, the moving would

     * break the hierarchical structure. Constant @c KAknTreeIIDRoot can be

     * used as an ID for the target node when the item is to be moved to the

     * top-most level of the list.

     *

     * @param aItem Item ID of the item to be moved.

     *

     * @param aTargetNode ID of the node, where the item is to be moved.

     *

     * @param aDrawNow @c ETrue to redraw the list after the item has been

     *      moved, otherwise @c EFalse.

     *

     * @leave KErrArgument The specified item is the same as the target node

     *      or one of the ancestors of target node. 

     *

     * @leave KErrNoMemory Not enough memory is available for adding the

     *      specified item to the target node.

     *

     * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

     *

     * @panic EAknHListPanicInvalidItemType Specified target item is not a node.

     *

     * @pre The moved item and the target node exist in the list, and the

     *      target node is not a descendant of the moved item.

     *

     * @post The item is moved to the specified target node and into a such

     *      position that the children of the target node remain in sorted

     *      order. The updated list is redrawn, if it is requested with the

     *      aDrawNow parameter.

     */

    IMPORT_C void MoveItemL( TAknTreeItemID aItem, TAknTreeItemID aTargetNode,

        TBool aDrawNow );

    /**

     * Removes an item from the hierarchical list. The item to be removed has

     * to be specified with the ID value returned when the item was added to

     * the hierarchical list. If the removed item is a node containing other

     * list items, those items are removed from the list as well. Constant

     * @c KAknTreeIIDRoot can be used to remove every item from the list.

     *

     * @param aItem Item ID of the item to be removed.

     *

     * @param aDrawNow @c ETrue to redraw the list after the item has been

     *      removed, othewise @c EFalse.

     *

     * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

     *

     * @pre The specified item exists in the hierarchical list.

     *

     * @post The specified item and all of its descendants are removed from

     *      the list. The updated list is drawn, when it is requested with

     *      the aDrawNow parameter.

     */

    IMPORT_C void RemoveItem( TAknTreeItemID aItem, TBool aDrawNow );

    /**

     * Expands a node in hierarchical list. When a node in the hierarchical

     * list is expanded, either with this method, or with pointer or key

     * event, the observer of the list is notified with respective event.

     * The client of the list can then update the content of the expanded

     * node. Constant @c KAknTreeIIDRoot can be used to expand every node

     * in the tree structure.

     *

     * @param aNode Item ID of the node to be expanded.

     * 

     * @param aDrawNow @c ETrue to redraw the list after the node has been

     *      expanded, otherwise @c EFalse.

     *

     * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

     *

     * @panic EAknHListPanicInvalidItemType Specified item is not a node.

     *

     * @pre The specified item exists in the hierarchical list and it is a

     *      node.

     *

     * @post The specified node is expanded. The updated list is drawn, when

     *      it is requested with the aDrawNow parameter.

     */

    IMPORT_C void ExpandNode( TAknTreeItemID aNode, TBool aDrawNow );

    /**

     * Collapses a node in hierarchical list. When a node in the hierarchical

     * list is collapsed, either with this method, or with pointer or key

     * event, all its content that is not set persistent is removed from the

     * list to reduce memory consumption. The observer of the hierarchical

     * list is nofied with the respective event. Constant @c KAknTreeIIDRoot

     * can be used to collapse every node in the tree structure.

     *

     * @param aNode Item ID of the node to be collapsed.

     *

     * @param aDrawNow @c ETrue to redraw the list after the node has been

     *      collapsed, otherwise @c EFalse.

     *

     * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

     *

     * @panic EAknHListPanicInvalidItemType Specified item is not a node.

     *

     * @pre The specified item exists in the hierarchical list and it is a

     *      node.

     *

     * @post The specified item is collapsed and all of its children, which are

     *      not set persistent, are removed from the list.

     */

    IMPORT_C void CollapseNode( TAknTreeItemID aNode, TBool aDrawNow );

    /**

     * Checks whether the specified node is expanded.

     *

     * @param aNode Item ID of a node.

     *

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

     *

     * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

     *

     * @panic EAknHListPanicInvalidItemType Specified item is not a node.

     */

    IMPORT_C TBool IsExpanded( TAknTreeItemID aNode ) const;

    /**

     * Gets the item ID of the focused item.

     *

     * @return Item ID of the focused item. Value @c KAknTreeIIDNone is

     *      returned if no item is focused.

     */

    IMPORT_C TAknTreeItemID FocusedItem() const;

    /**

     * Sets the focused item and its position on the list view. When the

     * focused item is changed, the vertical position of the view is changed

     * so that the position of the focused item on the view matches the given

     * index. The horizontal position of the view is changed so that the

     * the beginning of the focused item is visible.

     *

     * @param aItem Item ID of the item to be focused.

     *

     * @param aIndex The position of the focused item on the list view. If the

     *      index does not refer to any visible view location, that is, the

     *      index is less than zero or greater than or equal to the number of

     *      items in the view, the focused item is changed to specified item,

     *      but the position of the view is not changed.

     *

     * @param aDrawNow @c ETrue to redraw the list after the focused item

     *      has been changed, otherwise @c EFalse.

     *

     * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

     */

    IMPORT_C void SetFocusedItem( TAknTreeItemID aItem, TInt aIndex,

        TBool aDrawNow );

    /**

     * Highlight rectangle for the focused item. The returned rectangle is

     * screen relative and it can be used, for example, when positioning

     * pop-up for focused item. If the focused item is not visible, the

     * method returns an empty rectangle.

     *

     * @return Highlight rectangle of focused list item.

     */

    IMPORT_C TRect HighlightRect() const;

    /**

     * Adds a new icon to the list to be used by all list items. The same

     * icon can be used by multiple tree items and its referenced by the

     * ID returned by this function. The given parameters are also stored

     * in the tree list, which enables the tree list to reconstruct the

     * bitmaps on skin change events. If this behaviour is insufficient for

     * the client, it can always replace the existing icons by itself with

     * @c AssignIconL or @c AssignColorIconL method.

     *

     * @param aId Item ID of the icon to be added.

     *

     * @param aFilename Filename to be used to construct the item, 

     *      if no matching item was found in the currently active skin.

     *

     * @param aBitmapId ID of the bitmap in the file. 

     *      Used only if no matching item was found in the currently 

     *      active skin.

     *

     * @param aMaskId ID of the mask in the file.

     *      Used only if no matching item was found in the currently

     *      active skin.

     * 

     * @param aScaleMode Scale mode used when icon's bitmap is resized.

     *

     * @return ID assigned for the added icon.

     *

     * @leave KErrNoMemory Not enough memory.

     */

    IMPORT_C TInt AddIconL( const TAknsItemID& aId, const TDesC& aFilename,

        TInt aBitmapId, TInt aMaskId, TScaleMode aScaleMode );

    /**

     * Adds a new icon to the list. The ownership of given bitmaps is

     * transferred to the list only if specified with @c aTransferOwnership

     * parameter. Note that icons added to the list with this method cannot

     * be reconstructed on skin change events by the list. If necessary,

     * previously added icons can be replaced with @c AssignIconL method.

     *

     * @param aIcon Pointer to the bitmap.

     *

     * @param aMask Pointer to the mask bitmap.

     *

     * @param aTransferOwnership @c ETrue, if ownership of bitmaps is

     * transferred to the list. If the method leaves, it is always on the

     * responsibility of the client code to take care of deleting the bitmaps.

     *

     * @param aScaleMode The scale mode used when the icon is resized.

     *

     * @return ID assigned for the added icon.

     *

     * @leave KErrNoMemory Not enough memory.

     */

    IMPORT_C TInt AddIconL( CFbsBitmap* aIcon, CFbsBitmap* aMask,

        TBool aTransferOwnership, TScaleMode aScaleMode );

    /**

     * Adds a new icon to the list to be used by all list items. The same

     * icon can be used by multiple tree items and it is referenced by the

     * icon ID returned by this function. The given parameters are stored

     * in the tree list, and they are used in reconstructing the bitmaps on

     * skin change events.

     *

     * @param aId Item ID of the icon to be added.

     *

     * @param aColorId Item ID of the color table.

     *

     * @param aColorIndex Index in the color table.

     *

     * @param aFilename Filename to be used to construct the item, 

     *      if no matching item was found in the currently active skin.

     *

     * @param aBitmapId ID of the bitmap in the file. 

     *      Used only if no matching item was found in the currently 

     *      active skin.

     *

     * @param aMaskId ID of the mask in the file.

     *      Used only if no matching item was found in the currently

     *      active skin.

     *

     * @param aDefaultColor Color RGB value to be used, if no color

     *      is found in the currently active skin.

     *

     * @param aScaleMode Scale mode used when icon's bitmap is resized.

     *

     * @return ID assigned for the added icon.

     *

     * @leave KErrNoMemory Not enough memory.

     */

    IMPORT_C TInt AddColorIconL( const TAknsItemID& aId,

        const TAknsItemID& aColorId, TInt aColorIndex, const TDesC& aFilename,

        TInt aBitmapId, TInt aMaskId, TRgb aDefaultColor,

        TScaleMode aScaleMode );

    /**

     * Assigns an icon to the tree list with the specified ID. If an icon

     * with specified ID already exists in the list, the existing icon is

     * replaced with the new one. The given parameters are stored in the

     * tree list, and they are used in reconstructing the bitmaps on skin

     * change events.

     *

     * @param aIconId Icon ID assigned for the icon.

     *

     * @param aId Item ID of the icon to be added.

     *

     * @param aFilename Filename to be used to construct the item, 

     *      if no matching item was found in the currently active skin.

     *

     * @param aBitmapId ID of the bitmap in the file. 

     *      Used only if no matching item was found in the currently 

     *      active skin.

     *

     * @param aMaskId ID of the mask in the file.

     *      Used only if no matching item was found in the currently

     *      active skin.

     *

     * @param aScaleMode Scale mode used when icon's bitmap is resized.

     *

     * @leave KErrNoMemory Not enough memory.

     *

     * @leave KErrArgument Specified icon ID is out of allowed range.

     */

    IMPORT_C void AssignIconL( TInt aIconId, const TAknsItemID& aId,

        const TDesC& aFilename, TInt aBitmapId, TInt aMaskId,

        TScaleMode aScaleMode );

    /**

     * Assigns an icon to the tree list with the specified ID. If an icon

     * with specified ID already exists in the list, the existing icon is

     * replaced with the new one. The ownership of bitmaps is transferred to

     * the list only if so specifed with @c aTransferOnwership parameter.

     * Note that icons added with this method cannot be reconstructed on

     * skin change events by list.

     *

     * @param aIconId Icon ID assigned for the icon.

     *

     * @param aIcon Pointer to the bitmap.

     *

     * @param aMask Pointer to the mask bitmap.

     *

     * @param aTransferOwnership @c ETrue, if ownership of bitmaps is

     *      transferred to the list. If the method leaves, it is always on

     *      the responsibility of the client code to take care of deleting

     *      the bitmaps.

     *

     * @param aScaleMode Scale mode used when icon's bitmap is resized.

     *

     * @leave KErrNoMemory Not enough memory.

     *

     * @leave KErrArgument Specified icon ID is out of allowed range.

     */

    IMPORT_C void AssignIconL( TInt aIconId, CFbsBitmap* aIcon,

        CFbsBitmap* aMask, TBool aTransferOwnership, TScaleMode aScaleMode );

    /**

     * Assigns a color icon to the list with the specified ID. If an icon

     * with specified ID already exists in the list, the existing icon is

     * replaced with the new one. The given parameters are stored in the

     * tree list, and they are used in reconstructing the bitmaps on skin

     * change events.

     *

     * @param aIconId Icon ID assigned for the icon.

     *

     * @param aId Item ID of the icon to be added.

     *

     * @param aColorId Item ID of the color table.

     *

     * @param aColorIndex Index in the color table.

     *

     * @param aFilename Filename to be used to construct the item, 

     *      if no matching item was found in the currently active skin.

     *

     * @param aBitmapId ID of the bitmap in the file. 

     *      Used only if no matching item was found in the currently 

     *      active skin.

     *

     * @param aMaskId ID of the mask in the file.

     *      Used only if no matching item was found in the currently

     *      active skin.

     *

     * @param aDefaultColor Color RGB value to be used, if no color

     *      is found in the currently active skin.

     *

     * @param aScaleMode Scale mode used when icon's bitmap is resized.

     *

     * @leave KErrNoMemory Not enough memory.

     *

     * @leave KErrArgument Specified icon ID is out of allowed range.

     */ 

    IMPORT_C void AssignColorIconL( TInt aIconId, const TAknsItemID& aId,

        const TAknsItemID& aColorId, TInt aColorIndex, const TDesC& aFilename,

        TInt aBitmapId, TInt aMaskId, TRgb aDefaultColor,

        TScaleMode aScaleMode );

    /**

     * Removes the specified icon from the tree list. The specified icon cannot

     * be any of the default tree list icon, in which case the leaves with

     * value @c KErrArgument. If the specified icon is not found, the function

     * does nothing.

     *

     * @param aIconId Icon ID of the removed icon.

     *

     * @leave KErrArgument if specified icon is one of the default icons.

     */

    IMPORT_C void RemoveIconL( TInt aIconId );

    /**

     * Returns the number of children of a hierarchical list node. This method,

     * along with @c Child() method, can be used for enquiring information of

     * the list structure. Constant @c KAknTreeIIDRoot can be used to get the

     * item count on the top-most level of the list.

     *

     * @param aNode Item ID of a node.

     *

     * @return Number of children of specified node.

     *

     * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

     *

     * @panic EAknHListPanicInvalidItemType Specified item is not a node.

     */

    IMPORT_C TInt ChildCount( TAknTreeItemID aNode ) const;

    /**

     * Gets the item ID of a child of a hierarcical list node. The specific

     * child is specified with an index. The child count for any hierarchical

     * list node can be get with @c ChildCount() method.

     *