/*

* 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();