/*
* Copyright (c) 2004-2008 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:  Real-time timing model.
*
*/

#ifndef AKNSALTIMINGMODELREALTIME_H
#define AKNSALTIMINGMODELREALTIME_H

// INCLUDE FILES
#include "AknsAlTimingModel.h"

// CONSTANTS

// Timing model UID
const TInt KAknsAlTimingModelRealTimeUID = 0x10207624;

const TInt KAlMaxDurationVal = 65536; // In milliseconds, ~65 seconds

// Constants for parameter names
_LIT( KAknsAlRealTimeDuration, "d" );
_LIT( KAknsAlRealTimeRepeatCount, "rc" );
_LIT( KAknsAlRealTimeRepeatDuration, "rd" );
_LIT( KAknsAlRealTimeWrap, "w" );

// CLASS DECLARATION
/**
Real-time timing model that advances by keeping track on elapsed time between
subsequent updates. The next named parameters are supported:
- "d", duration
- "rc", repeat count
- "rd", repeat duration
- "w", wrap mode

Timing model configuration works as follows:

Duration undefined:
D    RC    RD     Single duration  Total duration
0    Inf   0      Inf              Inf
0    Inf   Def    RD               RD
0    Inf   Inf    Inf              Inf
0    0     0      0                0
0    0     Def    RD               RD
0    0     Inf    Inf              Inf
0    Def   0      0                0
0    Def   Def    RD               RD
0    Def   Inf    Inf              Inf

Duration defined:
D    RC    RD    Single duration   Total duration
Def  Inf   0     D                 Inf
Def  Inf   Def   D                 RD
Def  Inf   Inf   D                 Inf
Def  0     0     D                 D
Def  0     Def   D                 RD
Def  0     Inf   D                 Inf
Def  Def   0     D                 D * RC
Def  Def   Def   D                 MIN(D * RC, RD)
Def  Def   Inf   D                 D * RC

Duration infinite:
D    RC    RD    Single duration   Total duration
Inf  Inf   0     Inf               Inf
Inf  Inf   Def   RD                RD
Inf  Inf   Inf   Inf               Inf
Inf  0     0     Inf               Inf
Inf  0     Def   RD                RD
Inf  0     Inf   Inf               Inf
Inf  Def   0     Inf               Inf
Inf  Def   Def   RD                RD
Inf  Def   Inf   Inf               Inf

The above tables can reduced to:
    D    RC    RD    Single duration   Total duration
#1  0    *     Def   RD                RD
#2  0    *     Inf   Inf               Inf
#3  0    Inf   0     Inf               Inf
#4  0    0     0     0                 0
#5  0    Def   0     0                 0
#6  Def  Inf   0     D                 Inf
#7  Def  Inf   Def   D                 RD
#8  Def  Inf   Inf   D                 Inf
#9  Def  0     0     D                 D
#10 Def  0     Def   D                 RD
#11 Def  0     Inf   D                 Inf
#12 Def  Def   0     D                 D * RC
#13 Def  Def   Def   D                 MIN(D * RC, RD)
#14 Def  Def   Inf   D                 D * RC
#15 Inf  *     Def   RD                RD
#16 Inf  *     Inf   Inf               Inf
#17 Inf  *     0     Inf               Inf

Abbreviations used:
D   duration
RC  repeat count
RD  repeat duration
Def defined
0   undefined (zero in resulting durations)
Inf infinite
*   any value (defined, undefined, infinite)

Note: Case #3 follows SMIL, it could have been defined to produce the same
result as #4 and #5. Cases #4 and #5 could have been implemented as impossible
case that causes a leave. Current implementation just sets the total duration
to zero which produces an animation that finishes immediately.

Configuration value formats:
- Duration, repeat count and repeat duration are all defined as follows:
  < 0, value is infinite
    0, value is undefined
  > 0, value is defined
- Duration is milliseconds, when defined
- Repeat count is the number of repeated durations, when defined
- Repeat duration is milliseconds, when defined
- Because fixed point calculations are used, durations and repeat durations
  larger than KAlMaxDurationVal are clamped to KAlMaxDurationVal. It is
  possible to produce longer total durations by using repeat count.

Wrap:
If duration is repeated, wrapping defines how successive durations are mapped
to relative values ranges.
- If ETrue the sequence is wrapped [0,1][1,0][0,1]...
- If EFalse the sequence is tiled [0,1][0,1][0,1]...
- The default wrap mode is tiled. Wrapping is ignored if the duration is not
  repeated.

Relative value format:
- 32-bit unsigned integer, fixed point, 16.16 format.
- Relative value range [0, 65536] maps effectively to real number range [0, 1].
- Relative value is quaranteed to be in range [0, 65536].
- If animation duration is infinite the relative value is always 0.

@since 3.0
*/
NONSHARABLE_CLASS( CAknsAlTimingModelRealTime ): public MAknsAlTimingModel
    {
    public:

        static inline TBool Infinite( TInt aValue )
            {
            return ( aValue < 0 ? ETrue: EFalse );
            }

        static inline TBool Undefined( TInt aValue )
            {
            return ( aValue == 0 ? ETrue: EFalse );
            }

        static inline TBool Defined( TInt aValue )
            {
            return ( aValue > 0 ? ETrue: EFalse );
            }

    protected:
        CAknsAlTimingModelRealTime();

    public:
        static CAknsAlTimingModelRealTime* NewL();
        virtual ~CAknsAlTimingModelRealTime();

        TInt Duration() const;
        TInt TotalDuration() const;

    public: // Implementation of MAknsAlTimingModel

        /**
        * Supported named parameters are:
        * - "d", integer, duration
        * - "rc", integer, repeat count
        * - "rd", integer, repeat duration
        * - "w", boolean (0/1), wrap mode
        *
        * For documentation see the extensive class comment.
        *
        * Default parameter values are:
        * - "d" = 0
        * - "rc" = 0
        * - "rd" = 0
        * - "w" = EFalse (0)
        */
        void SetParametersL( MAknsRlParameterIterator& aParameters );
        /**
        * Advances the timing model by the provided delta time.
        */
        void Tick( const TInt aDeltaTime );
        /**
        * Timestamp based ticking is ignored.
        */
        void Tick( const TTime& aStamp );
        TUint32 RelativeValue() const;
        TBool IsFinished() const;
        void Begin();

    private:
        void Configure( TInt aD, TInt aRC, TInt aRD, TBool aWrap );

    private:

        /// The length of one active duration, in milliseconds
        TInt iDuration;

        /// The total animation length, in milliseconds
        TInt iTotalDuration;

        /// Elapsed time since the start of the animation, in milliseconds
        TInt iElapsedTime;

        /// The current relative value, fixed point 16.16 format.
        TUint32 iRelative;

        /// Used wrapping mode.
        TBool iWrap;
    };

#endif // AKNSALTIMINGMODELREALTIME_H

// End of File