1 /*

     2 * Copyright (c) 2006-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:   Timed values

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef __ALF_TIMED_VALUE__

    21 #define __ALF_TIMED_VALUE__

    22 

    23 #include <e32std.h>

    24 

    25 // Todo: is there need to expose these

    26 enum TAlfTimedValueFlags

    27     {

    28     EAlfValueFlagsNone = 0,

    29     EAlfValueNowChanged = 1,

    30     EAlfValueTargetChanged = 2,

    31     EAlfInterpolationStyleChanged =4,

    32     EAlfMappingFunctionChanged = 8,

    33     EAlfSpeedChanged = 16,    

    34     EAlfValueFlagsAll = 0xffffffff

    35     };

    36 

    37 /**

    38  * Timed value interpolation styles.

    39  *

    40  * @see To implement custom interpolation styles, you can use

    41  * mapping functions.

    42  *

    43  * @see MAlfMappingFunction

    44  * @see TAlfTimedValue::SetFunction()

    45  */

    46 enum TAlfInterpolationStyle

    47     {

    48     /** No interpolation is done. The target value becomes effective

    49         in a single step. */

    50     EAlfTimedValueStyleUseSystemDefault,

    51 

    52     EAlfTimedValueStyleNone,

    53 

    54     /** Use linear interpolation between the current value and the

    55         target value. */

    56     EAlfTimedValueStyleLinear,

    57 

    58     /** Use a sine wave for approximating preservation of momentum. */

    59     EAlfTimedValueStyleSineWave,

    60 

    61     /** Quarter of a sine wave for decelerating movement. */

    62     EAlfTimedValueStyleDecelerate,

    63 

    64     /** Quarter of a sine wave for accelerating movement. */

    65     EAlfTimedValueStyleAccelerate,

    66 

    67     /** Sine wave or decelerating style based on when the target value

    68         is defined. */

    69     EAlfTimedValueStyleAdaptive,

    70 

    71     /** Combination of linear and deceleration. */

    72     EAlfTimedValueStyleImpulse,

    73 

    74     EAlfTimedValueStyleLast

    75     };

    76 

    77 /**

    78  * 

    79  * Timed value class.

    80  *

    81  * Timed values are able to interpolate their value independently based on

    82  * time. The interpolation can be configured to follow a curve instead of

    83  * being linear. Timed value does not restrict the value units but interpolates

    84  * on any given real value. Mapping function can be used that maps the interpolated

    85  * values to some other real value space. If no mapping function is specified an

    86  * identity mapping is used. Current values and target values of timed value can be

    87  * set through class methods. Delays for timed value to achieve the target value can

    88  * be given in the Set - method. Timed value supports number of different interpolation

    89  * styles.

    90  *

    91  * @code

    92  *   // Here are some examples how the timed value can be used.

    93  *   // In the examples, the opacity of the visual is used as

    94  *   // an example, but any of the timed values work the same.

    95  * 

    96  *   // #1 New variable - getters are not really relevant

    97  *   TAlfTimedValue opacity;

    98  *   opacity->SetTarget( 1, 500 );

    99  *   visual->SetOpacity( opacity ); // changes only the target

   100  *   

   101  *   // 2# Data fetching

   102  *   // a) preferred

   103  *   const TAlfTimedValue& opacity = visual->Opacity();

   104  *   TReal32 valueNow = opacity->ValueNow();

   105  *   TReal32 target = opacity->Target();

   106  *   // b) 

   107  *   TReal32 valueNow = visual->Opacity().ValueNow();

   108  *   TReal32 target = visual->Opacity().Target();

   109  *   

   110  *   // 3# Data fetching and value update

   111  *   TAlfTimedValue opacity( visual->Opacity() );

   112  *   TReal32 target = opacity->Target();

   113  *   opacity->SetTarget( target*2, 500 );

   114  *   visual->SetOpacity( opacity );

   115  *   

   116  *   // 4# Use the same timed value for other places:

   117  *   // a)

   118  *   const TAlfTimedValue& visualOpacity = visual->Opacity();

   119  *   layout->SetOpacity( visualOpacity );

   120  *   // b)

   121  *   TAlfTimedValue visualOpacity( visual->Opacity() );

   122  *   visualOpacity->SetTarget( 1, 500 );

   123  *   layout->SetOpacity( visualOpacity );

   124  * @endcode

   125  *

   126  * @lib alfclient.lib

   127  * @since S60 v3.2

   128  **/

   129 class TAlfTimedValue

   130     {

   131     public:

   132 

   133     /**

   134      * Constructor. Enables creation of timed value with no explicitly set initial value.

   135      * The timed value is set to zero.

   136      *

   137      */

   138     IMPORT_C TAlfTimedValue();

   139     

   140     /**

   141      * Constructor. Enables initial value setting.

   142      *

   143      * @param aInitialValue  Initial value.

   144      *

   145      */

   146     IMPORT_C TAlfTimedValue(TReal32 aInitialValue) __SOFTFP; 

   147 

   148     /**

   149      * Constructor. Enables target value setting.

   150      *

   151      * @param aTargetValue  Target value.

   152      * @param aTime When the target value will be in effect. Transition duration in milliseconds.

   153      *

   154      */

   155     IMPORT_C TAlfTimedValue(TReal32 aTargetValue, TInt aTime) __SOFTFP; 

   156     

   157     /**

   158      * Set a new current value Change becomes effective immediately.

   159      *

   160      * @param aValueNow  New currentvalue.

   161      */

   162     IMPORT_C void SetValueNow(const TReal32& aValueNow);

   163 

   164     /**

   165      * Gets current value.

   166      *

   167      * @return Current value.

   168      */

   169     IMPORT_C TReal32 ValueNow() const __SOFTFP;

   170     

   171     /**

   172      * Set a new target value that becomes effective after a delay.

   173      * @see SetTargetWithSpeed()

   174      *

   175      * @param aValue            New target value.

   176      * @param aTime   Time duration after the target value will be in effect. Transition duration in milliseconds.

   177      */

   178     IMPORT_C void SetTarget(const TReal32& aTarget, TInt aTime); 

   179 

   180     /**

   181      * Sets a new target value. The transition time depends on the speed.

   182      * @see SetTarget()

   183      *

   184      * @param aTarget          New target value.

   185      * @param aUnitsPerSecond  Speed of change.

   186      */

   187     IMPORT_C void SetTargetWithSpeed(TReal32 aTarget, TReal32 aUnitsPerSecond) __SOFTFP;

   188 

   189     /**

   190      * Gets target value.

   191      *

   192      * @return Target value.

   193      */

   194     IMPORT_C TReal32 Target() const __SOFTFP;

   195 

   196     /**

   197      * Gets duration of the transition.

   198      *

   199      * @return Duration time in milliseconds..

   200      */

   201     IMPORT_C TInt TimeToTargetinMilliSeconds() const;

   202 

   203     /**

   204      * Gets speed of the transition in units per second if it has been set

   205      * with SetTargetWithSpeed.

   206      *

   207      * @return Speed of the transition in units per second.

   208      */

   209     IMPORT_C TReal32 Speed() const __SOFTFP;

   210         

   211     /**

   212      * Sets the interpolation style of the timed value.

   213      *

   214      * @param aStyle  Interpolation style used to reach target value.

   215      */

   216     IMPORT_C void SetStyle(TAlfInterpolationStyle aStyle);

   217     

   218     /**

   219      * Sets identifier of a mapping function that affects the timed value. 

   220      *

   221      * @param aIdentifier Identifier of a function that will map the current value to required

   222      * number space.

   223      */

   224     IMPORT_C void SetMappingFunctionIdentifier(TInt aIdentifier);    

   225 

   226     /**

   227      * Gets identifier of a mapping function that affects the timed value. 

   228      *

   229      * @return aIdentifier Identifier of a function that will map the current value to required

   230      * number space.

   231      */

   232     IMPORT_C TInt MappingFunctionIdentifier() const;

   233             

   234     /**

   235      * Gets flags.

   236      *

   237      * @return Flags.

   238      */

   239     IMPORT_C TInt& Flags();

   240         

   241     /**

   242      * Gets the interpolation style of the timed value.

   243      *

   244      * @return Interpolation style used to reach target value.

   245      */

   246     IMPORT_C TAlfInterpolationStyle Style();

   247         

   248 private:

   249     TReal32 iValueNow;

   250     TReal32 iValueTarget;

   251     TInt iTimeToTarget;

   252     TInt iInterpolationStyle;

   253     TInt iMappingFunctionIdentifier;

   254     TReal32 iSpeed;

   255     TInt iFlags;

   256 

   257 private:

   258     TInt iSpare1;

   259     TInt iSpare2;

   260     }; 

   261 

   262 struct TAlfRealPoint

   263     {

   264     TAlfRealPoint():iX(0),iY(0){}

   265     TAlfRealPoint(const TReal32& aX, const TReal32& aY):iX(aX),iY(aY){}

   266     TAlfRealPoint(const TPoint& aPoint):iX(aPoint.iX),iY(aPoint.iY){}

   267         

   268     inline operator TPoint() const

   269         {

   270         return TPoint((TInt)iX, (TInt)iY);

   271         }

   272 

   273     inline TSize AsSize() const

   274         {

   275         return TSize((TInt)iX, (TInt)iY);

   276         }

   277 

   278     inline TAlfRealPoint operator-(const TAlfRealPoint& aPoint) const

   279         {

   280         return TAlfRealPoint(iX - aPoint.iX, iY - aPoint.iY);

   281         }

   282 

   283     inline TAlfRealPoint operator+(const TAlfRealPoint& aPoint) const

   284         {

   285         return TAlfRealPoint(iX + aPoint.iX, iY + aPoint.iY);

   286         }

   287 

   288     inline TAlfRealPoint& operator+=(const TAlfRealPoint& aPoint)

   289         {

   290         iX += aPoint.iX;

   291         iY += aPoint.iY;

   292         return *this;

   293         }

   294 

   295     inline TAlfRealPoint& operator-=(const TAlfRealPoint& aPoint)

   296         {

   297         iX -= aPoint.iX;

   298         iY -= aPoint.iY;

   299         return *this;

   300         }

   301     

   302     inline TBool operator==(const TAlfRealPoint& aPoint) const 

   303         {

   304         if ( Abs(iX-aPoint.iX) < 0.0001 && Abs(iY-aPoint.iY) < 0.0001 )

   305             {

   306             return ETrue;

   307             }

   308         

   309         return EFalse;

   310         }

   311 

   312     TReal32 iX;

   313     TReal32 iY;    

   314 

   315 private:

   316     TInt iSpare1;

   317     TInt iSpare2;

   318     };

   319 

   320 struct TAlfRealSize

   321     {

   322     TAlfRealSize()

   323         : iWidth(0.f), iHeight(0.f) {}

   324         

   325     inline TAlfRealSize(TReal32 aWidth, TReal32 aHeight)

   326             : iWidth(aWidth), iHeight(aHeight)

   327         {

   328         }

   329         

   330     inline TAlfRealSize(const TSize& aSize)

   331             : iWidth((TReal32)aSize.iWidth), iHeight((TReal32)aSize.iHeight)

   332         {

   333         }

   334         

   335     inline TAlfRealSize(const TAlfRealPoint& aPoint)

   336             : iWidth( aPoint.iX ), iHeight( aPoint.iY )

   337         {

   338         }

   339         

   340     inline operator TSize() const

   341         {

   342         return TSize((TInt)iWidth, (TInt)iHeight);

   343         }

   344         

   345 public:    

   346 

   347     /** Width. */    

   348     TReal32 iWidth;

   349 

   350     /** Height. */

   351     TReal32 iHeight;

   352 

   353 private:

   354     TInt iSpare1;

   355     TInt iSpare2;

   356     };

   357 

   358 

   359 struct TAlfRealRect

   360     {

   361     TAlfRealRect(){}

   362     TAlfRealRect(const TRect& aRect):iTl(aRect.iTl),iBr(aRect.iBr){}

   363     TAlfRealRect(const TAlfRealPoint& aTl, const TAlfRealPoint& aBr):iTl(aTl),iBr(aBr){}

   364     inline operator TRect() const

   365         {

   366         return TRect((TPoint)iTl, (TPoint)iBr);

   367         }

   368 

   369     inline TReal32 Width() const

   370         {

   371         return iBr.iX - iTl.iX;

   372         }

   373         

   374     inline TReal32 Height() const

   375         {

   376         return iBr.iY - iTl.iY;

   377         }

   378         

   379     inline TAlfRealPoint TopRight() const

   380         {

   381         return TAlfRealPoint(iBr.iX, iTl.iY);

   382         }

   383 

   384     inline TAlfRealPoint BottomLeft() const

   385         {

   386         return TAlfRealPoint(iTl.iX, iBr.iY);

   387         }

   388 

   389     inline TAlfRealSize Size() const

   390         {

   391         return TAlfRealSize(Width(), Height());

   392         }

   393 

   394 

   395     inline TAlfRealPoint Center() const

   396         {

   397         return iTl + TAlfRealPoint(Width()/2, Height()/2);

   398         }

   399 

   400 

   401     inline void Grow(TReal32 aX, TReal32 aY)

   402         {

   403         iTl.iX -= aX;

   404         iTl.iY -= aY;

   405         iBr.iX += aX;

   406         iBr.iY += aY;

   407         }

   408         

   409     inline void Shrink(TReal32 aX, TReal32 aY)

   410         {

   411         iTl.iX += aX;

   412         iTl.iY += aY;

   413         iBr.iX -= aX;

   414         iBr.iY -= aY;

   415         }

   416 

   417     inline void Shrink(const TPoint& aPoint)

   418         {

   419         iTl.iX += aPoint.iX;

   420         iTl.iY += aPoint.iY;

   421         iBr.iX -= aPoint.iX;

   422         iBr.iY -= aPoint.iY;

   423         }

   424         

   425     inline void Shrink(const TAlfRealPoint& aPoint)

   426         {

   427         iTl.iX += aPoint.iX;

   428         iTl.iY += aPoint.iY;

   429         iBr.iX -= aPoint.iX;

   430         iBr.iY -= aPoint.iY;

   431         }

   432         

   433     inline void Shrink(const TAlfRealRect& aRect)

   434         {

   435         iTl.iX += aRect.iTl.iX;

   436         iTl.iY += aRect.iTl.iY;

   437         iBr.iX -= aRect.iBr.iX;

   438         iBr.iY -= aRect.iBr.iY;

   439         }

   440         

   441     inline void Move(TReal32 aDx, TReal32 aDy)

   442         {

   443         iTl.iX += aDx;

   444         iTl.iY += aDy;

   445         iBr.iX += aDx;

   446         iBr.iY += aDy;

   447         }

   448 

   449     TAlfRealPoint iTl;

   450     TAlfRealPoint iBr;    

   451 

   452 private:

   453     TInt iSpare1;

   454     TInt iSpare2;

   455     };

   456 

   457 class TAlfTimedPoint

   458     {

   459 public:    

   460     /**

   461      * Default constructor.

   462      */

   463     IMPORT_C TAlfTimedPoint();

   464 

   465     /**

   466      * Constructor that sets default values.

   467      */

   468     IMPORT_C TAlfTimedPoint(TReal32 aX, TReal32 aY) __SOFTFP;

   469 

   470     /**

   471      * Constructor. Enables target value setting.

   472      *

   473      * @param aXTarget  Target X value.

   474      * @param aYTarget  Target Y value.

   475      * @param aTransitionTime When the target value will be in effect. Transition duration in milliseconds.

   476      *

   477      */

   478     IMPORT_C TAlfTimedPoint(TReal32 aXTarget, TReal32 aYTarget, TInt aTransitionTime) __SOFTFP;

   479 

   480     /**

   481      * Sets the interpolation style of both components of the point.

   482      *

   483      * @param aStyle  Timed value interpolation style.

   484      */

   485     IMPORT_C void SetStyle(TAlfInterpolationStyle aStyle);

   486 

   487     /**

   488      * Sets identifier of a mapping function that affects the timed value for both 

   489      * components of the point. 

   490      *

   491      * @param aIdentifier Identifier of a function that will map the current value to required

   492      * number space.

   493      */

   494     IMPORT_C void SetMappingFunctionIdentifier(TInt aIdentifier);    

   495  

   496      /**

   497      * Sets the target for the timed point.

   498      *

   499      * @param aPoint           Target point.

   500      * @param aTransitionTime  Duration for reaching the target.

   501      */

   502     IMPORT_C void SetTarget(const TAlfRealPoint& aPoint, TInt aTransitionTime = 0);

   503 

   504     /**

   505      * Sets the target value of both components of the timed point.

   506      *

   507      * @param aValue           New target value.

   508      * @param aTransitionTime  Duration for reaching the target.

   509      */

   510     IMPORT_C void SetTarget(TReal32 aValue, TInt aTransitionTime = 0) __SOFTFP;

   511 

   512     /**

   513      * Sets the target value for the timed point, with a transition that is

   514      * done using a specific speed.

   515      *

   516      * @param aPoint  Target point.

   517      * @param aUnitsPerSecond  Units per second during the transition.

   518      */

   519     IMPORT_C void SetTargetWithSpeed(const TAlfRealPoint& aPoint, TReal32 aUnitsPerSecond) __SOFTFP;

   520 

   521     /**

   522      * Sets the target value of both components of the timed point.

   523      *

   524      * @param aValue  New target value.

   525      * @param aUnitsPerSecond  Speed of change.

   526      */

   527     IMPORT_C void SetTargetWithSpeed(TReal32 aValue, TReal32 aUnitsPerSecond) __SOFTFP;

   528     

   529     /**

   530      * Returns the current value of the point.

   531      *

   532      * @return  Current values as a regular TAlfRealPoint.

   533      */

   534     inline TAlfRealPoint ValueNow() const

   535         {

   536         return TAlfRealPoint(iX.ValueNow(), iY.ValueNow());

   537         }

   538         

   539     /**

   540      * Returns the target value of the point.

   541      *

   542      * @return  Target as a TAlfRealPoint.

   543      */

   544     inline TAlfRealPoint Target()  const

   545         {

   546         return TAlfRealPoint(iX.Target(), iY.Target());

   547         }

   548     

   549     /**

   550      * Returns the transition time value of the point.

   551      *

   552      * @return  Transition times as a TAlfRealPoint.

   553      */

   554     inline TAlfRealPoint TimeToTargetinMilliSeconds()  const

   555         {

   556         return TAlfRealPoint(iX.TimeToTargetinMilliSeconds(), iY.TimeToTargetinMilliSeconds());

   557         }

   558 

   559     /**

   560      * Returns the current interpolatad value of the point rounded to nearest

   561      * integer values. Note that the TAlfTimedPoint values are

   562      * floating-point.

   563      *

   564      * @see ValueNow() For returning the floating-point current value.

   565      *

   566      * @return  Current values as a regular TPoint.

   567      */

   568     IMPORT_C TPoint IntValueNow() const;

   569 

   570     /**

   571      * Returns the target value of the point rounded to nearest

   572      * integer values. Note that the TAlfTimedPoint values are

   573      * floating-point.

   574      *

   575      * @see Target() For returning the floating-point values.

   576      *

   577      * @return Target values as a normal TPoint - target value rounded to

   578      * nearest integer.

   579      */

   580     IMPORT_C TPoint IntTarget() const;

   581 

   582 public:

   583     

   584     TAlfTimedValue iX;

   585     TAlfTimedValue iY;

   586 

   587 private:

   588     TInt iSpare1;

   589     TInt iSpare2;

   590     };

   591 

   592 

   593 

   594 

   595 #endif