/*

 * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

 * 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

 * which accompanies this distribution, and is available

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

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  

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

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

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

 *

 *

 */

 #if !defined(__AKNGRID_H__)

 #define __AKNGRID_H__

 // INCLUDES

 #include <eiktxlbx.h>

 #include <eiklbv.h>

 #include <eikfrlbd.h>

 #include <eikfrlb.h>

 #include <AknGridM.h>

 #include <AknGridView.h>

 #include <Aknappui.h>

 // CLASS PREDEFINITIONS

 class CAknGridExtension;

 // CLASS DECLARATION

 /**

 *  Application grid handling class from Avkon.

 *  Provides support for ordering application grids items.

 *

 *  @since Series 60 0.9

 */

 class CAknGrid : public CEikListBox

     {

 private:// enums

     enum TIndicatorEvent

         {

         EMove,

         EChangeNumOfItems,

         EResize

         };

 public:

     /**

     * Base class default constructor.

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

     */

     IMPORT_C CAknGrid();

     /**

     * Destructor.

     */

     IMPORT_C virtual ~CAknGrid();

     /**

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

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

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

     * application programmer provides their own grid model class, the 

     * application programmer must instantiate their own grid model class object

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

     * before calling the @c ConstructL/ConstructFromResourceL function.

     * @param aModel Pointer to @c CAknGridM class.

     */  

     IMPORT_C void SetModel(CAknGridM* aModel);

     /**

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

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

     * framework generates a Symbian Leave code.

     * @param aPatent A CCoeControl pointer.

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

     * parameter is missing default value is 0.

     */  

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

     /**

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

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

     * instantiated automatically during the construction phase of the 

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

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

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

     * @c SetModel function before calling the 

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

     * framework generates a Symbian Leave code.

     * @param aReader Construct controls from resource file.

     */

     IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

     /**

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

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

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

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

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

     * the framework generates a Symbian Leave code.

     * @param aVerticalOrientation Items vertical orientation.

     * @param aLeftToRight @c ETrue left to right.

     * @param aTopToBottom @c ETrue top to bottom.

     * @param aNumOfItemsInPrimaryOrient Number of items in primary orient.  

     * @param aNumOfItemsInSecondaryOrient Number of items in Secondary orient.

     * @param aSizeOfItems Item size.

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

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

     */

     IMPORT_C void SetLayoutL(TBool aVerticalOrientation,

                              TBool aLeftToRight,

                              TBool aTopToBottom,

                              TInt aNumOfItemsInPrimaryOrient,

                              TInt aNumOfItemsInSecondaryOrient,

                              TSize aSizeOfItems,

                              TInt aWidthOfSpaceBetweenItems=0,

                              TInt aHeightOfSpaceBetweenItems=0);

     /**

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

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

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

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

     * generates a Symbian Leave code.

     * @param aReader Constructs controls from a resource file. 

     */

     IMPORT_C void SetLayoutFromResourceL(TResourceReader& aReader);

     /**

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

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

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

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

     * next logical data item in the sequence.

     * @param aScrollingType Items scrolling type enum definition.

     */

     IMPORT_C void SetPrimaryScrollingType(CAknGridView::TScrollingType aScrollingType);

     /** 

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

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

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

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

     * @param aSecondaryScrolling Secondary scrolling type enum definition.

     */

     IMPORT_C void SetSecondaryScrollingType(CAknGridView::TScrollingType aSecondaryScrolling);

     /**

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

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

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

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

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

     * the framework generates a Symbian Leave code.

     * @param aGridStartPosition Parameter manipulate the grid's starting 

     * position.

     */

     IMPORT_C void SetStartPositionL(TPoint aGridStartPosition);

     /**

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

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

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

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

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

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

     * left-to-right.

     * @return A current position of highlight.

     */

     IMPORT_C TInt CurrentDataIndex() const;

     /**

     * Moves the cursor to the required grid data index.

     * @param aDataIndex Data index value.

     */

     IMPORT_C void SetCurrentDataIndex(TInt aDataIndex);

     /**

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

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

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

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

     * @return Activated item's index value.

     */

     IMPORT_C TInt IndexOfPosition(TPoint aGridPosition) const;

     /**

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

     * by using item's index value.

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

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

     */

     IMPORT_C TPoint PositionAtIndex(TInt aItemIndex) const;

     /**

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

     * @return A pointer to @c CFormattedCellListBoxItemDrawer object.

     */

     IMPORT_C CFormattedCellListBoxItemDrawer* ItemDrawer() const;

     /**

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

     * framework generates a Symbian Leave code.

     * @since Series S60 3.0

     * @param aText Descriptor parameter.

     */

     IMPORT_C void SetEmptyGridTextL(const TDesC& aText);

     /**

     * This function sets the empty grid text.

     * @return A pointer to the grid text descriptor.

     */

     inline const TDesC* EmptyGridText() const;

 public:

     /**

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

     * leave occurs the framework generates a Symbian Leave code.

     * @return A pointer to @c CListBoxView class.

     */

     IMPORT_C virtual CListBoxView* MakeViewClassInstanceL();

     /**

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

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

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

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

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

     */

     IMPORT_C void SetColumnWidth(TInt aColumnWidth);

     /**

     * This function gives a width of the column.

     * @return A width of the column. 

     */

     IMPORT_C TInt ColumnWidth() const;

 public: //from CEikListBox

     /**

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

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

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

     */

     IMPORT_C virtual void UpdateScrollBarsL();

     /**

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

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

     * code.

     */  

     IMPORT_C void HandleItemAdditionL();

     /**

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

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

     * Leave code.

     */  

     IMPORT_C void HandleItemRemovalL();

     /**

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

     * occurs the framework generates a Symbian Leave code.

     * @param aKeyEvent Event to handled.

     * @param aType of the key event.

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

     */  

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

     /**

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

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

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

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

     * framework generates a Symbian Leave code. 

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

     */  

     IMPORT_C void SetItemHeightL(TInt aHeight);

     /**

     * This function handles size changes. This routine assumes that 

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

     */  

     IMPORT_C void SizeChanged();

     /**

     * This function creates a new object and returns pointer to 

     * @c CTextListBoxModel class.

     * @return A pointer to @c CTextListBoxModel object.

     */  

     IMPORT_C CTextListBoxModel* Model() const;

     /**

     * This function handles viewable rectangle.

     * @param aRect Rectangle parameter. 

     */  

     IMPORT_C void SetRect(const TRect& aRect);

     /**

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

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

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

     * a Symbian Leave code.

     */  

     IMPORT_C virtual void HandleViewRectSizeChangeL();

     /**

     * This function sets top item index.

     * @param aItemIndex Item index value.

     */  

     IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;

     /**

     * This function handles resource changes.

     * @since Series S60 2.6.

     * @param aType Message type.

     */  

     IMPORT_C virtual void HandleResourceChange(TInt aType);

     /**

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

     * the function has no immediately effect. EDrawNow redraw control 

     * immediately.

     * @since Series S60 3.0.

     */

     IMPORT_C void FocusChanged(TDrawNow aDrawNow);

 public: // From CCoeControl

     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

 protected: // from CEikListBox

     /**

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

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

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

     */

     IMPORT_C virtual TInt HorizontalNudgeValue() const;

     /**

     * This function gets the granularity for horizontal scrolls. The 

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

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

     */  

     IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;

     /**

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

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

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

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

     * current item index.

     */  

     IMPORT_C virtual void AdjustTopItemIndex() const;

     /** 

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

     * generates a Symbian Leave code.

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

     * handler is invoked.

     */

     IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos);

     /** 

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

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

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

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

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

     * pixels. 

     */

     IMPORT_C virtual void RestoreClientRectFromViewRect(TRect& aClientRect) const;

     /** 

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

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

     * @param aRect Rectangle parameter.

     */

     IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(TRect& aRect) const;

     /**

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

     * position of selector.

     */

     IMPORT_C virtual void UpdateScrollBarThumbs() const;

     /**

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

     * @return The number of component controls.

     */

     IMPORT_C virtual TInt CountComponentControls() const;

 protected:

     /**

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

     * framework generates a Symbian Leave code.

     * @param aPoint Co-ordinate object parameter.

     */

     IMPORT_C void MoveToNextOrPreviousItemL(TPoint aPoint);

     /** 

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

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

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

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

     * occurs the framework generates a Symbian Leave code.

     */

     IMPORT_C virtual void CalcGridSizeL();

     /**

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

     * generates a Symbian Leave code.

     */

     IMPORT_C virtual void CreateItemDrawerL();

 private:

     __DECLARE_TEST;

     // grid model helper

     inline CAknGridM* GridModel() const;

     // grid view helper

     inline CAknGridView* GridView() const;

     /**

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

     * occurs the framework generates a Symbian Leave code.

     * @param aOrientation

     * @param aHorizontal

     * @param aVertical

     * @param aNumOfItemsInPrimaryOrient

     * @param aNumOfItemsInSecondaryOrient

     * @param aSizeOfItems

     * @param aWidthOfSpaceBetweenItems

     * @param aHeightOfSpaceBetweenItems

     */

     void DoSetLayoutL(TInt aOrientation,

                       TInt aHorizontal,

                       TInt aVertical,

                       TInt aNumOfItemsInPrimaryOrient,

                       TInt aNumOfItemsInSecondaryOrient,

                       TSize aSizeOfItems,

                       TInt aWidthOfSpaceBetweenItems=0,

                       TInt aHeightOfSpaceBetweenItems=0);

 private:

     /**

     * From CAknControl

     */

     IMPORT_C void* ExtensionInterface( TUid aInterface );

 private: // from MListBoxModel

     IMPORT_C virtual TAny* MListBoxModel_Reserved();

 protected: 

     /**

     * From @c MEikScrollBarObserver

     *

     * This function handles scroll events caused by scroll bar. 

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

     *

     * @param aScrollBar pointer to scroll bar sent this event

     * @param aEventType type of event

     */

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

     /**

     * From @c MObjectProvider.

     *

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

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

     * other objects that they own.

     * 

     * @param aId An encapsulated object type ID.

     * @return Encapsulates the pointer to the object provided. 

     *         Note that the encapsulated pointer may be NULL.

     */

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

 private:

     TInt  iMinColWidth;

     TBool iCurrentIsValid;

     TInt  iNumOfColsInView;

     TInt  iNumOfRowsInView;

     TSize iSpaceBetweenItems;

         TInt  iSpare; // was iNumOfItemsInPrimaryOrient;

     TBitFlags iOrientationFlags;

     TBitFlags iHorizontalFlags;

     TBitFlags iVerticalFlags;

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

     };

 /**

  * Return Model

  */

 inline CAknGridM* CAknGrid::GridModel() const

     {

     return STATIC_CAST(CAknGridM*,iModel);

     }

 /**

  * Return View 

  */

 inline CAknGridView* CAknGrid::GridView() const

     {

     return STATIC_CAST(CAknGridView*,iView);

     }

 /**

  * Return text currently in the empty grid text

  */

 inline const TDesC* CAknGrid::EmptyGridText() const

     {

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

     }

 #endif //__AKNGRID_H__