--- a/epoc32/include/mw/akngridview.h	Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/mw/akngridview.h	Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,545 @@
-akngridview.h
+/*
+* 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__