1 /*

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

    15 *

    16 */

    17 

    18 

    19 #ifndef T_MMFLOATINGITEM_H

    20 #define T_MMFLOATINGITEM_H

    21 

    22 #include <e32std.h>

    23 #include <e32base.h>

    24 #include "mmwidgetsconstants.h"

    25 

    26 

    27 /**

    28  * Floating item.

    29  * 

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

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

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

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

    34  * standard place. Together with CMMDrawerAnimator, these classes support

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

    36  * frames.

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

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

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

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

    41  * control the state of all instances of TMMFloatingItem.

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

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

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

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

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

    47  * by a floating item.

    48  * 

    49  * @see CMMDrawerAnimator

    50  * @lib mmwidgets

    51  * @since S60 v5.0

    52  * @ingroup group_mmwidgets

    53  */

    54 

    55 class CListBoxView;

    56 

    57 class TMmFloatingItem

    58     {

    59     

    60 public:

    61     /**

    62      * Constructor.

    63      * 

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

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

    66      * just like all the non-floating items.

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

    68      * not change when the view is scrolled. 

    69      *

    70      * @since S60 ?S60_version

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

    72      *                        be draw off place.

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

    74      *                       coordinates, even when creating an item with relative

    75      *                       position).

    76      * @param aType Type of the floating item.

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

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

    79      *        scrolling behavior).

    80      */

    81     TMmFloatingItem( TInt aDrawnIndex, TPoint aStartPosition,

    82             TMmFloatingItemType aType, TInt aAnimationFrames,

    83             CListBoxView* aView = NULL );

    84     

    85     /**

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

    87      * the floating item will not perfrom self removal. Normally

    88      * floating items remove themselves fram the drawing buffer whenever 

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

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

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

    92      *

    93      * @since S60 5.0

    94      * @param aManual Flag of manual deletion.

    95      */

    96     void SetManualDelete( TBool aManual );

    97     

    98     /**

    99      * Performs a step of the animation, according to 

   100      * earlier provided information.

   101      *

   102      * @since S60 5.0

   103      */

   104     TBool MakeStep();

   105        

   106     /**

   107      * Set the difference in the location of the floating item

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

   109      * position of the animation

   110      *

   111      * @since S60 5.0

   112      * @param aDiffetenceVector Vector of displacement.

   113      */

   114     void SetPositionStep( TPoint aDiffetenceVector  );

   115     

   116     /**

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

   118      * item with every step of the animation.

   119      *

   120      * @since S60 5.0

   121      * @param aStartSize Initial size of the item.

   122      * @param aFinalSize Final size of the item.

   123      */

   124     void SetSizeStep( TReal aStartSize, TReal aFinalSize );   

   125     

   126     /**

   127      * Gets the current zoom ratio. The ratio might by

   128      * time specific, since floating items support animations

   129      * changing size of the item.

   130      *

   131      * @since S60 5.0

   132      * @return Zooming ratio.

   133      */

   134     TReal GetCurrentZoomRatio() const;

   135     

   136     /**

   137      * Gets the type of the floating item.

   138      *

   139      * @since S60 5.0

   140      * @return Type of the floating item.

   141      */    

   142     TMmFloatingItemType GetFloatingItemType() const;

   143 

   144     /**

   145      * Gets the item index of the item being drawn.

   146      *

   147      * @since S60 5.0

   148      * @return Item of the item drawn.

   149      */    

   150     TInt GetDrawnItemIndex() const;

   151     

   152     /**

   153      * Gets the current item position.

   154      * 

   155      * The position returned is always expressed in screen coordinates,

   156      * even if this item's position is relative.

   157      *

   158      * @since S60 5.0

   159      * @return Position of the item.

   160      */    

   161     TPoint GetItemPosition() const;

   162 

   163     /**

   164      * Marks the item as invalid. Item will be deleted 

   165      * from the cache when an attempt to draw the item

   166      * occurs.

   167      *

   168      * @since S60 5.0

   169      */    

   170     void InvalidateFloatingItem();

   171 

   172     /**

   173      * Tests if the item is still valid.

   174      *

   175      * @since S60 5.0

   176      */    

   177     TBool IsFloatingItemValid() const;

   178     

   179     /**

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

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

   182      * 

   183      * @since S60 5.0

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

   185      *         Positive value is returned if item is zooming in.

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

   187      */

   188     TInt GetZoomingStatus();

   189     

   190     /**

   191      * Checks if the item has the manual deletion

   192      * flag setup.

   193      *

   194      * @since S60 5.0

   195      * @return The status of manual deletion flag.

   196      */    

   197     TBool IsManualDelete();

   198     

   199     /**

   200      * Calculates consequent steps

   201      *

   202      * @since S60 5.0

   203      * @param aVector Displacement vector.

   204      */    

   205     void CalculateSteps(TPoint aVector);

   206     

   207 private:

   208     

   209     /**

   210      * Index of the item, which is being animated. 

   211      */  

   212     TInt iDrawnItemIndex;

   213     

   214     /**

   215      * Current item position.

   216      * 

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

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

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

   220      * first item in the view.

   221      */  

   222     TPoint iItemPosition;

   223     

   224     /**

   225      * Dispalcement of the item, per animation step.

   226      */  

   227     TFixedArray<TPoint, MmEffects::KMaximumAnimationFramesCount> iPositionStep;

   228     

   229     /**

   230      * Size change, per animation step.

   231      */  

   232     TReal iSizeStep;

   233     

   234     /**

   235      * Counter of animation frames.

   236      */  

   237     TInt iFrameCounter;

   238     

   239     /**

   240      * Total number of animation frames to perform.

   241      */  

   242     TInt iFrames;

   243     

   244     /**

   245      * Manual deletion flag.

   246      */  

   247     TBool iManualDelete;

   248     

   249     /**

   250      * Current scaling ratio.

   251      */  

   252     TReal iZoomRatio;

   253     

   254     /**

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

   256      * between different animations types.

   257      */  

   258     TMmFloatingItemType iType; 

   259     

   260     /**

   261      * The view on which items are drawn.

   262      * 

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

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

   265      * corner of the first item in the view. 

   266      */

   267     CListBoxView* iView;

   268        

   269     };

   270     

   271 #endif // T_MMFLOATINGITEM_H