/*

 * Copyright (c) 2002-2009 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: 

 *     CAknGridView handles the drawing, the mapping

 *     of the grid data index to the underlying listbox index (and

 *     visa versa) as well as the movement around the grid.

 *

 */

 #ifndef __AKNGRIDVIEW_H__

 #define __AKNGRIDVIEW_H__

 // INCLUDES

 #include <eiklbv.h>

 #include <akngridm.h>

 #include <eiklabel.h>

 // CLASS DECLARATION

 /**

 * @c CAknGridView handles the drawing, the mapping of the grid data index

 * to the underlying listbox index (and vice versa) as well as the movement

 * around the grid. Differentiation is needed between a data index and the

 * list box index since the inherited list box code handles the top, bottom

 * and current indexes as though everything is order topdown and left to

 * right. This is no good for grid that maybe order in 8 different

 * ways so need conversion between list box index and actual data

 * index.

 * List box index is the index for the data item according to the

 * snaking list box format of numbering data items.

 * Data index is the actual index in the grid according to the

 * ordering applied to the data by the user.

 * Note: the logical position is the intermediate form used to map

 * from a list box index to a data index or vi sa versa. It is

 * essentialy the position of the item in relation to the top left

 * corner of the grid. I.e. the top left position has logical

 * position 0,0.

 * 

 * @since 0.9

 * @lib avkon.lib

 */

 class CAknGridView : public CListBoxView 

 	{

 public:

 	/** Enumeration flags for grid.*/

 	enum TGridFlags

 		{

 		/** Vertical is primary direction.*/

 		EPrimaryIsVertical	= 0x0001,

 		/** From top to bottom.*/

 		ETopToBottom		= 0x0002,

 		/** From left to right.*/

 		ELeftToRight		= 0x0004

 		};

 	/** Enumeration for different scrolling types.*/

 	enum TScrollingType

 		{

 		/** Scrolling follows items and stops.*/

 		EScrollFollowsItemsAndStops,

 		/** Scrolling follows items and loops.*/

 		EScrollFollowsItemsAndLoops,

 		/** Scrolling follows grid. */

 		EScrollFollowsGrid,

 		/** Scrolling stops. */

 		EScrollStops,

 		/** Scrolls one line and stops.*/

 		EScrollIncrementLineAndStops,

 		/** Scrolls one line and loops.*/

 		EScrollIncrementLineAndLoops

 		};

 	/** Enumeration flags for different layouts.*/

 	struct SGrid

 		{

 		/** Current size of entire grid. */

 		TSize iGridDimensions;

 		/** Flags. */

 		TInt iGridFlags;

 		/** Size of the viewable area ( iColsInView * iRowsInView ). */

 		TInt iPageSize;

 		/** The number of columns in the viewable area. */

 		TInt iColsInView;

 		/** The number of rows in the viewable area. */

 		TInt iRowsInView;

 		/** The size of gap between items (height and width). */

 		TSize iSizeBetweenItems;

 		/** The size of an item. */

 		TSize iSizeOfItems;

 		};

 protected:

 	/** Enumeration flags for pages.*/

 	enum TPageIndex 

 		{

 		/** Previous page.*/

 		EPreviousPage,

 		/** Next page.*/

 		ENextPage,

 		/** First page. */

 		EHome,

 		/** Last page.*/

 		EEnd

 		};

 	/* Enumeration of position of current index.*/

 	enum TPositionCurrentIndex

 		{

 		/** Page. */

 		EPage,

 		/** Column.*/

 		EColumn,

 		/** Opposite corner.*/

 		EOppositeCorner

 		};

 public:

 	/**

 	* Default C++ constructor.

 	*/

 	IMPORT_C CAknGridView();

 	/**

 	* Destructor.

 	*/

 	IMPORT_C virtual ~CAknGridView();

 	// actual <-> listbox index conversion routines

 	/**

 	* Returns the actual index of given listbox index.

 	* @param aListBoxIndex The index of the listbox.

 	* @return The actual data index.

 	*/

 	IMPORT_C TInt ActualDataIndex(TInt aListBoxIndex) const;

 	/**

 	* Returns the listbox index of given data index.

 	* @param aDataIndex The index of the actual data.

 	* @return The index in listbox.

 	*/

 	IMPORT_C TInt ListBoxIndex(TInt aDataIndex) const;

 	/**

 	* Returns the current data index with respect to the ordering of the cells

 	* in the grid.

 	* @return Current data index.

 	*/

 	IMPORT_C TInt CurrentDataIndex() const;

 	/**

  	* Sets the current data index with a value given with respect to the

  	* ordering of the cells in the grid.

  	* @param aDataIndex The index to be set.

  	*/

 	IMPORT_C void SetCurrentDataIndex(TInt aDataIndex);

 	/**

  	* Sets the form of scroll to activate upon reaching the limit when moving

  	* in the primary direction of grid, primary meaning whether the items are

  	* organised vertically or horizontally.

  	* @param aScrollingType The primary scrolling type.

  	*/

 	IMPORT_C void SetPrimaryScrollingType(TScrollingType aScrollingType);

 	/**

  	* Sets the form of scroll to activate upon reaching the limit when moving

  	* in the secondary direction of grid.

  	* @param aSecondaryScrolling The secondary scrolling type.

  	*/

 	IMPORT_C void SetSecondaryScrollingType(TScrollingType aSecondaryScrolling);

 	/**

  	* Checks that number of cells in the grid is always enough to fill the

  	* current grid dimensions. This method should be called after any method

  	* that may alter the amount of data within the grid.

  	* @param aGridDimensions Grid diemnsions.

  	*/

 	IMPORT_C void SetGridCellDimensions(TSize aGridDimensions);

 	/**

  	* Returns the current grid dimensions.

  	* @return The size of the current grid.

  	*/

 	IMPORT_C TSize GridCellDimensions() const;

 	/**

 	* Sets the size of the spaces between items.

 	* @param aSizeOfSpaceBetweenItems The size of the spaces between items.

  	*/

 	IMPORT_C void SetSpacesBetweenItems(TSize aSizeOfSpaceBetweenItems);

 	/**

  	* Returns @c ETrue if the primary dimension of the grid is vertical.

  	* @return @ETrue if vertical is set as primary, otherwise @c EFalse.

  	*/

 	IMPORT_C TBool IsPrimaryVertical() const;

 	/**

  	* Converts a logical position on the grid, where the co-ordinates are with

  	* respect to the top left hand corner of the grid, to an index for the cell

  	* with respect to the ordering of the cells in the grid.

  	* @param aItemIndex Reference to the index for the cell in the grid. 

  	* @param aRowIndex The row in the grid.

  	* @param aColIndex The column in the grid.

  	*/

 	IMPORT_C void DataIndexFromLogicalPos(

 		TInt& aItemIndex,

 		TInt aRowIndex,

 		TInt aColIndex) const;

 	/**

  	* Converts an index for a cell in the grid, given with respect to the

  	* ordering of the cells in the grid, to a logical position on the grid,

  	* where the co-ordinates are with respect to the top left hand corner of

  	* the grid.

  	* @param aItemIndex The index for the cell in the grid. 

  	* @param aRowIndex Reference to the row in the grid.

  	* @param aColIndex Reference to the column in the grid.

  	*/

 	IMPORT_C void LogicalPosFromDataIndex(

 		TInt aItemIndex,

 		TInt& aRowIndex,

 		TInt& aColIndex) const;

 	/**

  	* Converts a CEikListBox index for a cell in the grid, given with respect

  	* to the snaking listbox top down, left to right structure underlying the

  	* grid structure, to a logical position on the grid, where the co-ordinates

  	* are with respect to the top left hand corner of the grid.

  	* @param aItemIndex Reference to the index for the cell in the grid. 

  	* @param aRowIndex The row in the grid.

  	* @param aColIndex The column in the grid.

  	*/	

 	IMPORT_C void ListBoxIndexFromLogicalPos(

 		TInt& aItemIndex,

 		TInt aRowIndex,

 		TInt aColIndex) const;

 	/**

  	* Converts a logical position on the grid, where the co-ordinates are with

  	* respect to the top left hand corner of the grid, to a CEikListBox index

  	* for the cell with respect to the snaking listbox top down, left to right

  	* structure underlying the grid structure.

  	* @param aItemIndex The index for the cell in the grid. 

  	* @param aRowIndex Reference to the row in the grid.

  	* @param aColIndex Reference to the column in the grid.

  	*/

 	IMPORT_C void LogicalPosFromListBoxIndex(

 		TInt aItemIndex,

 		TInt& aRowIndex,

 		TInt& aColIndex) const;

 	/**

 	* Draws empty grid list.

 	*/

 	IMPORT_C virtual void DrawEmptyList() const;

 	/**

  	* Grid initialisation function.

  	* @param aGridDetails Struct of grid details.

  	*/

 	IMPORT_C void SetGridDetails(SGrid aGridDetails);

 	/**

  	* This moves to the item and draws the grid in the right place.

  	* @param aItemIndex The wanted item index.

  	* @param aSelectionMode Mode for modifying the selection.

  	*/

 	IMPORT_C void MoveToItemIndexL(TInt aItemIndex, TSelectionMode aSelectionMode);

 	/**

 	* This function returns the number of visible columns.

 	* @return The number of visible columns in view.

 	*/

 	IMPORT_C TInt NumberOfColsInView() const;

 	/**

  	* This function returns the number of visible rows.

  	* @return The number of visible rows in view.

  	*/

 	IMPORT_C TInt NumberOfRowsInView() const;

     /**

     * Moves cursor with repeats.

     * @param aNext ETrue if next, EFalse if previous.

     * @param aSelectionMode selection mode.

     * @param aAmount Amount of steps to move.

     * @since S60 3.2

     */

     void MoveCursorWithRepeatsL( 

         TBool aNextOrPrev, 

         TSelectionMode aSelectionMode, 

         TInt aAmount );

 public: // from CListBoxView 

 	/**

 	* From @c CListBoxView. Basically empty implementation of 

 	* @c CListBoxView::DrawMatcherCursor.

 	*/

 	IMPORT_C virtual void DrawMatcherCursor();

 	/** 

 	* From @c CListBoxView. This function returns the current item in the grid

 	* and -1 if there is no current item,

 	* @return The current item.

 	*/

 	IMPORT_C TInt CurrentItemIndex() const;

 protected:

 	/**

 	* This function tests whether an item exists.

 	* @param aListBoxIndex Index to test.

 	* @return @c ETrue if the specified item exists, @c EFalse otherwise.

 	*/

 	IMPORT_C TBool ItemExists(TInt aListBoxIndex) const;

 public: // code moved from CSnakingListBoxView

 	/**

  	* This function sets the width of the grid column. This should only be 

  	* called via the selection box class's @c SetColumnWidth method.

  	* @param aColumnWidth The required width of all columns in the view, 

  	* in pixels.

  	*/

 	IMPORT_C void SetColumnWidth(TInt aColumnWidth);

 	/**

 	* Overloaded @c MoveCursorL method to process cursor movement according to

  	* orientation of the grid.

  	* @param aCursorMovement The cursor movement to apply 

  	* etc. @c ECursorNextItem and @c ECursorPreviousItem.

  	* @param aSelectionMode The selection mode of the calling list box. 	

  	*/	

 	IMPORT_C virtual void MoveCursorL(

 		TCursorMovement aCursorMovement,

 		TSelectionMode aSelectionMode);

 	/**

 	* This function draws every visible item into the specified rectangle. 

 	* As implemented in @c CListBoxView, this function's argument is ignored

 	* and the internal viewing rectangle is used. See @c SetViewRect().

 	* @param @c TRect* @c aClipRect = @c NULL The rectangle to draw into.

 	*/

 	IMPORT_C virtual void Draw(const TRect* aClipRect = NULL) const;

 	/**

  	* This has been overloaded to ensure that only valid cells are drawn and 

  	* not the empty cells.

  	* @param aItemIndex Index number of the item to draw.

 	*/ 	

 	IMPORT_C virtual void DrawItem(TInt aItemIndex) const;

 	/**

 	* This function gets the position of the top left corner of the specified 

 	* item, in pixels. 

 	* @param aItemIndex An item in the model. 

 	* @return @c TPoint position of the top left corner of the item, in pixels.

 	*/ 

 	IMPORT_C virtual TPoint ItemPos(TInt aItemIndex) const;

 	/**

 	* This function has been overloaded to draw items correctly. Recalculates 

 	* the bottom item’s index. This is called by the list box control when 

 	* either the size or the number of items in its model changes. 

 	*/ 	

 	IMPORT_C virtual void CalcBottomItemIndex();

 	/**

 	* This function gets the item the view would need to be moved to in order 

 	* to make the specified item visible.

 	* @param aItemIndex The item to make visible.

 	* @return The item to scroll to to make @c aItemIndex visible.

 	*/	

 	IMPORT_C virtual TInt CalcNewTopItemIndexSoItemIsVisible(TInt aItemIndex) const;

 	/**

 	* This function draws every item between the start and end indices

 	* inclusively.

 	* @param aStartItemIndex The first item to draw.

 	* @param aEndItemIndex The final item to draw.

 	*/

 	IMPORT_C virtual void DrawItemRange(TInt aStartItemIndex, TInt aEndItemIndex) const;

 	/**

 	* This function gets the width of all columns in the view.

 	* @return The width of all columns in the view, in pixels.

 	*/

 	inline TInt ColumnWidth() const;

 	/**

 	* Sets which item appears at the top left corner of the view. The function

 	* changes items displayed in the view appropriately.

 	* @param aItemIndex Index of the item to set at the top left.

 	*/

 	IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex);

 	/**

 	* This function sets item height in pixels.

 	* @param aItemHeight New height in pixels for this view’s items.

 	*/	

 	IMPORT_C virtual void SetItemHeight(TInt aItemHeight);

 	/*

 	* This function converts an (x, y) pixel position to an item index.

 	* @param aPosition Pixel position in the viewing rectangle.

 	* @param aItemIndex Reference to the item index.

 	* @return Whether there was an item at aPosition.

 	*/	

 	IMPORT_C virtual TBool XYPosToItemIndex(TPoint aPosition, TInt& aItemIndex) const;

 	/**

 	* Calculates the data width in columns. @c iDataWidth is calculated based on

 	* model and drawer information.

 	*/	

 	IMPORT_C virtual void CalcDataWidth();

 	/**

 	* Gets the visible width of the specified rectangle in pixels.

 	* @param aRect Reference to the rectangle for which to get the visible 

 	* width.

 	* @return Visible width of aRect in pixels.

 	*/	

 	IMPORT_C virtual TInt VisibleWidth(const TRect& aRect) const;

 	/**

 	* Makes the specified item visible by moving the view location and 

 	* redrawing the control. Index of the item to make visible. 

 	* @param aItemIndex Index of the item to make visible. 

 	* @return @c ETrue if the control was redrawn, @c EFalse if no redraw 

 	* happened (i.e. the item was already visible, or redraw was disabled).

 	*/

 	IMPORT_C virtual TBool ScrollToMakeItemVisible(TInt aItemIndex);

 	/**

 	* Gets the number of columns that this view would need to be scrolled by 

 	* to make the specified item visible. The function returns 0 if no 

 	* scrolling is needed. @c ScrollToMakeItemVisible() uses this function.

 	* @param aItemIndex Item to make visible.

 	* @return The number of columns to scroll, or zero if no scrolling is

 	* needed.

 	*/

 	IMPORT_C virtual TInt CalculateHScrollOffsetSoItemIsVisible(TInt aItemIndex);

 	/**

 	* Gets the size of the specified item.

 	* @param aItemIndex=0 The index of the item whose size this call is to get.

 	* @return @c TSize The size of the item in pixels.

 	*/

 	IMPORT_C virtual TSize ItemSize(TInt aItemIndex=0) const;

 	/**

 	* Converts an item index into the (row, column) pair describing that item.

 	* @param aItemIndex The item index.

 	* @param aRowIndex Reference to the row index.

 	* @param aColIndex Reference the column index.

 	*/	

 	IMPORT_C void CalcRowAndColIndexesFromItemIndex(TInt aItemIndex, TInt& aRowIndex, TInt& aColIndex) const;

 	/**

 	* This function converts a row/column pair into the item index for that 

 	* item.

 	* @param aItemIndex Reference to the item index. 

 	* @param aRowIndex Row index of the item.

 	* @param aColIndex Column index of the item.

 	*/

 	IMPORT_C void CalcItemIndexFromRowAndColIndexes(TInt& aItemIndex, TInt aRowIndex, TInt aColIndex) const;

 protected: // code moved from CSnakingListBoxView

 	/**

 	* This function draws every item in every column between the start and end

 	* columns inclusively.

 	* @param aStartColIndex The first column to draw. 

 	* @param aEndColIndex The last column to draw. 

 	*/

 	IMPORT_C void DrawColumnRange(TInt aStartColIndex, TInt aEndColIndex) const;

 	/**

 	* This function clears each item’s rectangle between the specified start

 	* and finish item’s indexes.

 	* @param aStartItemIndex The first item to clear.

 	* @param aEndItemIndex The last item to clear.

 	*/	

 	IMPORT_C void ClearUnusedItemSpace(TInt aStartItemIndex, TInt aEndItemIndex) const;

 	/**

 	* This function updates the horizontal scroll offset (iHScrollOffset) 

 	* based on the top item’s index. This function is called internally by

 	* @c CEikSnakingListBoxes when needed.

 	*/	

 	IMPORT_C void UpdateHScrollOffsetBasedOnTopItemIndex();

 protected:

 	/**

 	* This inline function is grid model helper.

 	* @return A pointer to @c CAknGridM object.

 	*/	

 	inline CAknGridM* GridModel() const;

 	/** 

 	* This function handles movement routines.

 	* @param aCursorMovement Handles cursor movements etc. @c ECursorNextItem

 	* and @c ECursorPreviousItem.

 	* @param aSelectionMode Modes for modifying the selection.

 	*/

 	IMPORT_C void DoMoveL(TCursorMovement aCursorMovement, TSelectionMode aSelectionMode);

 private:

 	// movement handling routines

 	IMPORT_C TInt SearchByLines(TInt aX, TInt aY, TCursorMovement aCursorMovement, TBool aBeginSearchOnIndex = EFalse);

 	IMPORT_C TInt FindNextItem(TInt aItemIndex, TBool aLookDown, TBool aLookRight, TBool aFirstLookHorizontal, TBool aBeginSearchOnIndex = EFalse);

 	TBool IsEdgePassed(TInt aItemIndex, TBool aLookDown, TBool aLookRight, TBool aFirstLookHorizontal, TBool aBeginSearchOnIndex, TInt& aNewIndex);

 	TBool IsMoveRight(TCursorMovement aCursorMovement);

 	TBool IsMoveDown(TCursorMovement aCursorMovement);

 private: // overridden from CListBoxView

 	IMPORT_C virtual TAny* Reserved_1();

 private:

     /**

     * Draws the portion of the grid view rectangle that contains no items.

     */

     void DrawUnusedViewPortion() const;

 private:

 	TScrollingType iScrollingType;

 	TScrollingType iScrollInSecondaryDimension;

 	SGrid iGridDetails;

     TInt iSpare[2];

 	};

 inline CAknGridM* CAknGridView::GridModel() const

 	{

 	return STATIC_CAST(CAknGridM*,iModel);

 	}

 inline TInt CAknGridView::ColumnWidth() const

 	{ return iGridDetails.iSizeOfItems.iWidth; }

 #endif // __AKNGRIDVIEW_H__