1 akngrid.h

     1 /*

     2 * Copyright (c) 2002-2004 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  

    15 *     This is a concrete class for the handling of a grid. The class handles a

    16 *     rectangular grid arrangement of items held in any linear ordering i.e 

    17 *     cells ordered top to bottom and left, left to right and down etc.

    18 *

    19 *

    20 */

    21 

    22 

    23 #if !defined(__AKNGRID_H__)

    24 #define __AKNGRID_H__

    25 

    26 // INCLUDES

    27 #include <eiktxlbx.h>

    28 #include <eiklbv.h>

    29 #include <eikfrlbd.h>

    30 #include <eikfrlb.h>

    31 

    32 #include <AknGridM.h>

    33 #include <AknGridView.h>

    34 #include <Aknappui.h>

    35 

    36 // CLASS PREDEFINITIONS

    37 class CAknGridExtension;

    38 

    39 // CLASS DECLARATION

    40 

    41 /**

    42 *  Application grid handling class from Avkon.

    43 *  Provides support for ordering application grids items.

    44 *

    45 *  @since Series 60 0.9

    46 */

    47 class CAknGrid : public CEikListBox

    48     {

    49 private:// enums

    50     enum TIndicatorEvent

    51         {

    52         EMove,

    53         EChangeNumOfItems,

    54         EResize

    55         };

    56 public:

    57 

    58     /**

    59     * Base class default constructor.

    60     * @return A pointer to a new @c CAknGrid object.

    61     */

    62     IMPORT_C CAknGrid();

    63     

    64     /**

    65     * Destructor.

    66     */

    67     IMPORT_C virtual ~CAknGrid();

    68     

    69     /**

    70     * This function gives @c CAknGridM class pointer to @c CAknGrid class. 

    71     * Usually, the @c CAknGridM class object is instantiated automatically 

    72     * during the construction phase of the @c CAknGrid object. If an 

    73     * application programmer provides their own grid model class, the 

    74     * application programmer must instantiate their own grid model class object

    75     * and give it to the @c CAknGrid object using the @c SetModel function 

    76     * before calling the @c ConstructL/ConstructFromResourceL function.

    77     * @param aModel Pointer to @c CAknGridM class.

    78     */  

    79     IMPORT_C void SetModel(CAknGridM* aModel);

    80 

    81     /**

    82     * This is Symbian default constructor. The @c ConstructL function needs to

    83     * be called in case resource data is not used. If a leave occurs the 

    84     * framework generates a Symbian Leave code.

    85     * @param aPatent A CCoeControl pointer.

    86     * @param aFlags Parameter for @c CEikListBox constructor. If the 

    87     * parameter is missing default value is 0.

    88     */  

    89     IMPORT_C void ConstructL(const CCoeControl* aParent, TInt aFlags = 0);

    90 

    91     /**

    92     * The @c ConstructFromResourceL function needs to be called in case 

    93     * resource data is used. Usually, the @c CAknGridM class object is 

    94     * instantiated automatically during the construction phase of the 

    95     * @c CAknGrid object. If an application programmer provides their own grid

    96     * model class, the application programmer must instantiate their own grid 

    97     * model class object and give it to the @c CAknGrid object using the 

    98     * @c SetModel function before calling the 

    99     * @c ConstructL/ConstructFromResourceL function. If a leave occurs the 

   100     * framework generates a Symbian Leave code.

   101     * @param aReader Construct controls from resource file.

   102     */

   103     IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

   104 

   105     /**

   106     * Sets the orientation of the grid, either vertical or horizontal, the

   107     * ordering of the data and the size of the primary dimension of the

   108     * grid. The value for the parameter @c aNumOfItemsInPrimaryOrient must be

   109     * greater than zero since this determines the number of items (be it rows

   110     * or columns) in the primary orientation of the grid. If a leave occurs

   111     * the framework generates a Symbian Leave code.

   112     * @param aVerticalOrientation Items vertical orientation.

   113     * @param aLeftToRight @c ETrue left to right.

   114     * @param aTopToBottom @c ETrue top to bottom.

   115     * @param aNumOfItemsInPrimaryOrient Number of items in primary orient.  

   116     * @param aNumOfItemsInSecondaryOrient Number of items in Secondary orient.

   117     * @param aSizeOfItems Item size.

   118     * @param aWidthOfSpaceBetweenItems =0 Width of space between items.

   119     * @param aHeightOfSpaceBetweenItems =0 Height of space between items.

   120     */

   121     IMPORT_C void SetLayoutL(TBool aVerticalOrientation,

   122                              TBool aLeftToRight,

   123                              TBool aTopToBottom,

   124                              TInt aNumOfItemsInPrimaryOrient,

   125                              TInt aNumOfItemsInSecondaryOrient,

   126                              TSize aSizeOfItems,

   127                              TInt aWidthOfSpaceBetweenItems=0,

   128                              TInt aHeightOfSpaceBetweenItems=0);

   129 

   130     /**

   131     * Sets the layout from a resource. Layout includes orientation (either

   132     * vertical or horizontal), horizontal and vertical direction of numbering,

   133     * the number of items in the primary and secondary orientation, and the 

   134     * primary and secondary scrolling types. If a leave occurs the framework 

   135     * generates a Symbian Leave code.

   136     * @param aReader Constructs controls from a resource file. 

   137     */

   138     IMPORT_C void SetLayoutFromResourceL(TResourceReader& aReader);

   139 

   140     /**

   141     * Sets the movement of the cursor with respect to scrolling when the

   142     * end item in the current row or column, whichever is the primary

   143     * orientation of the data items, is encountered. The movement maybe

   144     * either stop, loop back to same row or column or move onto the

   145     * next logical data item in the sequence.

   146     * @param aScrollingType Items scrolling type enum definition.

   147     */

   148     IMPORT_C void SetPrimaryScrollingType(CAknGridView::TScrollingType aScrollingType);

   149     

   150     /** 

   151     * Sets the movement of the cursor with respect to scrolling when the

   152     * end item in the secondary dimension of the grid is encountered.

   153     * The movement maybe either stop, loop back back to same row or column

   154     * or move onto the next logical data item in the sequence.

   155     * @param aSecondaryScrolling Secondary scrolling type enum definition.

   156     */

   157     IMPORT_C void SetSecondaryScrollingType(CAknGridView::TScrollingType aSecondaryScrolling);

   158 

   159     /**

   160     * Sets the starting position of the data within the grid. A blank page 

   161     * cannot be accessed (since cannot move into empty cells) so  a totally 

   162     * blank page is the same as if the page never existed since the user 

   163     * cannot scroll into it. For this reason it is suggested that the start

   164     * position be no more than one page into the grid. If a leave occurs 

   165     * the framework generates a Symbian Leave code.

   166     * @param aGridStartPosition Parameter manipulate the grid's starting 

   167     * position.

   168     */

   169     IMPORT_C void SetStartPositionL(TPoint aGridStartPosition);

   170 

   171     /**

   172     * @c CurrentDataIndex retrieves the index of the selection. In grids, you 

   173     * should use this method instead of @c CEikListBox::CurrentItemIndex(), 

   174     * when you are manipulating data stored in the grid's @c ItemTextArray. 

   175     * While @c CurrentItemIndex() returns the same value as 

   176     * @c CurrentItemIndex() on most phones, there will be difference in some 

   177     * language variants where text reading/writing direction is different from 

   178     * left-to-right.

   179     * @return A current position of highlight.

   180     */

   181     IMPORT_C TInt CurrentDataIndex() const;

   182     

   183     /**

   184     * Moves the cursor to the required grid data index.

   185     * @param aDataIndex Data index value.

   186     */

   187     IMPORT_C void SetCurrentDataIndex(TInt aDataIndex);

   188 

   189     /**

   190     * The grid position function. Gives the data index by using grid's 

   191     * position. The position must be given from the top left corner. If 

   192     * the function returns -1 the item's position is invalid.

   193     * @param aGridPosition The data item's co-ordinate values. 

   194     * @return Activated item's index value.

   195     */

   196     IMPORT_C TInt IndexOfPosition(TPoint aGridPosition) const;

   197     

   198     /**

   199     * The grid position function. Gives the data item's co-ordinate values 

   200     * by using item's index value.

   201     * @param aItemIndex The data item's index value.   

   202     * @return @c TPoint co-ordinate values of active item.

   203     */

   204     IMPORT_C TPoint PositionAtIndex(TInt aItemIndex) const;

   205 

   206     /**

   207     * Item drawer. Gets the pointer to the grid class.

   208     * @return A pointer to @c CFormattedCellListBoxItemDrawer object.

   209     */

   210     IMPORT_C CFormattedCellListBoxItemDrawer* ItemDrawer() const;

   211 

   212     /**

   213     * Function sets a grid text to the data item. If a leave occurs the 

   214     * framework generates a Symbian Leave code.

   215     * @since Series S60 3.0

   216     * @param aText Descriptor parameter.

   217     */

   218     IMPORT_C void SetEmptyGridTextL(const TDesC& aText);

   219     

   220     /**

   221     * This function sets the empty grid text.

   222     * @return A pointer to the grid text descriptor.

   223     */

   224     inline const TDesC* EmptyGridText() const;

   225 

   226 public:

   227 

   228     /**

   229     * This function creates a new object and returns pointer to it. If the 

   230     * leave occurs the framework generates a Symbian Leave code.

   231     * @return A pointer to @c CListBoxView class.

   232     */

   233     IMPORT_C virtual CListBoxView* MakeViewClassInstanceL();

   234 

   235     /**

   236     * This function sets the column width of the grid. Column width cannot be 

   237     * set in a horizontal grid since the number of columns in the grid is 

   238     * defined by the initialising call to @c SetLayoutL. The column width 

   239     * cannot be larger than the width of the viewing rectangle.

   240     * @param aColumnWidth A parameter defines a width of the column.

   241     */

   242     IMPORT_C void SetColumnWidth(TInt aColumnWidth);

   243     

   244     /**

   245     * This function gives a width of the column.

   246     * @return A width of the column. 

   247     */

   248     IMPORT_C TInt ColumnWidth() const;

   249 

   250 public: //from CEikListBox

   251 

   252     /**

   253     * This function updates the scrollbars, including item position. This 

   254     * function is called when the size of the scrollbars or data changes. If 

   255     * the leave occurs the framework generates a Symbian Leave code.

   256     */

   257     IMPORT_C virtual void UpdateScrollBarsL();

   258     

   259     /**

   260     * This function should be called after one or more items have been added to

   261     * the grid. If a leave occurs the framework generates a Symbian Leave 

   262     * code.

   263     */  

   264     IMPORT_C void HandleItemAdditionL();

   265     

   266     /**

   267     * This function should be called after one or more items have been removed 

   268     * from the grid. If a leave occurs the framework generates a Symbian 

   269     * Leave code.

   270     */  

   271     IMPORT_C void HandleItemRemovalL();

   272     

   273     /**

   274     * This function is from @c CEikAppUi, handles key events. If a leave 

   275     * occurs the framework generates a Symbian Leave code.

   276     * @param aKeyEvent Event to handled.

   277     * @param aType of the key event.

   278     * @return Response code ( @c EKeyWasConsumed, @c EKeyWasNotConsumed )

   279     */  

   280     IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);

   281     

   282     /**

   283     * This function sets the row height of the grid. Row height cannot be set

   284     * in a vertical grid since the number of rows in the grid is defined by 

   285     * the initialising call to @c SetLayoutL. The row height cannot be larger 

   286     * than the height of the viewing rectangle. If a leave occurs the 

   287     * framework generates a Symbian Leave code. 

   288     * @param aHeight The height of the item's rows.

   289     */  

   290     IMPORT_C void SetItemHeightL(TInt aHeight);

   291     

   292     /**

   293     * This function handles size changes. This routine assumes that 

   294     * @c SetLayoutL has been called to set up the grid.

   295     */  

   296     IMPORT_C void SizeChanged();

   297     

   298     /**

   299     * This function creates a new object and returns pointer to 

   300     * @c CTextListBoxModel class.

   301     * @return A pointer to @c CTextListBoxModel object.

   302     */  

   303     IMPORT_C CTextListBoxModel* Model() const;

   304         

   305     /**

   306     * This function handles viewable rectangle.

   307     * @param aRect Rectangle parameter. 

   308     */  

   309     IMPORT_C void SetRect(const TRect& aRect);

   310     

   311     /**

   312     * This function is called when the grid's items, item's data and scroll 

   313     * bars has been changed. This implementation ensures that the current 

   314     * item is visible after resize. If a leave occurs the framework generates

   315     * a Symbian Leave code.

   316     */  

   317     IMPORT_C virtual void HandleViewRectSizeChangeL();

   318     

   319     /**

   320     * This function sets top item index.

   321     * @param aItemIndex Item index value.

   322     */  

   323     IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;

   324     

   325     /**

   326     * This function handles resource changes.

   327     * @since Series S60 2.6.

   328     * @param aType Message type.

   329     */  

   330     IMPORT_C virtual void HandleResourceChange(TInt aType);

   331     

   332     /**

   333     * Indicates whether the control should be redrawn now. If @c ENoDrawNow, 

   334     * the function has no immediately effect. EDrawNow redraw control 

   335     * immediately.

   336     * @since Series S60 3.0.

   337     */

   338     IMPORT_C void FocusChanged(TDrawNow aDrawNow);

   339 

   340 public: // From CCoeControl

   341     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   342 

   343 protected: // from CEikListBox

   344 

   345     /**

   346     * This function scroll horizontal by one column when the left/right scroll

   347     * arrows (i.e. the nudge buttons) are tapped.

   348     * @return A nudge value when the buttons are pressed.

   349     */

   350     IMPORT_C virtual TInt HorizontalNudgeValue() const;

   351     

   352     /**

   353     * This function gets the granularity for horizontal scrolls. The 

   354     * granularity is the minimum size of a horizontal move of the client area.

   355     * @return A grain size for horizontal scrolling in pixels. 

   356     */  

   357     IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;

   358     

   359     /**

   360     * This function called by various functions of this class to ensure that

   361     * the top item index is always a sane value. The implementation in 

   362     * @c CEikListBox tries to ensure the minimum amount of white space at the 

   363     * bottom of the list box. Note that this function does not affect the 

   364     * current item index.

   365     */  

   366     IMPORT_C virtual void AdjustTopItemIndex() const;

   367     

   368     /** 

   369     * This function handles drag events. If a leave occurs the framework 

   370     * generates a Symbian Leave code.

   371     * @param aPointerPos The position of the @c TPointerEvent for which this 

   372     * handler is invoked.

   373     */

   374     IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos);

   375 

   376     /** 

   377     * This function calculates the client area. This method is called by 

   378     * various functions of this class to recalculate the extent of the client

   379     * area from @c iViewRect. This implementation takes into account any 

   380     * rounding of the viewing rectangle made to fit a whole number of items.

   381     * @param aClientRect On return contains a size for the client area in 

   382     * pixels. 

   383     */

   384     IMPORT_C virtual void RestoreClientRectFromViewRect(TRect& aClientRect) const;

   385 

   386     /** 

   387     * This function rounds down the height of the rectangle (if necessary) so 

   388     * that only a whole number of items can be displayed inside the list box.

   389     * @param aRect Rectangle parameter.

   390     */

   391     IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(TRect& aRect) const;

   392 

   393     /**

   394     * Updates the position of grids scroll bars’ thumbs to reflect the vertical 

   395     * position of selector.

   396     */

   397     IMPORT_C virtual void UpdateScrollBarThumbs() const;

   398     

   399     /**

   400     * Gets a count of the component controls of this grid.

   401     * @return The number of component controls.

   402     */

   403     IMPORT_C virtual TInt CountComponentControls() const;

   404 

   405 protected:

   406 

   407     /**

   408     * Moves to the next or previous item on the grid. If a leave occurs the 

   409     * framework generates a Symbian Leave code.

   410     * @param aPoint Co-ordinate object parameter.

   411     */

   412     IMPORT_C void MoveToNextOrPreviousItemL(TPoint aPoint);

   413     

   414     /** 

   415     * This protected function used by functions to check/alter the dimensions

   416     * of the grid as data items are added or removed or the size of the items

   417     * are altered. It also assumes that @c SetLayoutL has been called. 

   418     * This will not leave if scrollbars have both been turned off. If a leave 

   419     * occurs the framework generates a Symbian Leave code.

   420     */

   421     IMPORT_C virtual void CalcGridSizeL();

   422     

   423     /**

   424     * Creates a formatted list item drawer. If a leave occurs the framework 

   425     * generates a Symbian Leave code.

   426     */

   427     IMPORT_C virtual void CreateItemDrawerL();

   428 

   429 private:

   430     __DECLARE_TEST;

   431 

   432     // grid model helper

   433     inline CAknGridM* GridModel() const;

   434 

   435     // grid view helper

   436     inline CAknGridView* GridView() const;

   437 

   438     /**

   439     * This function sets the size and initial layout of items. If a leave 

   440     * occurs the framework generates a Symbian Leave code.

   441     * @param aOrientation

   442     * @param aHorizontal

   443     * @param aVertical

   444     * @param aNumOfItemsInPrimaryOrient

   445     * @param aNumOfItemsInSecondaryOrient

   446     * @param aSizeOfItems

   447     * @param aWidthOfSpaceBetweenItems

   448     * @param aHeightOfSpaceBetweenItems

   449     */

   450     void DoSetLayoutL(TInt aOrientation,

   451                       TInt aHorizontal,

   452                       TInt aVertical,

   453                       TInt aNumOfItemsInPrimaryOrient,

   454                       TInt aNumOfItemsInSecondaryOrient,

   455                       TSize aSizeOfItems,

   456                       TInt aWidthOfSpaceBetweenItems=0,

   457                       TInt aHeightOfSpaceBetweenItems=0);

   458 

   459 private:

   460     /**

   461     * From CAknControl

   462     */

   463     IMPORT_C void* ExtensionInterface( TUid aInterface );

   464 private: // from MListBoxModel

   465     IMPORT_C virtual TAny* MListBoxModel_Reserved();

   466     

   467 protected: 

   468     /**

   469     * From @c MEikScrollBarObserver

   470     *

   471     * This function handles scroll events caused by scroll bar. 

   472     * It updates grid's view by event and new thumb position. 

   473     *

   474     * @param aScrollBar pointer to scroll bar sent this event

   475     * @param aEventType type of event

   476     */

   477     IMPORT_C virtual void HandleScrollEventL(CEikScrollBar* aScrollBar, TEikScrollEvent aEventType);

   478 

   479     /**

   480     * From @c MObjectProvider.

   481     *

   482     * Retrieves an object of the same type as that encapsulated in aId. This 

   483     * function is used to allow controls to ask their owners for access to 

   484     * other objects that they own.

   485     * 

   486     * @param aId An encapsulated object type ID.

   487     * @return Encapsulates the pointer to the object provided. 

   488     *         Note that the encapsulated pointer may be NULL.

   489     */

   490     IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

   491     

   492     

   493 private:

   494     TInt  iMinColWidth;

   495     TBool iCurrentIsValid;

   496     TInt  iNumOfColsInView;

   497     TInt  iNumOfRowsInView;

   498     TSize iSpaceBetweenItems;

   499         TInt  iSpare; // was iNumOfItemsInPrimaryOrient;

   500     TBitFlags iOrientationFlags;

   501     TBitFlags iHorizontalFlags;

   502     TBitFlags iVerticalFlags;

   503     CAknGridExtension *iExtension; // spare taken to use as extension class

   504     };

   505 

   506 /**

   507  * Return Model

   508  */

   509 inline CAknGridM* CAknGrid::GridModel() const

   510     {

   511     return STATIC_CAST(CAknGridM*,iModel);

   512     }

   513 

   514 /**

   515  * Return View 

   516  */

   517 inline CAknGridView* CAknGrid::GridView() const

   518     {

   519     return STATIC_CAST(CAknGridView*,iView);

   520     }

   521 

   522 /**

   523  * Return text currently in the empty grid text

   524  */

   525 inline const TDesC* CAknGrid::EmptyGridText() const

   526     {

   527     return STATIC_CAST(CAknGridView*,iView)->EmptyListText();

   528     }

   529 

   530 #endif //__AKNGRID_H__

   531