/*
* Copyright (c) 2006-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:   THuiInteractionInterval is a utility class that can be used 
*                as specify intervals that adapt to user input.
*
*/

 

#ifndef __HUIINTERACTIONINTERVAL_H__
#define __HUIINTERACTIONINTERVAL_H__


#include <e32base.h>


/**
 * THuiInteractionInterval is a utility class that can be used to determine
 * the correct animation interval time, while taking into account how much time has
 * elapsed since the last time the interval was determined. 
 *
 * An interaction interval is useful for example when animating a list selector. By default,
 * the time interval for moving between two items could be 500 ms, but if
 * the user moves faster than this, the selector's animation may be 
 * unnecessarily delayed. In this situation, the interaction interval would
 * shorten the time interval for the moving animation, if necessary, to keep
 * better in sync with how quickly the user is moving in the list.
 */
class THuiInteractionInterval 
    {
public:

    /* Constructors and destructor. */

    /**
     * Initializes the interaction interval.
     *
     * @param aScalar  Determines how strongly the interval adapts. 
     *
     * @see SetScalar()
     */
    IMPORT_C THuiInteractionInterval(TReal32 aScalar = 2.0f) __SOFTFP;


    /* Methods. */

    /**
     * Sets the adaptation scalar. Determines how strongly the interval
     * will adapt to the elapsed time since the last evaluation.
     *
     * For example, 1.0 would mean that the maximum interval time is the 
     * time elapsed between the current evaluation and the
     * previous one. In this case, when the animation frequency 
     * stays the same, each sequence would have time to complete
     * before the next sequence begins. When the scalar is 2.0, the
     * maximum is twice the elapsed time, meaning that the 
     * ongoing animation sequence would always be finished halfway 
     * when the next sequence begins. This produces a smoother
     * end result.
     *
     * @param aScalar  New adaptation scalar.
     */
    IMPORT_C void SetScalar(TReal32 aScalar) __SOFTFP;
    
    /**
     * Returns the current adapation scalar.
     *
     * @return Adaptation scalar.
     */
    IMPORT_C TReal32 Scalar() const __SOFTFP;

    /**
     * Evaluates the current interval. The evaluated interval will always 
     * be at least as large as the elapsed time since the last evaluation, 
     * but at most <code>aIntervalTime</code>. 
     *
     * @param aIntervalTime  The requested normal interval time.
     *
     * @return  The evaluated interval, effective during the current frame.
     *
     * @see SetScalar()
     */
    IMPORT_C TInt Interval(TInt aIntervalTime);
    
    
private:

    /** Interval scalar. */
    TReal32 iScalar;
    
    /** Last time interaction interval was determined. */
    TUint32 iLastTimeMs;

    };


#endif  // __HUIINTERACTIONINTERVAL_H__