1.1 --- a/epoc32/include/mw/akngridview.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/akngridview.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,545 @@
1.4 -akngridview.h
1.5 +/*
1.6 +* Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description:
1.19 +* CAknGridView handles the drawing, the mapping
1.20 +* of the grid data index to the underlying listbox index (and
1.21 +* visa versa) as well as the movement around the grid.
1.22 +*
1.23 +*/
1.24 +
1.25 +#ifndef __AKNGRIDVIEW_H__
1.26 +#define __AKNGRIDVIEW_H__
1.27 +
1.28 +// INCLUDES
1.29 +#include <eiklbv.h>
1.30 +#include <akngridm.h>
1.31 +#include <eiklabel.h>
1.32 +
1.33 +// CLASS DECLARATION
1.34 +
1.35 +/**
1.36 +* @c CAknGridView handles the drawing, the mapping of the grid data index
1.37 +* to the underlying listbox index (and vice versa) as well as the movement
1.38 +* around the grid. Differentiation is needed between a data index and the
1.39 +* list box index since the inherited list box code handles the top, bottom
1.40 +* and current indexes as though everything is order topdown and left to
1.41 +* right. This is no good for grid that maybe order in 8 different
1.42 +* ways so need conversion between list box index and actual data
1.43 +* index.
1.44 +* List box index is the index for the data item according to the
1.45 +* snaking list box format of numbering data items.
1.46 +* Data index is the actual index in the grid according to the
1.47 +* ordering applied to the data by the user.
1.48 +* Note: the logical position is the intermediate form used to map
1.49 +* from a list box index to a data index or vi sa versa. It is
1.50 +* essentialy the position of the item in relation to the top left
1.51 +* corner of the grid. I.e. the top left position has logical
1.52 +* position 0,0.
1.53 +*
1.54 +* @since 0.9
1.55 +* @lib avkon.lib
1.56 +*/
1.57 +class CAknGridView : public CListBoxView
1.58 + {
1.59 +public:
1.60 + /** Enumeration flags for grid.*/
1.61 + enum TGridFlags
1.62 + {
1.63 + /** Vertical is primary direction.*/
1.64 + EPrimaryIsVertical = 0x0001,
1.65 + /** From top to bottom.*/
1.66 + ETopToBottom = 0x0002,
1.67 + /** From left to right.*/
1.68 + ELeftToRight = 0x0004
1.69 + };
1.70 + /** Enumeration for different scrolling types.*/
1.71 + enum TScrollingType
1.72 + {
1.73 + /** Scrolling follows items and stops.*/
1.74 + EScrollFollowsItemsAndStops,
1.75 + /** Scrolling follows items and loops.*/
1.76 + EScrollFollowsItemsAndLoops,
1.77 + /** Scrolling follows grid. */
1.78 + EScrollFollowsGrid,
1.79 + /** Scrolling stops. */
1.80 + EScrollStops,
1.81 + /** Scrolls one line and stops.*/
1.82 + EScrollIncrementLineAndStops,
1.83 + /** Scrolls one line and loops.*/
1.84 + EScrollIncrementLineAndLoops
1.85 + };
1.86 + /** Enumeration flags for different layouts.*/
1.87 + struct SGrid
1.88 + {
1.89 + /** Current size of entire grid. */
1.90 + TSize iGridDimensions;
1.91 + /** Flags. */
1.92 + TInt iGridFlags;
1.93 + /** Size of the viewable area ( iColsInView * iRowsInView ). */
1.94 + TInt iPageSize;
1.95 + /** The number of columns in the viewable area. */
1.96 + TInt iColsInView;
1.97 + /** The number of rows in the viewable area. */
1.98 + TInt iRowsInView;
1.99 + /** The size of gap between items (height and width). */
1.100 + TSize iSizeBetweenItems;
1.101 + /** The size of an item. */
1.102 + TSize iSizeOfItems;
1.103 + };
1.104 +
1.105 +protected:
1.106 + /** Enumeration flags for pages.*/
1.107 + enum TPageIndex
1.108 + {
1.109 + /** Previous page.*/
1.110 + EPreviousPage,
1.111 + /** Next page.*/
1.112 + ENextPage,
1.113 + /** First page. */
1.114 + EHome,
1.115 + /** Last page.*/
1.116 + EEnd
1.117 + };
1.118 + /* Enumeration of position of current index.*/
1.119 + enum TPositionCurrentIndex
1.120 + {
1.121 + /** Page. */
1.122 + EPage,
1.123 + /** Column.*/
1.124 + EColumn,
1.125 + /** Opposite corner.*/
1.126 + EOppositeCorner
1.127 + };
1.128 +
1.129 +public:
1.130 + /**
1.131 + * Default C++ constructor.
1.132 + */
1.133 + IMPORT_C CAknGridView();
1.134 +
1.135 + /**
1.136 + * Destructor.
1.137 + */
1.138 + IMPORT_C virtual ~CAknGridView();
1.139 +
1.140 + // actual <-> listbox index conversion routines
1.141 + /**
1.142 + * Returns the actual index of given listbox index.
1.143 + * @param aListBoxIndex The index of the listbox.
1.144 + * @return The actual data index.
1.145 + */
1.146 + IMPORT_C TInt ActualDataIndex(TInt aListBoxIndex) const;
1.147 +
1.148 + /**
1.149 + * Returns the listbox index of given data index.
1.150 + * @param aDataIndex The index of the actual data.
1.151 + * @return The index in listbox.
1.152 + */
1.153 + IMPORT_C TInt ListBoxIndex(TInt aDataIndex) const;
1.154 +
1.155 + /**
1.156 + * Returns the current data index with respect to the ordering of the cells
1.157 + * in the grid.
1.158 + * @return Current data index.
1.159 + */
1.160 + IMPORT_C TInt CurrentDataIndex() const;
1.161 +
1.162 + /**
1.163 + * Sets the current data index with a value given with respect to the
1.164 + * ordering of the cells in the grid.
1.165 + * @param aDataIndex The index to be set.
1.166 + */
1.167 + IMPORT_C void SetCurrentDataIndex(TInt aDataIndex);
1.168 +
1.169 + /**
1.170 + * Sets the form of scroll to activate upon reaching the limit when moving
1.171 + * in the primary direction of grid, primary meaning whether the items are
1.172 + * organised vertically or horizontally.
1.173 + * @param aScrollingType The primary scrolling type.
1.174 + */
1.175 + IMPORT_C void SetPrimaryScrollingType(TScrollingType aScrollingType);
1.176 + /**
1.177 + * Sets the form of scroll to activate upon reaching the limit when moving
1.178 + * in the secondary direction of grid.
1.179 + * @param aSecondaryScrolling The secondary scrolling type.
1.180 + */
1.181 + IMPORT_C void SetSecondaryScrollingType(TScrollingType aSecondaryScrolling);
1.182 +
1.183 + /**
1.184 + * Checks that number of cells in the grid is always enough to fill the
1.185 + * current grid dimensions. This method should be called after any method
1.186 + * that may alter the amount of data within the grid.
1.187 + * @param aGridDimensions Grid diemnsions.
1.188 + */
1.189 + IMPORT_C void SetGridCellDimensions(TSize aGridDimensions);
1.190 +
1.191 + /**
1.192 + * Returns the current grid dimensions.
1.193 + * @return The size of the current grid.
1.194 + */
1.195 + IMPORT_C TSize GridCellDimensions() const;
1.196 + /**
1.197 + * Sets the size of the spaces between items.
1.198 + * @param aSizeOfSpaceBetweenItems The size of the spaces between items.
1.199 + */
1.200 + IMPORT_C void SetSpacesBetweenItems(TSize aSizeOfSpaceBetweenItems);
1.201 +
1.202 + /**
1.203 + * Returns @c ETrue if the primary dimension of the grid is vertical.
1.204 + * @return @ETrue if vertical is set as primary, otherwise @c EFalse.
1.205 + */
1.206 + IMPORT_C TBool IsPrimaryVertical() const;
1.207 +
1.208 + /**
1.209 + * Converts a logical position on the grid, where the co-ordinates are with
1.210 + * respect to the top left hand corner of the grid, to an index for the cell
1.211 + * with respect to the ordering of the cells in the grid.
1.212 + * @param aItemIndex Reference to the index for the cell in the grid.
1.213 + * @param aRowIndex The row in the grid.
1.214 + * @param aColIndex The column in the grid.
1.215 + */
1.216 + IMPORT_C void DataIndexFromLogicalPos(
1.217 + TInt& aItemIndex,
1.218 + TInt aRowIndex,
1.219 + TInt aColIndex) const;
1.220 +
1.221 + /**
1.222 + * Converts an index for a cell in the grid, given with respect to the
1.223 + * ordering of the cells in the grid, to a logical position on the grid,
1.224 + * where the co-ordinates are with respect to the top left hand corner of
1.225 + * the grid.
1.226 + * @param aItemIndex The index for the cell in the grid.
1.227 + * @param aRowIndex Reference to the row in the grid.
1.228 + * @param aColIndex Reference to the column in the grid.
1.229 + */
1.230 + IMPORT_C void LogicalPosFromDataIndex(
1.231 + TInt aItemIndex,
1.232 + TInt& aRowIndex,
1.233 + TInt& aColIndex) const;
1.234 +
1.235 + /**
1.236 + * Converts a CEikListBox index for a cell in the grid, given with respect
1.237 + * to the snaking listbox top down, left to right structure underlying the
1.238 + * grid structure, to a logical position on the grid, where the co-ordinates
1.239 + * are with respect to the top left hand corner of the grid.
1.240 + * @param aItemIndex Reference to the index for the cell in the grid.
1.241 + * @param aRowIndex The row in the grid.
1.242 + * @param aColIndex The column in the grid.
1.243 + */
1.244 + IMPORT_C void ListBoxIndexFromLogicalPos(
1.245 + TInt& aItemIndex,
1.246 + TInt aRowIndex,
1.247 + TInt aColIndex) const;
1.248 + /**
1.249 + * Converts a logical position on the grid, where the co-ordinates are with
1.250 + * respect to the top left hand corner of the grid, to a CEikListBox index
1.251 + * for the cell with respect to the snaking listbox top down, left to right
1.252 + * structure underlying the grid structure.
1.253 + * @param aItemIndex The index for the cell in the grid.
1.254 + * @param aRowIndex Reference to the row in the grid.
1.255 + * @param aColIndex Reference to the column in the grid.
1.256 + */
1.257 + IMPORT_C void LogicalPosFromListBoxIndex(
1.258 + TInt aItemIndex,
1.259 + TInt& aRowIndex,
1.260 + TInt& aColIndex) const;
1.261 +
1.262 + /**
1.263 + * Draws empty grid list.
1.264 + */
1.265 + IMPORT_C virtual void DrawEmptyList() const;
1.266 +
1.267 + /**
1.268 + * Grid initialisation function.
1.269 + * @param aGridDetails Struct of grid details.
1.270 + */
1.271 + IMPORT_C void SetGridDetails(SGrid aGridDetails);
1.272 +
1.273 + /**
1.274 + * This moves to the item and draws the grid in the right place.
1.275 + * @param aItemIndex The wanted item index.
1.276 + * @param aSelectionMode Mode for modifying the selection.
1.277 + */
1.278 + IMPORT_C void MoveToItemIndexL(TInt aItemIndex, TSelectionMode aSelectionMode);
1.279 +
1.280 + /**
1.281 + * This function returns the number of visible columns.
1.282 + * @return The number of visible columns in view.
1.283 + */
1.284 + IMPORT_C TInt NumberOfColsInView() const;
1.285 +
1.286 + /**
1.287 + * This function returns the number of visible rows.
1.288 + * @return The number of visible rows in view.
1.289 + */
1.290 + IMPORT_C TInt NumberOfRowsInView() const;
1.291 +
1.292 + /**
1.293 + * Moves cursor with repeats.
1.294 + * @param aNext ETrue if next, EFalse if previous.
1.295 + * @param aSelectionMode selection mode.
1.296 + * @param aAmount Amount of steps to move.
1.297 + * @since S60 3.2
1.298 + */
1.299 + void MoveCursorWithRepeatsL(
1.300 + TBool aNextOrPrev,
1.301 + TSelectionMode aSelectionMode,
1.302 + TInt aAmount );
1.303 +
1.304 +public: // from CListBoxView
1.305 + /**
1.306 + * From @c CListBoxView. Basically empty implementation of
1.307 + * @c CListBoxView::DrawMatcherCursor.
1.308 + */
1.309 + IMPORT_C virtual void DrawMatcherCursor();
1.310 +
1.311 + /**
1.312 + * From @c CListBoxView. This function returns the current item in the grid
1.313 + * and -1 if there is no current item,
1.314 + * @return The current item.
1.315 + */
1.316 + IMPORT_C TInt CurrentItemIndex() const;
1.317 +
1.318 +protected:
1.319 + /**
1.320 + * This function tests whether an item exists.
1.321 + * @param aListBoxIndex Index to test.
1.322 + * @return @c ETrue if the specified item exists, @c EFalse otherwise.
1.323 + */
1.324 + IMPORT_C TBool ItemExists(TInt aListBoxIndex) const;
1.325 +
1.326 +public: // code moved from CSnakingListBoxView
1.327 + /**
1.328 + * This function sets the width of the grid column. This should only be
1.329 + * called via the selection box class's @c SetColumnWidth method.
1.330 + * @param aColumnWidth The required width of all columns in the view,
1.331 + * in pixels.
1.332 + */
1.333 + IMPORT_C void SetColumnWidth(TInt aColumnWidth);
1.334 +
1.335 + /**
1.336 + * Overloaded @c MoveCursorL method to process cursor movement according to
1.337 + * orientation of the grid.
1.338 + * @param aCursorMovement The cursor movement to apply
1.339 + * etc. @c ECursorNextItem and @c ECursorPreviousItem.
1.340 + * @param aSelectionMode The selection mode of the calling list box.
1.341 + */
1.342 + IMPORT_C virtual void MoveCursorL(
1.343 + TCursorMovement aCursorMovement,
1.344 + TSelectionMode aSelectionMode);
1.345 +
1.346 + /**
1.347 + * This function draws every visible item into the specified rectangle.
1.348 + * As implemented in @c CListBoxView, this function's argument is ignored
1.349 + * and the internal viewing rectangle is used. See @c SetViewRect().
1.350 + * @param @c TRect* @c aClipRect = @c NULL The rectangle to draw into.
1.351 + */
1.352 + IMPORT_C virtual void Draw(const TRect* aClipRect = NULL) const;
1.353 +
1.354 + /**
1.355 + * This has been overloaded to ensure that only valid cells are drawn and
1.356 + * not the empty cells.
1.357 + * @param aItemIndex Index number of the item to draw.
1.358 + */
1.359 + IMPORT_C virtual void DrawItem(TInt aItemIndex) const;
1.360 +
1.361 + /**
1.362 + * This function gets the position of the top left corner of the specified
1.363 + * item, in pixels.
1.364 + * @param aItemIndex An item in the model.
1.365 + * @return @c TPoint position of the top left corner of the item, in pixels.
1.366 + */
1.367 + IMPORT_C virtual TPoint ItemPos(TInt aItemIndex) const;
1.368 +
1.369 + /**
1.370 + * This function has been overloaded to draw items correctly. Recalculates
1.371 + * the bottom item’s index. This is called by the list box control when
1.372 + * either the size or the number of items in its model changes.
1.373 + */
1.374 + IMPORT_C virtual void CalcBottomItemIndex();
1.375 +
1.376 + /**
1.377 + * This function gets the item the view would need to be moved to in order
1.378 + * to make the specified item visible.
1.379 + * @param aItemIndex The item to make visible.
1.380 + * @return The item to scroll to to make @c aItemIndex visible.
1.381 + */
1.382 + IMPORT_C virtual TInt CalcNewTopItemIndexSoItemIsVisible(TInt aItemIndex) const;
1.383 +
1.384 + /**
1.385 + * This function draws every item between the start and end indices
1.386 + * inclusively.
1.387 + * @param aStartItemIndex The first item to draw.
1.388 + * @param aEndItemIndex The final item to draw.
1.389 + */
1.390 + IMPORT_C virtual void DrawItemRange(TInt aStartItemIndex, TInt aEndItemIndex) const;
1.391 +
1.392 + /**
1.393 + * This function gets the width of all columns in the view.
1.394 + * @return The width of all columns in the view, in pixels.
1.395 + */
1.396 + inline TInt ColumnWidth() const;
1.397 +
1.398 + /**
1.399 + * Sets which item appears at the top left corner of the view. The function
1.400 + * changes items displayed in the view appropriately.
1.401 + * @param aItemIndex Index of the item to set at the top left.
1.402 + */
1.403 + IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex);
1.404 +
1.405 + /**
1.406 + * This function sets item height in pixels.
1.407 + * @param aItemHeight New height in pixels for this view’s items.
1.408 + */
1.409 + IMPORT_C virtual void SetItemHeight(TInt aItemHeight);
1.410 +
1.411 + /*
1.412 + * This function converts an (x, y) pixel position to an item index.
1.413 + * @param aPosition Pixel position in the viewing rectangle.
1.414 + * @param aItemIndex Reference to the item index.
1.415 + * @return Whether there was an item at aPosition.
1.416 + */
1.417 + IMPORT_C virtual TBool XYPosToItemIndex(TPoint aPosition, TInt& aItemIndex) const;
1.418 +
1.419 + /**
1.420 + * Calculates the data width in columns. @c iDataWidth is calculated based on
1.421 + * model and drawer information.
1.422 + */
1.423 + IMPORT_C virtual void CalcDataWidth();
1.424 +
1.425 + /**
1.426 + * Gets the visible width of the specified rectangle in pixels.
1.427 + * @param aRect Reference to the rectangle for which to get the visible
1.428 + * width.
1.429 + * @return Visible width of aRect in pixels.
1.430 + */
1.431 + IMPORT_C virtual TInt VisibleWidth(const TRect& aRect) const;
1.432 +
1.433 + /**
1.434 + * Makes the specified item visible by moving the view location and
1.435 + * redrawing the control. Index of the item to make visible.
1.436 + * @param aItemIndex Index of the item to make visible.
1.437 + * @return @c ETrue if the control was redrawn, @c EFalse if no redraw
1.438 + * happened (i.e. the item was already visible, or redraw was disabled).
1.439 + */
1.440 + IMPORT_C virtual TBool ScrollToMakeItemVisible(TInt aItemIndex);
1.441 +
1.442 + /**
1.443 + * Gets the number of columns that this view would need to be scrolled by
1.444 + * to make the specified item visible. The function returns 0 if no
1.445 + * scrolling is needed. @c ScrollToMakeItemVisible() uses this function.
1.446 + * @param aItemIndex Item to make visible.
1.447 + * @return The number of columns to scroll, or zero if no scrolling is
1.448 + * needed.
1.449 + */
1.450 + IMPORT_C virtual TInt CalculateHScrollOffsetSoItemIsVisible(TInt aItemIndex);
1.451 +
1.452 + /**
1.453 + * Gets the size of the specified item.
1.454 + * @param aItemIndex=0 The index of the item whose size this call is to get.
1.455 + * @return @c TSize The size of the item in pixels.
1.456 + */
1.457 + IMPORT_C virtual TSize ItemSize(TInt aItemIndex=0) const;
1.458 +
1.459 + /**
1.460 + * Converts an item index into the (row, column) pair describing that item.
1.461 + * @param aItemIndex The item index.
1.462 + * @param aRowIndex Reference to the row index.
1.463 + * @param aColIndex Reference the column index.
1.464 + */
1.465 + IMPORT_C void CalcRowAndColIndexesFromItemIndex(TInt aItemIndex, TInt& aRowIndex, TInt& aColIndex) const;
1.466 +
1.467 + /**
1.468 + * This function converts a row/column pair into the item index for that
1.469 + * item.
1.470 + * @param aItemIndex Reference to the item index.
1.471 + * @param aRowIndex Row index of the item.
1.472 + * @param aColIndex Column index of the item.
1.473 + */
1.474 + IMPORT_C void CalcItemIndexFromRowAndColIndexes(TInt& aItemIndex, TInt aRowIndex, TInt aColIndex) const;
1.475 +
1.476 +protected: // code moved from CSnakingListBoxView
1.477 + /**
1.478 + * This function draws every item in every column between the start and end
1.479 + * columns inclusively.
1.480 + * @param aStartColIndex The first column to draw.
1.481 + * @param aEndColIndex The last column to draw.
1.482 + */
1.483 + IMPORT_C void DrawColumnRange(TInt aStartColIndex, TInt aEndColIndex) const;
1.484 +
1.485 + /**
1.486 + * This function clears each item’s rectangle between the specified start
1.487 + * and finish item’s indexes.
1.488 + * @param aStartItemIndex The first item to clear.
1.489 + * @param aEndItemIndex The last item to clear.
1.490 + */
1.491 + IMPORT_C void ClearUnusedItemSpace(TInt aStartItemIndex, TInt aEndItemIndex) const;
1.492 +
1.493 + /**
1.494 + * This function updates the horizontal scroll offset (iHScrollOffset)
1.495 + * based on the top item’s index. This function is called internally by
1.496 + * @c CEikSnakingListBoxes when needed.
1.497 + */
1.498 + IMPORT_C void UpdateHScrollOffsetBasedOnTopItemIndex();
1.499 +
1.500 +protected:
1.501 + /**
1.502 + * This inline function is grid model helper.
1.503 + * @return A pointer to @c CAknGridM object.
1.504 + */
1.505 + inline CAknGridM* GridModel() const;
1.506 +
1.507 + /**
1.508 + * This function handles movement routines.
1.509 + * @param aCursorMovement Handles cursor movements etc. @c ECursorNextItem
1.510 + * and @c ECursorPreviousItem.
1.511 + * @param aSelectionMode Modes for modifying the selection.
1.512 + */
1.513 + IMPORT_C void DoMoveL(TCursorMovement aCursorMovement, TSelectionMode aSelectionMode);
1.514 +
1.515 +private:
1.516 + // movement handling routines
1.517 + IMPORT_C TInt SearchByLines(TInt aX, TInt aY, TCursorMovement aCursorMovement, TBool aBeginSearchOnIndex = EFalse);
1.518 + IMPORT_C TInt FindNextItem(TInt aItemIndex, TBool aLookDown, TBool aLookRight, TBool aFirstLookHorizontal, TBool aBeginSearchOnIndex = EFalse);
1.519 + TBool IsEdgePassed(TInt aItemIndex, TBool aLookDown, TBool aLookRight, TBool aFirstLookHorizontal, TBool aBeginSearchOnIndex, TInt& aNewIndex);
1.520 +
1.521 + TBool IsMoveRight(TCursorMovement aCursorMovement);
1.522 + TBool IsMoveDown(TCursorMovement aCursorMovement);
1.523 +private: // overridden from CListBoxView
1.524 + IMPORT_C virtual TAny* Reserved_1();
1.525 +
1.526 +private:
1.527 +
1.528 + /**
1.529 + * Draws the portion of the grid view rectangle that contains no items.
1.530 + */
1.531 + void DrawUnusedViewPortion() const;
1.532 +
1.533 +private:
1.534 + TScrollingType iScrollingType;
1.535 + TScrollingType iScrollInSecondaryDimension;
1.536 +
1.537 + SGrid iGridDetails;
1.538 + TInt iSpare[2];
1.539 + };
1.540 +
1.541 +inline CAknGridM* CAknGridView::GridModel() const
1.542 + {
1.543 + return STATIC_CAST(CAknGridM*,iModel);
1.544 + }
1.545 +
1.546 +inline TInt CAknGridView::ColumnWidth() const
1.547 + { return iGridDetails.iSizeOfItems.iWidth; }
1.548 +
1.549 +#endif // __AKNGRIDVIEW_H__