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.25 % << 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      * Scrolls the view if pointer is close to the top/bottom edge.

   309      *

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

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

   312      * in CAknGrid before ODE scrolling was introduced.

   313      */

   314     void HandleScrollingInEditMode( const TPointerEvent& aPointerEvent );

   315 

   316     /**

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

   318      *

   319      * @param aPointerEvent pointer event

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

   321      */

   322     TBool IsPointerInTopScrollingThreshold(

   323             const TPointerEvent& aPointerEvent ) const;

   324 

   325     /**

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

   327      *

   328      * @param aPointerEvent pointer event

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

   330      */

   331     TBool IsPointerInBottomScrollingThreshold(

   332             const TPointerEvent& aPointerEvent ) const;

   333 

   334     /**

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

   336      *

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

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

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

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

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

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

   343      *

   344      * @param aPointerEvent pointer event

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

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

   347      */

   348     TInt ScrollIfNeeded( const TPointerEvent& aPointerEvent );

   349 

   350     /**

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

   352      * boundary checking and WITHOUT redrawing.

   353      *

   354      * @param aDistanceInPixels Distance to scroll.

   355      */

   356     void ScrollWithoutRedraw( TInt aDistanceInPixels );

   357 

   358     /**

   359      * Updates the dispapearing highlight.

   360      *

   361      * @since S60 v3.0

   362      * @param aPointerEvent Type of pointer event.

   363      */

   364     void HandleOverridenHighlightDrawing( const TPointerEvent& aPointerEvent,

   365         TInt aIndexBefore, TInt aIndexAfter );

   366 

   367     /**

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

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

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

   371      * be drawn correctly in mirrored layout.

   372      */

   373     void FixViewForMirroredLayout();

   374 

   375     /**

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

   377      *

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

   379      */

   380     TInt ScrollBarOffset();

   381 

   382     /**

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

   384      *

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

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

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

   388      */

   389     void RedrawScrollbarBackground() const;

   390 

   391     /**

   392      * Does actual handling of scroll events.

   393      *

   394      * @param aScrollBar Scrollbar being scrolled.

   395      * @param aEventType Type of scrollbar event.

   396      */

   397     void ProcessScrollEventL( CEikScrollBar* aScrollBar,

   398             TEikScrollEvent aEventType );

   399 

   400     /**

   401      * Handles periodic events from @c iRedrawTimer.

   402      * Such events are generated at equal time intervals while

   403      * the view is being scrolled using the scrollbar.

   404      * This function typically calls @c ProcessScrollEventL,

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

   406      */

   407     void HandleRedrawTimerEventL();

   408 

   409 private:

   410     /**

   411      * Callback function for @c iRedrawTimer.

   412      * It simply calls @c HandleRedrawTimerEventL and returns 0.

   413      *

   414      * @param aPtr A pointer to CMmGrid object.

   415      * @return 0 (always).

   416      */

   417     static TInt RedrawTimerCallback( TAny* aPtr );

   418 

   419 private:

   420     /**

   421      * Grid model.

   422      */

   423     CMmGridModel* iMmModel;

   424 

   425     /**

   426      * Item drawer.

   427      */

   428     CMmListBoxItemDrawer* iMmDrawer;

   429 

   430     /**

   431      * Marquee adapter.

   432      */

   433     CMmMarqueeAdapter* iMarqueeAdapter;

   434 

   435     /**

   436      * Scrollbar visibility flag.

   437      */

   438     TBool iScrollbarVisibilityChanged;

   439 

   440     /**

   441      * Item index which is current in grid.

   442      */

   443     TInt iCurrentItemIndex;

   444 

   445     /**

   446      * Currently top view item index.

   447      */

   448     TInt iCurrentTopItemIndex;

   449 

   450     /**

   451      * Layout of grid.

   452      */

   453     TSize iViewLayout;

   454 

   455     /**

   456      * A flag that indicates that highlight is visible because

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

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

   459      * is being pressed.

   460      */

   461     TBool iHighlightVisibleUntilButton1Up;

   462 

   463     /**

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

   465      * are blocked in the CountComponentControls() method;

   466      */

   467     TBool iDisableChildComponentDrawing;

   468 

   469     /**

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

   471      * during EButton1Down event.

   472      */

   473     TPoint iButton1DownPos;

   474 

   475     /**

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

   477      */

   478     TBool iScrollbarThumbIsBeingDragged;

   479 

   480     /**

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

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

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

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

   485      * iRedrawTimer completes.

   486      */

   487     TInt iSkippedScrollbarEventsCount;

   488 

   489     /**

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

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

   492      * the scrollbar.

   493      */

   494     CPeriodic* iRedrawTimer;

   495     };

   496 

   497 #endif // C_MMGRID_H