1 /*

     2 * Copyright (c) 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:  A controlet class for doing marquee text scrolling.

    15 *

    16 */

    17 

    18 

    19 #ifndef MARQUEECLET_H

    20 #define MARQUEECLET_H

    21 

    22 #include <e32base.h>

    23 #include <alf/alfeventhandler.h>

    24 

    25 // Forward declarations.

    26 class CAlfViewportLayout;

    27 class CAlfControl;

    28 

    29 /**

    30  * A controlet for doing marquee scrolling. 

    31  *

    32  * This class handles the logic and drawing for a

    33  * marquee scrolling visual. When you initialise the clet,

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

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

    36  * To start the scrolling action, call StartScrolling.

    37  */

    38 class TFsMarqueeClet: public MAlfEventHandler

    39     {

    40 public:

    41     /**

    42      * The direction that the visual scrolls from.

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

    44      */

    45     enum TScrollDirection

    46         {

    47         EScrollFromLeft = 0,  

    48         EScrollFromRight,

    49         

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

    51         EScrollNothing = -1

    52         };    

    53 

    54     /**

    55      * The animation type of the scrolling.

    56      */    

    57     enum TScrollType

    58         {

    59         /** Bounce backwards and forwards continuously. */

    60         EScrollBounce = 0,  

    61         

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

    63         EScrollWrap,

    64         

    65         /** Scroll forth then stop. */

    66         EScrollForth

    67         };        

    68     

    69 public:

    70 

    71     /* Constructors. */

    72 

    73     /**

    74      * Constructor.

    75      * 

    76      */

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

    78 

    79     /**

    80      * Destructor.

    81      */

    82     virtual ~TFsMarqueeClet();

    83     

    84     /**

    85      * Set the type of marquee.

    86      * 

    87      * @param aType Type of scrolling.

    88      */

    89     void SetScrollType( const TScrollType aType );

    90     

    91     /**

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

    93      * 

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

    95      * the entire contents of the visual.

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

    97      */

    98     void SetScrollSpeed(TInt aTime);

    99     

   100     /**

   101      * Sets the number of marquee's scroll cycles.

   102      * 

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

   104      */

   105     void SetScrollRepetitions( TInt aRepetitions );

   106 

   107     /**

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

   109      * 

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

   111      */

   112     void SetScrollCycleDelay ( TInt aCycleDelay );

   113     

   114     /**

   115      * Change the direction that the text scrolls from.

   116      * 

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

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

   119      * edge of the viewport.

   120      *

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

   122      * @see TScrollDirection.

   123      */

   124     void SetScrollDirection(TScrollDirection aDir);

   125     

   126     /**

   127      * The area that we want to scroll.

   128      * 

   129      * Sets the scrolling area.

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

   131      */    

   132     void SetScrollableArea(TSize& aScrollableArea);

   133     

   134     /**

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

   136      *

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

   138      */

   139     void StartScrolling();

   140 

   141     /**

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

   143      */

   144     void StopScrolling();

   145     

   146 protected:

   147     

   148     /**

   149      * Initiate scrolling once then stop.

   150      */

   151     void StartScrollingOnce();

   152     

   153     /**

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

   155      */

   156     void StartScrollingForth();

   157     

   158     /**

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

   160      */    

   161     void StartScrollingLoop();

   162     

   163     /**

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

   165      */        

   166     void StartScrollingBounce(); 

   167     

   168     /**

   169      * The function cancels custom commands sent during scrolling process.

   170      */

   171     void CancelScrollingCommands();

   172     

   173     /**

   174      * Handles the events sent through the AlfScheduler. Implementation of

   175      * MAlfEventHandler interface. The scheduled events are needed in order

   176      * to update the scroll direction/position.

   177      * 

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

   179      */

   180     TBool OfferEventL(const TAlfEvent& aEvent); 

   181     

   182 protected: 

   183 

   184     /**

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

   186      */

   187     enum TCustomEvent

   188         {

   189         ECustomEventScrollingFinished = 200,

   190         ECustomEventScrollingPauseFinished,

   191         ECustomEventScrollingStartPauseFinished

   192         };

   193    

   194     /** 

   195      * The viewport layout used by this clet for scrolling.     

   196      */

   197     CAlfViewportLayout& iViewport;

   198     

   199     /** 

   200      * The owning control of this clet.     

   201      */

   202     CAlfControl& iControl;

   203     

   204     /** 

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

   206      */

   207     TScrollDirection iDir;

   208         

   209     /** 

   210      * Type of scrolling.     

   211      */

   212     TScrollType iType;

   213     

   214     /** 

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

   216      */

   217     TSize iScrollableArea;

   218     

   219     /** 

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

   221      */

   222     TInt iTime;

   223     

   224     /**

   225      * Number of marquee cycles.

   226      * Negative value - infinite loop.

   227      */

   228     TInt iRepetitions;

   229     

   230     /**

   231      * Cycle delay (miliseconds).

   232      */

   233     TInt iCycleDelay;

   234        

   235     };

   236 

   237 

   238 #endif // MARQUEECLET_H