/*

* Copyright (c) 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:  Freestyle tree list component

 *

*/

#ifndef C_FSTREELIST_H

#define C_FSTREELIST_H

/////SYSTEM INCLUDES

//////TOOLKIT INCLUDES

#include <alf/alfcontrol.h>

//////PROJECT INCLUDES

#include "fstreelistconstants.h"

#include "fstreevisualizerbase.h"

#include "fstreevisualizerobserver.h"

//////TOOLKIT CLASSES

class CAlfEnv;

class CAlfTexture;

//////PROJECT CLASSES

class CFsTree;

class CFsTreeControl;

class MFsTreeListObserver;

class MFsTreeItemData;

class MFsTreeItemVisualizer;

class MFsTreeNodeVisualizer;

class CFsAlfTextStyleManager;

/** An array of tree list observers */

typedef RPointerArray<MFsTreeListObserver> RFsTreeListObservers;

/**

 * Batch updates for the tree.

 */

class MFsTreeBatchProcessing

    {

public:

    /**

     * Begin batch update. During batch update changes to the world

     * will not be updated on screen until the EndUpdateL is called.

     */

    virtual void BeginUpdate() = 0;

    /**

     * End batch update. All changes done between BeginUpdate and EndUpdateL

     * will be shown on screen.

     */

    virtual void EndUpdateL() = 0;

    };

/**

 * CFsTreeList is a component for creating and displaying hierarchical list 

 * using tree data structure.

 *

 * @code

 *

 * @endcode

 *

 * @lib

 */

