1 /*

     2 * Copyright (c)  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:  CMmGrid declaration

    15 *  Version     : %version: MM_32.1.22 % << Don't touch! Updated by Synergy at check-out.

    16 *

    17 */

    18 

    19 

    20 #ifndef C_MMGRID_H

    21 #define C_MMGRID_H

    22 

    23 #include <e32std.h>

    24 #include <e32base.h>

    25 #include <AknGrid.h> 

    26 

    27 class CMmGridModel;

    28 class CMmListBoxItemDrawer;

    29 class CMmMarqueeAdapter;

    30 class CMmWidgetContainer;

    31 class CMmTemplateLibrary;

    32 

    33 /**

    34  *  Multimedia Menu Grid Widget

    35  * 

    36  *  @code

    37  *  @endcode

    38  *  @lib mmwidgets

    39  *  @since S60 v3.0

    40  *  @ingroup group_mmwidgets

    41  */

    42 NONSHARABLE_CLASS( CMmGrid ) : public CAknGrid

    43     {

    44 public:

    45     

    46     /**

    47      * Two-phased constructor.

    48      * 

    49      * @param aParent Parent control.

    50      * @param aFlags Additional Flags.

    51      * @param aTemplateLibrary Template library for drawer.

    52      */

    53     static CMmGrid* NewL( const CCoeControl* aParent, TInt aFlags,

    54         CMmTemplateLibrary* aTemplateLibrary );

    55     

    56     /**

    57      * Two-phased constructor.

    58      * 

    59      * @param aParent Parent control.

    60      * @param aFlags Additional Flags.

    61      * @param aTemplateLibrary Template library for drawer.

    62      */

    63     static CMmGrid* NewLC(const CCoeControl* aParent, TInt aFlags,

    64         CMmTemplateLibrary* aTemplateLibrary );

    65     

    66     /**

    67      * Destructor.

    68      */

    69     virtual ~CMmGrid();

    70 

    71     /**

    72      * Draws the grid is given rectangle.

    73      *

    74      * @since S60 v3.0

    75      * @param aRect Rect within which grid should be drawn.

    76      */

    77     void Draw( const TRect& aRect ) const;

    78     

    79     /**

    80      * Draws the grid view.

    81      *

    82      * @since S60 v5.0

    83      */

    84     void DrawView();

    85 

    86     /**

    87      * Creates the item drawer for grid.

    88      * 

    89      * @since S60 v3.0

    90      */

    91     void CreateItemDrawerL();

    92     

    93     /**

    94      * Creates the item drawer for grid.

    95      * 

    96      * @param aTemplateLibrary Template library for drawer. 

    97      * @since S60 v3.0

    98      */

    99     void CreateItemDrawerL( CMmTemplateLibrary* aTemplateLibrary );

   100     

   101     /**

   102      * Creates the view class instance for grid.

   103      *

   104      * @since S60 v3.0

   105      * @return Griv view.

   106      */

   107     CListBoxView* MakeViewClassInstanceL();

   108     

   109     /**

   110      * Handles scrolling event.

   111      *

   112      * @since S60 v3.0

   113      * @param aScrollBar Scrollbar being scrolled.

   114      * @param aEventType Type of scrollbar event.

   115      */

   116     void HandleScrollEventL( CEikScrollBar* aScrollBar, 

   117             TEikScrollEvent aEventType );

   118     

   119     /**

   120      * Handles pointer event.

   121      *

   122      * @since S60 v3.0

   123      * @param aPointerEvent Type of pointer event.

   124      */

   125     void HandlePointerEventL( const TPointerEvent& aPointerEvent );

   126      

   127     /**

   128      * Sets item drawer and view background context.

   129      *

   130      * @since S60 v3.0

   131      * @param aBgContext Background context to be set in view and item drawer.

   132      */

   133     void SetItemDrawerAndViewBgContext(

   134     		CAknsBasicBackgroundControlContext* aBgContext );

   135     

   136     /**

   137      * Handles changes in scrollbar visibility.

   138      *

   139      * @since S60 v3.0

   140      */

   141     TBool HandleScrollbarVisibilityChangeL();

   142     

   143     /**

   144      * Checks if all items from model fit in given rectangle.

   145      *

   146      * @since S60 v3.0

   147      * @return Do items fit in view rectangle.

   148      */

   149     TBool AllItemsFitInViewRect();

   150     

   151     /**

   152      * Updates scrollbar changes.

   153      *

   154      * @since S60 v3.0

   155      */

   156     void UpdateScrollBarsL();

   157     

   158     /**

   159      * Sets the marquee adapter.

   160      *

   161      * @since S60 v3.0

   162      * @param aAdapter Marquee adapter.

   163      */

   164     void SetMarqueeAdapter( CMmMarqueeAdapter* aAdapter );

   165     

   166     /**

   167      * Sets up the layout (orientation and items' sizes).

   168      *

   169      * @since S60 v3.0

   170      */

   171     void SetupLayout();

   172 

   173     /**

   174      * Gets the Grid model.

   175      *

   176      * @since S60 v3.0

   177      * @return Grid model.

   178      */       

   179     CMmGridModel * MmModel();

   180     

   181     /**

   182      * This function from @c CAknGrid handles key events.

   183      *  

   184      * It has been overridden to allow for correct handling of

   185      * left and right rocker keys when mirrored layout is used.

   186      * 

   187      * @param aKeyEvent event to handle

   188      * @param aType type of the key event

   189      * @return response code ( @c EKeyWasConsumed, @c EKeyWasNotConsumed )

   190      */

   191     TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);

   192     

   193     /**

   194      * This function from CAknGrid is overriden to make grid 

   195      * behavior correct in the mirrored layout.

   196      * Please note that it is necessary because of the hackish

   197      * solution used to draw items in mirrored layout.

   198      */

   199     void HandleViewRectSizeChangeL();

   200     

   201     /**

   202      * Overridden function from CAknGrid.

   203      */

   204     void AdjustTopItemIndex() const;

   205 

   206     /**

   207      * Set the vertical item offset;

   208      * @param aOffset The offset to set to the widget.

   209      * 

   210      * @since S60 v5.0

   211      */

   212     void SetVerticalItemOffset( TInt aOffset );

   213 

   214     /**

   215      * Gets the current widget vertical item offset.

   216      * 

   217      * @since S60 v5.0

   218      * @return The current widget vertical item offset.

   219      */

   220     TInt VerticalItemOffset() const;

   221     

   222     /**

   223      * Simply sets the item height members in widget and view.

   224      */

   225     void SetItemHeight( TInt aItemHeight );

   226 

   227     /**

   228      * Updates scrollbar thumbs.

   229      */

   230     void UpdateScrollBarThumbs();

   231 

   232     /**

   233      * Counts the number of component controls which this component owns.

   234      */ 

   235     TInt CountComponentControls() const;

   236 

   237     /**

   238      * Disables/enables child component (scrollbar) drawing.

   239      */

   240     void SetDisableChildComponentDrawing( TBool aDisable );

   241     

   242 private:

   243     /**

   244      * Default constructor.

   245      * 

   246      * @since S60 v3.0 

   247      */

   248     CMmGrid();

   249     

   250     /**

   251      * 2nd phase constructor.

   252      * 

   253      * @since S60 v3.0 

   254      * @param aParent Parent control.

   255      * @param aFlags Additional Flags.

   256      * @param aTemplateLibrary Template library for drawer.

   257      */

   258     void ConstructL( const CCoeControl* aParent, TInt aFlags,

   259         CMmTemplateLibrary* aTemplateLibrary );

   260     

   261     /**

   262      * Handles changes in resource.

   263      *

   264      * @since S60 v3.0

   265      * @param aIsLandscape Is orientation in landscape mode.

   266      * @param aCellSize The size of grid cell/item.

   267      * @param aViewLayout The layout of the grid (e.g. 3x4).

   268      */

   269     void DoHandleResourceChangeL( TBool aIsLandscape, TSize& aCellSize,

   270             TSize& aViewLayout );

   271     

   272     /**

   273      * Handles changes in resource.

   274      *

   275      * @since S60 v3.0

   276      * @param aCellSize The size of grid cell/item.

   277      * @param aViewLayout The layout of the grid (e.g. 3x4).

   278      */

   279     void DoHandleResourceChangeL( TSize& aCellSize,

   280             TSize& aViewLayout );

   281     

   282     /**

   283      * Sets up the layout (for use in non-leaving SetupLayout())

   284      * 

   285      * @since S60 v3.0 

   286      */

   287     void DoSetupLayoutL();

   288     

   289     /**

   290      * Handles pointer events when edit mode is enabled.

   291      * 

   292      * This method is only called during edit mode. It selectively passes

   293      * only some of the pointer events to CAknGrid::HandlePointerEventL

   294      * in order to disable flicking and panning.

   295      * 

   296      * @param aPointerEvent pointer event

   297      */

   298     void HandlePointerEventInEditModeL( const TPointerEvent& aPointerEvent );

   299     

   300     /**

   301      * Handles pointer events when edit mode is disabled.

   302      * 

   303      * @param aPointerEvent pointer event

   304      */

   305     void HandlePointerEventInNormalModeL( const TPointerEvent& aPointerEvent );

   306     

   307     /**

   308      * Handles button repeat event in normal mode.

   309      * 

   310      * Such event is requested when handling button1down event so that

   311      * certain actions (i.e. setting highlight visibility) can be made

   312      * with a small delay - this improves menu behavior on flicking.

   313      * 

   314      * @param aPointerEvent pointer event 

   315      */

   316     void HandleButtonRepeatEventInNormalModeL( const TPointerEvent& aPointerEvent );

   317     

   318     /**

   319      * Scrolls the view if pointer is close to the top/bottom edge.

   320      * 

   321      * This method is used only when edit mode is active. In a way it

   322      * brings back the focus based scrolling behavior that was present

   323      * in CAknGrid before ODE scrolling was introduced.

   324      */

   325     void HandleScrollingInEditMode( const TPointerEvent& aPointerEvent );

   326     

   327     /**

   328      * Checks if pointer position is within the scroll-triggering area.

   329      * 

   330      * @param aPointerEvent pointer event

   331      * @return true if pointer above the top scrolling threshold.

   332      */

   333     TBool IsPointerInTopScrollingThreshold(

   334             const TPointerEvent& aPointerEvent ) const;

   335 

   336     /**

   337      * Checks if pointer position is within the scroll-triggering area.

   338      * 

   339      * @param aPointerEvent pointer event

   340      * @return true if pointer below the bottom scrolling threshold.

   341      */

   342     TBool IsPointerInBottomScrollingThreshold(

   343             const TPointerEvent& aPointerEvent ) const;

   344     

   345     /**

   346      * Scrolls the view if the pointer is near top/bottom edge of the screen.

   347      * 

   348      * Assumes that current item index is the index of the item under the

   349      * pointer. The time value returned is based on the distance of the pointer

   350      * from the top/bottom edge of the grid view (this makes the scrolling speed

   351      * dependent of how close the pointer is to the edge).

   352      * If there is no need to continue scrolling because the beginning/end of

   353      * the list has already been reached, 0 is returned.

   354      * 

   355      * @param aPointerEvent pointer event

   356      * @return time to wait before calling this method again (in microseconds)

   357      *         or 0 if already at the beginning/end of the list

   358      */

   359     TInt ScrollIfNeeded( const TPointerEvent& aPointerEvent );

   360     

   361     /**

   362      * Minimal scrolling (setting top item index and vertical offset) with 

   363      * boundary checking and WITHOUT redrawing.

   364      * 

   365      * @param aDistanceInPixels Distance to scroll.

   366      */

   367     void ScrollWithoutRedraw( TInt aDistanceInPixels );

   368     

   369     /**

   370      * Updates the dispapearing highlight.

   371      *

   372      * @since S60 v3.0

   373      * @param aPointerEvent Type of pointer event.

   374      */

   375     void HandleOverridenHighlightDrawing( const TPointerEvent& aPointerEvent,

   376     		TInt aIndexBefore, TInt aIndexAfter );

   377 

   378     /**

   379      * Ensures that elements are drawn correctly when mirrored layout is

   380      * used and scrollbar is visible by shifting ViewRect to the right.

   381      * Also disabled background drawing for scrollbar as it would not

   382      * be drawn correctly in mirrored layout.

   383      */

   384     void FixViewForMirroredLayout();

   385     

   386     /**

   387      * Gets the offset margin of scrollbar related to view rectangle.

   388      * 

   389      * @return The distance from view rect side to scrollbar.

   390      */

   391     TInt ScrollBarOffset();

   392     

   393     /**

   394      * Redraws the background under the vertical scrollbar in mirrored layout.

   395      * 

   396      * The reason such method is needed is that view rectangle is shifted

   397      * to the right in mirrored layout and does not cover the scrollbar

   398      * area. In normal (non-mirrored) mode this method does nothing.

   399      */

   400     void RedrawScrollbarBackground() const;

   401     

   402     /**

   403      * Does actual handling of scroll events.

   404      * 

   405      * @param aScrollBar Scrollbar being scrolled.

   406      * @param aEventType Type of scrollbar event.

   407      */

   408     void ProcessScrollEventL( CEikScrollBar* aScrollBar, 

   409             TEikScrollEvent aEventType );

   410     

   411     /**

   412      * Handles periodic events from @c iRedrawTimer.

   413      * Such events are generated at equal time intervals while

   414      * the view is being scrolled using the scrollbar.

   415      * This function typically calls @c ProcessScrollEventL,

   416      * which actually scrolls the view and causes a redraw. 

   417      */

   418     void HandleRedrawTimerEvent();

   419     

   420 private:

   421     /**

   422      * Callback function for @c iRedrawTimer.

   423      * It simply calls @c HandleRedrawTimerEvent and returns 0.

   424      * 

   425      * @param aPtr A pointer to CMmGrid object.

   426      * @return 0 (always).

   427      */

   428     static TInt RedrawTimerCallback( TAny* aPtr );

   429 

   430 private:

   431     /**

   432      * Grid model.

   433      */            

   434     CMmGridModel* iMmModel;

   435     

   436     /**

   437      * Item drawer.

   438      */                

   439     CMmListBoxItemDrawer* iMmDrawer;

   440 

   441     /**

   442      * Marquee adapter.

   443      */                

   444     CMmMarqueeAdapter* iMarqueeAdapter;

   445     

   446     /**

   447      * Scrollbar visibility flag.

   448      */                

   449     TBool iScrollbarVisibilityChanged;

   450 

   451     /**

   452      * Item index which is current in grid.

   453      */            

   454     TInt iCurrentItemIndex;

   455     

   456     /**

   457      * Currently top view item index.

   458      */            

   459     TInt iCurrentTopItemIndex;

   460     

   461     /**

   462      * Layout of grid.

   463      */            

   464     TSize iViewLayout;

   465     

   466     /**

   467      * A flag that indicates that highlight is visible because

   468      * the user is pressing the screen (continuously) and that

   469      * highlight should remain visible only as long as the screen

   470      * is being pressed.    

   471      */

   472     TBool iHighlightVisibleUntilButton1Up;

   473 	

   474     /**

   475      * Blocks scrollbar drawing. When this flag is set scrollbars components

   476      * are blocked in the CountComponentControls() method;   

   477      */

   478     TBool iDisableChildComponentDrawing;

   479     

   480     /**

   481      * This member is only used in edit mode to store the position of the pointer

   482      * during EButton1Down event.

   483      */

   484     TPoint iButton1DownPos;

   485 

   486     /**

   487      * ETrue if the view is being scrolled with the scrollbar.

   488      */

   489     TBool iScrollbarThumbIsBeingDragged;

   490     

   491     /**

   492      * Stores the number of scrollbar events that were ignored.

   493      * It is only used while scrolling the view using scrollbar,

   494      * in such situation the scroll events that this object receives

   495      * are ignored, and actual scrolling is done only when

   496      * iRedrawTimer completes.

   497      */

   498     TInt iSkippedScrollbarEventsCount;

   499     

   500     /**

   501      * A timer that initiates redraws at certain time intervals.

   502      * It is used to refresh the view while scrolling with

   503      * the scrollbar.

   504      */

   505     CPeriodic* iRedrawTimer;

   506     };

   507 

   508 #endif // C_MMGRID_H