1 /*

     2 * Copyright (c) 2004-2008 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:  Interface for animation value.

    15 *

    16 */

    17 

    18 

    19 #ifndef AKNSALANIMATIONVALUE_H

    20 #define AKNSALANIMATIONVALUE_H

    21 

    22 //  INCLUDES

    23 #include <e32std.h>

    24 

    25 // FORWARD DECLARATIONS

    26 class CAknsAlPolyLine;

    27 class CAknsAlPolyLine1D;

    28 struct TAknsRlParameterData;

    29 class MAknsRlParameterIterator;

    30 

    31 // -----------------------------------------------------------------------------

    32 // AnimationValue interface

    33 // -----------------------------------------------------------------------------

    34 

    35 // CLASS DECLARATION

    36 /**

    37 * Interface for animation value. Animation value is an entity that dynamically

    38 * changes over time (most probably a function yielding a value). One animation

    39 * has pool of animation values. When the animation is running it will update

    40 * timing models first and then update the animation values.

    41 *

    42 * AnimationValue is not aware of the context where it is being used. The

    43 * animation framework binds each animation value to a timing model. Binding

    44 * animation values to effect filter parameters is also done by the animation

    45 * framework (with named references).

    46 *

    47 * @since 3.0

    48 */

    49 class MAknsAlAnimationValue

    50     {

    51     public:

    52 

    53         /**

    54         * This interface is used for controlling the ownership.

    55         */

    56         virtual ~MAknsAlAnimationValue() {}

    57 

    58         /**

    59         * Advances the state of the animation value by one frame.

    60         *

    61         * @param aDeltaTime The time delta between this update and the previous

    62         *   update, in milliseconds.

    63         * @param aRelative The relative position in current animation duration,

    64         *   16.16 fixed point, always in real number range [0,1]. See

    65         *   CAknsAlTimingModelRealTime.h for details.

    66         */

    67         virtual void Tick( TUint32 aDeltaTime, TUint32 aRelative ) =0;

    68 

    69         /**

    70         * Fills the provided parameter structure with the current animation

    71         * value type and value. Note that the parameter name is not changed

    72         * (name is assigned by the animation framework).

    73         */

    74         virtual void FillData( TAknsRlParameterData& aData ) const =0;

    75 

    76         /**

    77         * Parametrizes the animation value. The semantics of this method follow

    78         * MAknsRlEffect::SetParametersL. Setting parameters is done once when

    79         * the animation is created.

    80         */

    81         virtual void SetParametersL( MAknsRlParameterIterator& aParameters ) =0;

    82 

    83         /**

    84         * Resets the animation value state to the very beginning of animation

    85         * (without losing any parameter information). Restarting an animation

    86         * cause Begin on all animation values.

    87         */

    88         virtual void Begin() =0;

    89 

    90     public: // Cleanup operation

    91 

    92         /**

    93         * Cleanup operation for internal use.

    94         *

    95         * @internal

    96         */

    97         static void CleanupOp( TAny* aItem )

    98             {

    99             MAknsAlAnimationValue* value =

   100                 static_cast<MAknsAlAnimationValue*>( aItem );

   101             delete value;

   102             }

   103     };

   104 

   105 // -----------------------------------------------------------------------------

   106 // LinearRange

   107 // -----------------------------------------------------------------------------

   108 

   109 // CONSTANTS

   110 

   111 // Animation value UID

   112 const TInt KAknsAlValueLinearRangeUID = 0x10207626;

   113 

   114 // Constants for parameter names

   115 _LIT( KAknsAlValueLinearRangeStart, "s" );

   116 _LIT( KAknsAlValueLinearRangeEnd, "e" );

   117 

   118 // CLASS DECLARATION

   119 /**

   120 * Animation value implementation of linear range. Resulting values are

   121 * generated linearly in range [start, end] by using mapping

   122 *   current = start + relative * (end - start)

   123 *

   124 * @since 3.0

   125 */

   126 NONSHARABLE_CLASS( CAknsAlValueLinearRange ):

   127     public CBase, public MAknsAlAnimationValue

   128     {

   129     protected: // Protected constructors

   130         CAknsAlValueLinearRange();

   131 

   132     public:

   133         static CAknsAlValueLinearRange* NewL();

   134         virtual ~CAknsAlValueLinearRange();

   135 

   136     public: // Implementation of MAknsAlAnimationValue

   137         void Tick( TUint32 aDeltaTime, TUint32 aRelative );

   138 

   139         /**

   140         * Fills the data with the current range value (integer).

   141         */

   142         void FillData( TAknsRlParameterData& aData ) const;

   143 

   144         /**

   145         * Accepted named parameters:

   146         * - "s", integer, range [MIN_INT, MAX_INT], range start value

   147         * - "e", integer, range [MIN_INT, MAX_INT], range end value

   148         *

   149         * There are no constraints on start and end values. E.g. "s" < "e" is

   150         * ok, "s" >= "e" is ok.

   151         *

   152         * The default parameter values are:

   153         * - "s" = 0

   154         * - "e" = 255

   155         */

   156         void SetParametersL( MAknsRlParameterIterator& aParameters );

   157         void Begin();

   158 

   159     private:

   160         TInt iValue;

   161         TInt iStart;

   162         TInt iEnd;

   163     };

   164 

   165 // -----------------------------------------------------------------------------

   166 // Constant

   167 // -----------------------------------------------------------------------------

   168 

   169 // CONSTANTS

   170 

   171 // Animation value UID

   172 const TInt KAknsAlValueConstantUID = 0x10207627;

   173 

   174 // Constants for parameter names

   175 _LIT( KAknsAlValueConstantValue, "c" );

   176 

   177 // CLASS DECLARATION

   178 /**

   179 * Implements a constant value that cannot be changed by ticking (but by

   180 * reparametrizing can).

   181 *

   182 * @since 3.0

   183 */

   184 NONSHARABLE_CLASS( CAknsAlValueConstant ):

   185     public CBase, public MAknsAlAnimationValue

   186     {

   187     protected: // Protected constructors

   188         CAknsAlValueConstant();

   189 

   190     public:

   191         static CAknsAlValueConstant* NewL();

   192         virtual ~CAknsAlValueConstant();

   193 

   194     public: // Implementation of MAknsAlAnimationValue

   195         void Tick( TUint32 aDeltaTime, TUint32 aRelative );

   196 

   197         /**

   198         * Fills the data with the constant value (integer).

   199         */

   200         void FillData( TAknsRlParameterData& aData ) const;

   201 

   202         /**

   203         * Accepted named parameter:

   204         * - "c", integer, range [MIN_INT, MAX_INT], constant value

   205         *

   206         * The default parameter value is:

   207         * - "c" = 0

   208         */

   209         void SetParametersL( MAknsRlParameterIterator& aParameters );

   210         void Begin();

   211 

   212     private:

   213         TInt iValue;

   214     };

   215 

   216 // -----------------------------------------------------------------------------

   217 // Random

   218 // -----------------------------------------------------------------------------

   219 

   220 // CONSTANTS

   221 

   222 // Animation value UID

   223 const TInt KAknsAlValueRandomUID = 0x10207628;

   224 

   225 // Constants for parameter names

   226 _LIT( KAknsAlValueRandomMin, "min" );

   227 _LIT( KAknsAlValueRandomMax, "max" );

   228 

   229 // CLASS DECLARATION

   230 /**

   231 * Implements random animation value. Resulting random values are in range [min,

   232 * max]. User::TickCount is used for generating the random seed.

   233 *

   234 * @since 3.0

   235 */

   236 NONSHARABLE_CLASS( CAknsAlValueRandom ):

   237     public CBase, public MAknsAlAnimationValue

   238     {

   239     protected: // Protected constructors

   240         CAknsAlValueRandom();

   241 

   242     public:

   243         static CAknsAlValueRandom* NewL();

   244         virtual ~CAknsAlValueRandom();

   245 

   246     public: // Implementation of MAknsAlAnimationValue

   247         void Tick( TUint32 aDeltaTime, TUint32 aRelative );

   248 

   249         /**

   250         * Fills the data with the current random value (integer).

   251         */

   252         void FillData( TAknsRlParameterData& aData ) const;

   253 

   254         /**

   255         * Accepted named parameters:

   256         * - "min", integer, range [MIN_INT, MAX_INT], range start value

   257         * - "max", integer, range [MIN_INT, MAX_INT], range end value

   258         *

   259         * Random values are generated in range [min, max]. Min must be <= max,

   260         * otherwise parametrization will leave.

   261         *

   262         * The default parameter values are:

   263         * - "min" = 0

   264         * - "max" = 255

   265         */

   266         void SetParametersL( MAknsRlParameterIterator& aParameters );

   267         void Begin();

   268 

   269     private:

   270         TInt64 iCurrentSeed;

   271         TInt iValue;

   272         TInt iMin;

   273         TInt iMax;

   274     };

   275 

   276 // -----------------------------------------------------------------------------

   277 // Poly line 1D

   278 // -----------------------------------------------------------------------------

   279 

   280 // CONSTANTS

   281 

   282 // Animation value UID

   283 const TInt KAknsAlValuePoly1DUID = 0x10207629;

   284 

   285 // Constants for parameter names

   286 _LIT( KAknsAlValuePoly1DPoints, "p" );

   287 _LIT( KAknsAlValuePoly1DFactor, "f" );

   288 

   289 // CLASS DECLARATION

   290 /**

   291 * Implements one dimensional polyline as a segmented function on xy-plane.

   292 * Relative value defines the position on x axis and the polyline defines the y

   293 * for each x.

   294 *

   295 * @since 3.0

   296 */

   297 NONSHARABLE_CLASS( CAknsAlValuePoly1D ):

   298     public CBase, public MAknsAlAnimationValue

   299     {

   300     protected: // Protected constructors

   301         CAknsAlValuePoly1D();

   302         void ConstructL();

   303 

   304     public:

   305         static CAknsAlValuePoly1D* NewL();

   306         virtual ~CAknsAlValuePoly1D();

   307 

   308     public: // Implementation of MAknsAlAnimationValue

   309         void Tick( TUint32 aDeltaTime, TUint32 aRelative );

   310 

   311         /**

   312         * Fills the data with the current value (integer).

   313         */

   314         void FillData( TAknsRlParameterData& aData ) const;

   315 

   316         /**

   317         * Accepted named parameters:

   318         * - "p", descriptor/string, contains polyline points

   319         * - "f", integer, the factor used for scaling the polyline results

   320         *

   321         * Descriptor "p" contains (x,y) pairs that define the polyline

   322         * segments. Polyline is not closed (no segment between the first and

   323         * last points). Coordinates are interpreted as 16-bit values that map

   324         * to floating point range [0, 1].

   325         *

   326         * Input descriptor "p" must fulfil the next constraints:

   327         * - Length must be even (divisible with 2)

   328         * - p[n] < p[n+2] must hold, where n is an even integer (yields x

   329         *   coordinates, odd integers index y coordinates).

   330         *

   331         * Factor "f" defines the range of resulting values, hence the resulting

   332         * values are in range [0, f]. Factor "f" must be >= 0.

   333         *

   334         * The default parameter values are:

   335         * - "p" = empty

   336         * - "f" = 1

   337         */

   338         void SetParametersL( MAknsRlParameterIterator& aParameters );

   339         void Begin();

   340 

   341     private:

   342         TInt iValue;

   343         // The numeric implementation of polyline, owned

   344         CAknsAlPolyLine1D* iPoly;

   345     };

   346 

   347 // -----------------------------------------------------------------------------

   348 // Poly line 2D

   349 // -----------------------------------------------------------------------------

   350 

   351 // CONSTANTS

   352 

   353 // Animation value UID

   354 const TInt KAknsAlValuePoly2DUID = 0x1020762A;

   355 

   356 // Constants for parameter names

   357 _LIT( KAknsAlValuePoly2DPoints, "p" );

   358 _LIT( KAknsAlValuePoly2DFactor, "f" );

   359 

   360 // CLASS DECLARATION

   361 /**

   362 * Implements 2D polyline xy-plane. Relative value defines the position on the

   363 * length of polyline.

   364 *

   365 * @since 3.0

   366 */

   367 NONSHARABLE_CLASS( CAknsAlValuePoly2D ):

   368     public CBase, public MAknsAlAnimationValue

   369     {

   370     protected: // Protected constructors

   371         CAknsAlValuePoly2D();

   372         void ConstructL();

   373 

   374     public:

   375         static CAknsAlValuePoly2D* NewL();

   376         virtual ~CAknsAlValuePoly2D();

   377 

   378     public: // Implementation of MAknsAlAnimationValue

   379         void Tick( TUint32 aDeltaTime, TUint32 aRelative );

   380 

   381         /**

   382         * Fills the data with the current spline point. It is a two element

   383         * 16-bit descriptor containing point (x,y), string. First element

   384         * contains the value x, second element contains the value y.

   385         */

   386         void FillData( TAknsRlParameterData& aData ) const;

   387 

   388         /**

   389         * Accepted named parameters:

   390         * - "p", descriptor/string, contains polyline points

   391         * - "f", descriptor, the factors used for scaling the polyline results

   392         *

   393         * Descriptor "p" contains (x,y) pairs that define the polyline

   394         * segments. Polyline is not closed (no segment between the first and

   395         * last points). Coordinates are interpreted as 16-bit values that map

   396         * to floating point range [0, 1]. The number of coordinates must be

   397         * even (divisible with 2)

   398         *

   399         * Factor "f" defines the range of resulting values, hence the resulting

   400         * values are in range [fx, fy], where fx >= 0 and fy >= 0. The first

   401         * descriptor value is considered "fx", the second "fy", the rest is

   402         * omitted. At least 2 values must be available.

   403         *

   404         * The default parameter values are:

   405         * - "p" = empty

   406         * - "f" = (1, 1)

   407         */

   408         void SetParametersL( MAknsRlParameterIterator& aParameters );

   409         void Begin();

   410 

   411     private:

   412         TBuf16<2> iValue;

   413         // The numeric implementation of polyline, owned

   414         CAknsAlPolyLine* iPoly;

   415     };

   416 

   417 #endif // AKNSALANIMATIONVALUE_H

   418 

   419 // End of File