/*

* Copyright (c) 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:  floating item

*

*/

#ifndef T_MMFLOATINGITEM_H

#define T_MMFLOATINGITEM_H

#include <e32std.h>

#include <e32base.h>

#include "mmwidgetsconstants.h"

/**

 * Floating item.

 * 

 * This class describes a floating item element. Floating item is an extension

 * to the way grid and list widgets are drawn. Since widgets are very restrictive,

 * as to the place where na item is drawn (since in both grid and list each item

 * has a pretty well defined place) there had to be a way to draw items off the

 * standard place. Together with CMMDrawerAnimator, these classes support

 * drawing of dragged item as well as other off place items such as animation 

 * frames.

 * Floating items as such support the idea of animation, as each of the items

 * are aware of the animation step, and may modify its own position, whenever

 * requested. However a timer in this manner is needed, and this role is 

 * performed by CMMDrawerAnimator, which is aware of the redraw speed, and may

 * control the state of all instances of TMMFloatingItem.

 * It should be noted that both TMMFloatingItem and CMMDrawerAnimator doesn't 

 * handle item's drawing on it's own. These classes just control the logical 

 * state of floating items. All floating items are associated with the 

 * CMMListBoxItemDrawer in an array, and drawn whenever a Draw operation is 

 * performed on the widget, or any particular item, that is in any way overlapped

 * by a floating item.

 * 

 * @see CMMDrawerAnimator

 * @lib mmwidgets

 * @since S60 v5.0

 * @ingroup group_mmwidgets

 */

class CListBoxView;

class TMmFloatingItem

    {

public:

    /**

     * Constructor.

     * 

     * If a non-null value for the aView parameter is supplied, then item position

     * will be relative, so when the view is scrolled the floating item will move

     * just like all the non-floating items.

     * If aView is NULL, then item position will be absolute, meaning that it will

     * not change when the view is scrolled. 

     *

     * @since S60 ?S60_version

     * @param aDrawnIndex Index of the item which is going to 

     *                        be draw off place.

     * @param aStartPosition Position of the item (always expressed in screen

     *                       coordinates, even when creating an item with relative

     *                       position).

     * @param aType Type of the floating item.

     * @param aAnimationFrames Total number of animation frames to perform.

     * @param aView The view on which items are drawn (optional - affects

     *        scrolling behavior).

     */

    TMmFloatingItem( TInt aDrawnIndex, TPoint aStartPosition,

            TMmFloatingItemType aType, TInt aAnimationFrames,

            CListBoxView* aView = NULL );

    /**

     * Sets the flag of manual delete. If such flag is set

     * the floating item will not perfrom self removal. Normally

     * floating items remove themselves fram the drawing buffer whenever 

     * the animation is finished. This is used for example for

     * dragged items, since they are not animated, and they will be

     * deleted manual when the uses lets go of the drag.

     *

     * @since S60 5.0

     * @param aManual Flag of manual deletion.

     */

    void SetManualDelete( TBool aManual );

    /**

     * Performs a step of the animation, according to 

     * earlier provided information.

     *

     * @since S60 5.0

     */

    TBool MakeStep();

    /**

     * Set the difference in the location of the floating item

     * from the originating position of the item, to the resulting

     * position of the animation

     *

     * @since S60 5.0

     * @param aDiffetenceVector Vector of displacement.

     */

    void SetPositionStep( TPoint aDiffetenceVector  );

    /**

     * Set the size of the step that modifies the size of the

     * item with every step of the animation.

     *

     * @since S60 5.0

     * @param aStartSize Initial size of the item.

     * @param aFinalSize Final size of the item.

     */

    void SetSizeStep( TReal aStartSize, TReal aFinalSize );   

    /**

     * Gets the current zoom ratio. The ratio might by

     * time specific, since floating items support animations

     * changing size of the item.

     *

     * @since S60 5.0

     * @return Zooming ratio.

     */

    TReal GetCurrentZoomRatio() const;

    /**

     * Gets the type of the floating item.

     *

     * @since S60 5.0

     * @return Type of the floating item.

     */    

    TMmFloatingItemType GetFloatingItemType() const;

    /**

     * Gets the item index of the item being drawn.

     *

     * @since S60 5.0

     * @return Item of the item drawn.

     */    

    TInt GetDrawnItemIndex() const;

    /**

     * Gets the current item position.

     * 

     * The position returned is always expressed in screen coordinates,

     * even if this item's position is relative.

     *

     * @since S60 5.0

     * @return Position of the item.

     */    

    TPoint GetItemPosition() const;

    /**

     * Marks the item as invalid. Item will be deleted 

     * from the cache when an attempt to draw the item

     * occurs.

     *

     * @since S60 5.0

     */    

    void InvalidateFloatingItem();

    /**

     * Tests if the item is still valid.

     *

     * @since S60 5.0

     */    

    TBool IsFloatingItemValid() const;

    /**

     * Zooming status is returned, meaning if the item is still 

     * in the state of zoming in, zooming out, or in normal size

     * 

     * @since S60 5.0

     * @return Negative value is returned if the item is zooming out.

     *         Positive value is returned if item is zooming in.

     *         Zero is returned if the item is static in size.

     */

    TInt GetZoomingStatus();

    /**

     * Checks if the item has the manual deletion

     * flag setup.

     *

     * @since S60 5.0

     * @return The status of manual deletion flag.

     */    

    TBool IsManualDelete();

    /**

     * Calculates consequent steps

     *

     * @since S60 5.0

     * @param aVector Displacement vector.

     */    

    void CalculateSteps(TPoint aVector);

private:

    /**

     * Index of the item, which is being animated. 

     */  

    TInt iDrawnItemIndex;

    /**

     * Current item position.

     * 

     * This can be either an absolute position (expressed in screen coordinates) or

     * a relative position depending on whether iView member variable is NULL.

     * In the latter case, the position is relative to the top-left corner of the

     * first item in the view.

     */  

    TPoint iItemPosition;

    /**

     * Dispalcement of the item, per animation step.

     */  

    TFixedArray<TPoint, MmEffects::KMaximumAnimationFramesCount> iPositionStep;

    /**

     * Size change, per animation step.

     */  

    TReal iSizeStep;

    /**

     * Counter of animation frames.

     */  

    TInt iFrameCounter;

    /**

     * Total number of animation frames to perform.

     */  

    TInt iFrames;

    /**

     * Manual deletion flag.

     */  

    TBool iManualDelete;

    /**

     * Current scaling ratio.

     */  

    TReal iZoomRatio;

    /**

     * Type of the floating item. There is a need for distinction

     * between different animations types.

     */  

    TMmFloatingItemType iType; 

    /**

     * The view on which items are drawn.

     * 

     * When iView is NULL, then iItemPosition contains absolute item position.

     * Otherwise iItemPostion contains item position relative to the top-left

     * corner of the first item in the view. 

     */

    CListBoxView* iView;

    };

#endif // T_MMFLOATINGITEM_H