class CFsTreeList  : public CBase, MFsTreeVisualizerObserver, MFsTreeBatchProcessing

    {

public: // from MFsTreeBatchProcessing

    /**

     * @see MFsTreeBatchProcessing::BeginUpdate

     */

    void BeginUpdate();

    /**

     * @see MFsTreeBatchProcessing::EndUpdateL

     */

    void EndUpdateL();

public: // Construction

    /** Pre-defined types of markability in list */

    enum TFsTreeListMarkType

        {

        EFsTreeListNonMarkable,

        EFsTreeListMarkable,

        EFsTreeListMultiMarkable

        };

    /** Pre-defined types of scrolling in list

     *  OLD API - to be removed.

     * */

    enum TFsTreeListScrollbars

        {

        EFsTreeListNoScrollbars,

        EFsTreeListVerticalScrollbar

        };

    /**

     * Two-phased constructor

     *

     * @param aTreeV Pointer to the class responsible for visualizing tree

     *        structure

     * @param aEnv Reference to the UI toolkit environment

     */

    IMPORT_C static CFsTreeList* NewL( CFsTreeVisualizerBase& aTreeV,

                                       CAlfEnv& aEnv );

    /**

     * C++ destructor

     */

    IMPORT_C virtual ~CFsTreeList();

    /**

     * Adds observer to the list of observers

     *

     * @param aTreeListObserver Reference to the list observer

     */

    IMPORT_C void AddObserverL( MFsTreeListObserver& aTreeListObserver );

    /**

     * Removes observer from the list of observers

     *

     * @param aTreeListObserver         Reference to the list observer

     *

     * @panic ETreeListPanicObserverNotFound The given observer was not

     *                                  registered previously

     */

    IMPORT_C void RemoveObserver( MFsTreeListObserver& aTreeListObserver );

public: // Tree list configuration

    /**

     * Returns a hitckcock control associated with the component.

     */

    IMPORT_C CAlfControl* TreeControl( ) const;

    /**

     * The function sets duration of the slide-in effect.

     *

     * @param aTimeMiliseconds Slide in time in milliseconds.

     */

    IMPORT_C void SetSlideInDuration ( TInt aTimeMiliseconds );

    /**

     * The function returns slide in effect's duration.

     *

     * @return Slide in duration in miliseconds.

     */

    IMPORT_C TInt SlideInDuration ( ) const;

    /**

     * The function sets direction of the slide in effect.

     *

     * @param aDirection A direction of the slide in effect.

     */

    IMPORT_C void SetSlideInDirection (

            MFsTreeVisualizer::TFsSlideEffect aDirection );

    /**

     * The function returns direction of the slide in effect.

     *

     * @return A direction of the slide in effect.

     */

    IMPORT_C MFsTreeVisualizer::TFsSlideEffect SlideInDirection ( ) const;

    /**

     * The function sets duration of the slide-out effect.

     *

     * @param aTimeMiliseconds Slide out time in milliseconds.

     */

    IMPORT_C void SetSlideOutDuration ( TInt aTimeMiliseconds );

    /**

     * The function returns slide out effect's duration.

     *

     * @return Slide out duration in miliseconds.

     */

    IMPORT_C TInt SlideOutDuration ( ) const;

    /**

     * The function sets direction of the slide out effect.

     *

     * @param aDirection A direction of the slide out effect.

     */

    IMPORT_C void SetSlideOutDirection (

            MFsTreeVisualizer::TFsSlideEffect aDirection );

    /**

     * The function returns direction of the slide out effect.

     *

     * @return A direction of the slide out effect.

     */

    IMPORT_C MFsTreeVisualizer::TFsSlideEffect SlideOutDirection ( ) const;

    /**

     * Returns information about looping type of the list.

     *

     * @return Type of list looping. EFsTreeListLoopingDisabled when looping

     *         is turned off.

     */

    IMPORT_C TFsTreeListLoopingType LoopingType() const;

    /**

     * Returns information whether list is markable, non-markable or

     * multi-markable

     *

     * @return Returns markability of the list

     */

    IMPORT_C TFsTreeListMarkType MarkType() const;

    /**

     * OLD API - to be removed.

     * Returns information about scrollbars used by list visual

     *

     * @return Returns a type of scrollbars that the list uses

     */

    IMPORT_C TFsTreeListScrollbars HasScrollBars() const;

    /**

     * Old API - to be removed

     *

     * @param aFlag Scrollbar type for the list

     */

    IMPORT_C void SetScrollBarsL( const TFsTreeListScrollbars aFlag );

    /**

     * Returns information about scrollbars used by list visual

     *

     * @return Returns a type of scrollbars that the list uses

     */

    IMPORT_C TFsScrollbarVisibility ScrollbarVisibility() const;

    /**

     * Enables or disables scrollbars

     *

     * @param aFlag Scrollbar type for the list

     */

    IMPORT_C void SetScrollbarVisibilityL(const TFsScrollbarVisibility aVisibility);

    /**

     * Sets type of list's looping.

     *

     * @param aLoopingType type of list looping.

     */

    IMPORT_C void SetLoopingType( const TFsTreeListLoopingType aLoopingType );

    /**

     * The functions sets fade-in's effect duration.

     * @param aFadeTime A time in miliseconds for fade in effect.

     */

    IMPORT_C void SetFadeInEffectTime( TInt aFadeTime );

    /**

     * The functions returns fade-in's effect duration.

     * @return A time in miliseconds for fade in effect.

     */

    IMPORT_C TInt FadeInEffectTime( );

    /**

     * The functions sets fade-out's effect duration.

     * @param aFadeTime A time in miliseconds for fade-out effect.

     */

    IMPORT_C void SetFadeOutEffectTime( TInt aFadeTime );

    /**

     * The functions returns fade-out's effect duration.

     * @return A time in miliseconds for fade-out effect.

     */

    IMPORT_C TInt FadeOutEffectTime( );

    /**

     * Function sets the time of list scroll per item and the scroll

     * acceleration rate.

     * @param aScrollTime Time (in miliseconds) at which the list items are

     *                    scrolled.

     * @param aScrollAcceleration Rate of scroll acceleration when the up/down

     *                            key is pressed for a long time. This is

     *                            multiplied by the number of up/down key

     *                            repeats. Acceleration rate should be in

     *                            0.0-1.0 range.

     */

    IMPORT_C void SetScrollTime ( TInt aScrollTime,

                                  TReal aScrollAcceleration = 0.0 );

    /**

     * Function gets the values of scroll speed and its acceleration rate.

     *

     * @param aScrollTime Time (in miliseconds) at which the list items are

     *                    scrolled.

     *

     * @param aScrollAcceleration Rate of scroll acceleration when the up/down

     *                            key is pressed for a long time.

     */

    IMPORT_C void GetScrollTime( TInt& aScrollTime,

                                 TReal& aScrollAcceleration );

    /**

     * Enables or disables marking of list items

     *

     * @param aFlag Type of markability for the list

     */

    IMPORT_C void SetMarkTypeL( const TFsTreeListMarkType aFlag );

    /**

     * Returns information whether list enables indention or not

     *

     * @return ETrue if indention is enabled, EFalse otherwise

     */

    IMPORT_C TInt Indentation() const;

    /**

     * Enables or disables indention for list

     *

     * @param aIndentation Indentation in pixels.

     */

    IMPORT_C void SetIndentationL( const TInt aIndentation );

    /**

     * The functions sets wether all item in the list should be always in

     * extended state or in normal state.

     * The list view is refreshed.

     *

     * @param aAlwaysExtended ETrue if items should be always extended. EFalse

     *                        if items should be in normal state.

     */

    IMPORT_C void SetItemsAlwaysExtendedL ( TBool aAlwaysExtended );

    /*

     * The function returns if items are always in extended state or in

     * normal.

     *

     * @return ETrue if items are always in extended state, EFalse if items

     *         are in normal state.

     */

    IMPORT_C TBool IsItemsAlwaysExtended ( );

public: // Tree management

    /**

     * Inserts new item as a child of parent given by Id with the given

     * position

     *

     * @param aItemD Pointer to item's data

     * @param aItemV Pointer to item's visualizer

     * @param aParentId Id of parent node

     * @param aIndex Position of new item in the list of parent's children (if

     *               omitted, the item is inserted as last)

     * @param aAllowRefresh Blocks/Allows view update after an item has been added

     *               to the tree list. Currently works only with scrollbar update.

     *

     * @return Id of the inserted item

     *

     * @panic EFsListPanicParentIdNotFound The specified parent id was not

     *                          found

     * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's

     *                                    number of children

     */

    IMPORT_C TFsTreeItemId InsertItemL( MFsTreeItemData& aItemD,

                                        MFsTreeItemVisualizer& aItemV,

                                        const TFsTreeItemId aParentId,

                                        const TInt aIndex = -1,

                                        const TBool aAllowRefresh = ETrue);

    /**

     * Inserts new node as a child of parent given by Id with the given

     * position

     *

     * @param aItemD Pointer to node's data

     * @param aItemV Pointer to node's visualizer

     * @param aParentId Id of parent node

     * @param aIndex Position of new node in the list of parent's children (if

     *               omitted, the node is inserted as last)

     *

     * @return Id of the inserted node

     *

     * @panic EFsListPanicParentIdNotFound The specified parent id was not

     *                          found

     * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's

     *                                    number of children

     */

    IMPORT_C TFsTreeItemId InsertNodeL( MFsTreeItemData& aItemD,

                                        MFsTreeNodeVisualizer& aNodeV,

                                        const TFsTreeItemId aParentId,

                                        const TInt aIndex = -1,

                                        const TBool aAllowRefresh = ETrue );

    /**

     * Removes the item with given Id from the list. If aItemId is a node all

     * its children will be removed as well.

     *

     * @param aItemId Id of the item to be removed

     *

     * @panic EFsListPanicInvalidItemId The specified item id was not found in

     *                                  the list

     */

    IMPORT_C void RemoveL( const TFsTreeItemId aItemId );

    /**

     * Removes all items from the list.

     */

    IMPORT_C void RemoveAllL( );

    /**

     * Removes all children of the given node.

     *

     * @param aNodeId Id of the node

     *

     * @panic EFsListPanicInvalidItemId The specified item id was not found in

     *                                  the list

     * @panic EFsListPanicInvalidItemType Item id was passed instead of the

     *                                  node id

     */

    IMPORT_C void RemoveChildrenL( const TFsTreeItemId aNodeId );

    /**

     * Moves the item with given Id to the list of children of parent with

     * given id

     *

     * @param aItemId Id of the item to be moved

     * @param aTargetNode Id of the new parent node

     * @param aIndex Position of the item in the list of new parent's children

     *               (if omitted, the item/node is inserted as last)

     *

     * @panic EFsListPanicInvalidItemId The specified item id was not found in

     *                                  the list

     * @panic EFsListPanicParentIdNotFound The specified parent id was not

     *                                  found

     * @panic EFsListPanicInvalidItemType Item id was passed as a second param

     *                                    instead of the node id

     * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's

     *                                    number of children

     */

    IMPORT_C void MoveItemL( const TFsTreeItemId aItemId,

            const TFsTreeItemId aTargetNode, const TInt aIndex = -1 );

    /**

     * Checks if a node has children, if parameter is omitted, root of the

     * list is checked to indicate if the list is empty

     *

     * @param aNodeId Id of a node

     *

     * @return Etrue if a node has children, EFalse if it does not

     *

     * @panic EFsListPanicInvalidItemId The specified item id was not found in

     *                                  the list

     * @panic EFsListPanicInvalidItemType Item id was passed instead of the

     *                          node id

     */

    IMPORT_C TBool IsEmpty(const TFsTreeItemId aNodeId = KFsTreeRootID) const;

    /**

     * Returns the level of an item in tree.

     *

     * @param aItemId Id of an item.

     *

     * @return Level of an item.

     */

    IMPORT_C TUint Level( const TFsTreeItemId aItemId ) const;

    /**

     * Counts elements in the list

     *

     * @return Number of list items

     */

    IMPORT_C TUint Count() const;

    /**

     * Gets the number of children of the given node

     *

     * @param aNodeId Id of the node

     *

     * @return Number of node's children

     *

     * @panic EFsListPanicInvalidItemId The specified item id was not found in

     *                                  the list

     * @panic EFsListPanicInvalidItemType Item id was passed instead of the

     *                      node id

     */

    IMPORT_C TUint CountChildren( const TFsTreeItemId aNodeId ) const;

    /**

     * Gets the id of a child of the specified node with the position given

     *

     * @param aNodeId Id of a node

     * @param aIndex Index of the child

     *

     * @return Id of a child

     *

     * @panic EFsListPanicInvalidItemId The specified item id was not found in

     *                                  the list

     * @panic EFsListPanicInvalidItemType Item id was passed instead of the

     *                      node id

     * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's

     *                                    number of children

     */

    IMPORT_C TFsTreeItemId Child( const TFsTreeItemId aNodeId,

            const TUint aIndex ) const;

    /**

     * Returns the index of a child for a given parent

     *

     * @param aNodeId Id of a node

     * @param aItemId Id of a child

     *

     * @return Index of a child

     *

     * @panic EFsListPanicInvalidItemId The specified item id was not found

     *                                  in the list

     * @panic EFsListPanicInvalidItemType Item id was passed instead of

     *                                  the node id

     * @panic EFsListPanicIndexOutOfRange Specified index exceeds node's

     *                                  number of children