/*

* 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:  A controlet class for doing marquee text scrolling.

*

*/

#ifndef MARQUEECLET_H

#define MARQUEECLET_H

#include <e32base.h>

#include <alf/alfeventhandler.h>

// Forward declarations.

class CAlfViewportLayout;

class CAlfControl;

/**

 * A controlet for doing marquee scrolling. 

 *

 * This class handles the logic and drawing for a

 * marquee scrolling visual. When you initialise the clet,

 * you pass in the type and direction of the scrolling. Also,

 * you need to tell the clet the viewport that you want to scroll.

 * To start the scrolling action, call StartScrolling.

 */

class TFsMarqueeClet: public MAlfEventHandler

    {

public:

    /**

     * The direction that the visual scrolls from.

     * ie, EScrollFromLeft means the visual will appear on the left and move off to the right.

     */

    enum TScrollDirection

        {

        EScrollFromLeft = 0,  

        EScrollFromRight,

        /** No scrolling direction set, do not scroll. */

        EScrollNothing = -1

        };    

    /**

     * The animation type of the scrolling.

     */    

    enum TScrollType

        {

        /** Bounce backwards and forwards continuously. */

        EScrollBounce = 0,  

        /** Scroll continuously. Note that the visual contents must be duplicated twice for smooth scrolling effect. */

        EScrollWrap,

        /** Scroll forth then stop. */

        EScrollForth

        };        

public:

    /* Constructors. */

    /**

     * Constructor.

     * 

     */

    TFsMarqueeClet(CAlfControl& aControl, CAlfViewportLayout& aViewport, TScrollDirection aDir = TFsMarqueeClet::EScrollFromRight, TScrollType aType = TFsMarqueeClet::EScrollWrap);

    /**

     * Destructor.

     */

    virtual ~TFsMarqueeClet();

    /**

     * Set the type of marquee.

     * 

     * @param aType Type of scrolling.

     */

    void SetScrollType( const TScrollType aType );

    /**

     * The number of milliseconds to complete a full scroll cycle.

     * 

     * The amount of time that the scrolling clet will use to scroll

     * the entire contents of the visual.

     * @param aTime The time in milliseconds that a complete scroll cycle will take.

     */

    void SetScrollSpeed(TInt aTime);

    /**

     * Sets the number of marquee's scroll cycles.

     * 

     * @aRepetition Number of marquee cycles. Negative value - infinite loop.

     */

    void SetScrollRepetitions( TInt aRepetitions );

    /**

     * The function sets time for a pause after each cycle.

     * 

     * @param aCycleDelay Time in miliseconds for a next cycle start delay.

     */

    void SetScrollCycleDelay ( TInt aCycleDelay );

    /**

     * Change the direction that the text scrolls from.

     * 

     * Set the direction that the text will scroll from. For example, setting the direction to

     * EScrollFromRight will mean that the visual will scroll in from the left and leave from the right

     * edge of the viewport.

     *

     * @param aTime The time in milliseconds that a complete scroll cycle will take.

     * @see TScrollDirection.

     */

    void SetScrollDirection(TScrollDirection aDir);

    /**

     * The area that we want to scroll.

     * 

     * Sets the scrolling area.

     * @param aScrollableArea The dimensions in pixels of the area to scroll.

     */    

    void SetScrollableArea(TSize& aScrollableArea);

    /**

     * Begin scrolling with the specified speed, direction and type.

     *

     * Call this to begin or reset the scrolling behaviour of this marquee.

     */

    void StartScrolling();

    /**

     * Stop scrolling and reset the visual to its zero position.

     */

    void StopScrolling();

protected:

    /**

     * Initiate scrolling once then stop.

     */

    void StartScrollingOnce();

    /**

     * Scroll continously forth. Generates update messages to retrigger itself forever.

     */

    void StartScrollingForth();

    /**

     * Scroll continuously in a loop. Generates update messages to retrigger itself forever.

     */    

    void StartScrollingLoop();

    /**

     * Scroll continuously in a bouncing pattern. Generates update messages to retrigger itself forever.

     */        

    void StartScrollingBounce(); 

    /**

     * The function cancels custom commands sent during scrolling process.

     */

    void CancelScrollingCommands();

    /**

     * Handles the events sent through the AlfScheduler. Implementation of

     * MAlfEventHandler interface. The scheduled events are needed in order

     * to update the scroll direction/position.

     * 

     * @param aEvent The event sent to this list visualiser.

     */

    TBool OfferEventL(const TAlfEvent& aEvent); 

protected: 

    /**

     * Custom events that drive the text wrapping/scrolling repeating.

     */

    enum TCustomEvent

        {

        ECustomEventScrollingFinished = 200,

        ECustomEventScrollingPauseFinished,

        ECustomEventScrollingStartPauseFinished

        };

    /** 

     * The viewport layout used by this clet for scrolling.     

     */

    CAlfViewportLayout& iViewport;

    /** 

     * The owning control of this clet.     

     */

    CAlfControl& iControl;

    /** 

     * Scroll direction of the marquee. (the direction it scrolls FROM).     

     */

    TScrollDirection iDir;

    /** 

     * Type of scrolling.     

     */

    TScrollType iType;

    /** 

     * The total area of the contents that we want to scroll. (Usually just the text extents).     

     */

    TSize iScrollableArea;

    /** 

     * The time for a complete scroll cycle (miliseconds).     

     */

    TInt iTime;

    /**

     * Number of marquee cycles.

     * Negative value - infinite loop.

     */

    TInt iRepetitions;

    /**

     * Cycle delay (miliseconds).

     */

    TInt iCycleDelay;

    };

#endif // MARQUEECLET_H