|
1 /* |
|
2 * Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * CAknGridView handles the drawing, the mapping |
|
16 * of the grid data index to the underlying listbox index (and |
|
17 * visa versa) as well as the movement around the grid. |
|
18 * |
|
19 */ |
|
20 |
|
21 #ifndef __AKNGRIDVIEW_H__ |
|
22 #define __AKNGRIDVIEW_H__ |
|
23 |
|
24 // INCLUDES |
|
25 #include <eiklbv.h> |
|
26 #include <AknGridM.h> |
|
27 #include <eiklabel.h> |
|
28 |
|
29 // CLASS DECLARATION |
|
30 |
|
31 /** |
|
32 * @c CAknGridView handles the drawing, the mapping of the grid data index |
|
33 * to the underlying listbox index (and vice versa) as well as the movement |
|
34 * around the grid. Differentiation is needed between a data index and the |
|
35 * list box index since the inherited list box code handles the top, bottom |
|
36 * and current indexes as though everything is order topdown and left to |
|
37 * right. This is no good for grid that maybe order in 8 different |
|
38 * ways so need conversion between list box index and actual data |
|
39 * index. |
|
40 * List box index is the index for the data item according to the |
|
41 * snaking list box format of numbering data items. |
|
42 * Data index is the actual index in the grid according to the |
|
43 * ordering applied to the data by the user. |
|
44 * Note: the logical position is the intermediate form used to map |
|
45 * from a list box index to a data index or vi sa versa. It is |
|
46 * essentialy the position of the item in relation to the top left |
|
47 * corner of the grid. I.e. the top left position has logical |
|
48 * position 0,0. |
|
49 * |
|
50 * @since 0.9 |
|
51 * @lib avkon.lib |
|
52 */ |
|
53 class CAknGridView : public CListBoxView |
|
54 { |
|
55 public: |
|
56 /** Enumeration flags for grid.*/ |
|
57 enum TGridFlags |
|
58 { |
|
59 /** Vertical is primary direction.*/ |
|
60 EPrimaryIsVertical = 0x0001, |
|
61 /** From top to bottom.*/ |
|
62 ETopToBottom = 0x0002, |
|
63 /** From left to right.*/ |
|
64 ELeftToRight = 0x0004 |
|
65 }; |
|
66 /** Enumeration for different scrolling types.*/ |
|
67 enum TScrollingType |
|
68 { |
|
69 /** Scrolling follows items and stops.*/ |
|
70 EScrollFollowsItemsAndStops, |
|
71 /** Scrolling follows items and loops.*/ |
|
72 EScrollFollowsItemsAndLoops, |
|
73 /** Scrolling follows grid. */ |
|
74 EScrollFollowsGrid, |
|
75 /** Scrolling stops. */ |
|
76 EScrollStops, |
|
77 /** Scrolls one line and stops.*/ |
|
78 EScrollIncrementLineAndStops, |
|
79 /** Scrolls one line and loops.*/ |
|
80 EScrollIncrementLineAndLoops |
|
81 }; |
|
82 /** Enumeration flags for different layouts.*/ |
|
83 struct SGrid |
|
84 { |
|
85 /** Current size of entire grid. */ |
|
86 TSize iGridDimensions; |
|
87 /** Flags. */ |
|
88 TInt iGridFlags; |
|
89 /** Size of the viewable area ( iColsInView * iRowsInView ). */ |
|
90 TInt iPageSize; |
|
91 /** The number of columns in the viewable area. */ |
|
92 TInt iColsInView; |
|
93 /** The number of rows in the viewable area. */ |
|
94 TInt iRowsInView; |
|
95 /** The size of gap between items (height and width). */ |
|
96 TSize iSizeBetweenItems; |
|
97 /** The size of an item. */ |
|
98 TSize iSizeOfItems; |
|
99 }; |
|
100 |
|
101 protected: |
|
102 /** Enumeration flags for pages.*/ |
|
103 enum TPageIndex |
|
104 { |
|
105 /** Previous page.*/ |
|
106 EPreviousPage, |
|
107 /** Next page.*/ |
|
108 ENextPage, |
|
109 /** First page. */ |
|
110 EHome, |
|
111 /** Last page.*/ |
|
112 EEnd |
|
113 }; |
|
114 /* Enumeration of position of current index.*/ |
|
115 enum TPositionCurrentIndex |
|
116 { |
|
117 /** Page. */ |
|
118 EPage, |
|
119 /** Column.*/ |
|
120 EColumn, |
|
121 /** Opposite corner.*/ |
|
122 EOppositeCorner |
|
123 }; |
|
124 |
|
125 public: |
|
126 /** |
|
127 * Default C++ constructor. |
|
128 */ |
|
129 IMPORT_C CAknGridView(); |
|
130 |
|
131 /** |
|
132 * Destructor. |
|
133 */ |
|
134 IMPORT_C virtual ~CAknGridView(); |
|
135 |
|
136 // actual <-> listbox index conversion routines |
|
137 /** |
|
138 * Returns the actual index of given listbox index. |
|
139 * @param aListBoxIndex The index of the listbox. |
|
140 * @return The actual data index. |
|
141 */ |
|
142 IMPORT_C TInt ActualDataIndex(TInt aListBoxIndex) const; |
|
143 |
|
144 /** |
|
145 * Returns the listbox index of given data index. |
|
146 * @param aDataIndex The index of the actual data. |
|
147 * @return The index in listbox. |
|
148 */ |
|
149 IMPORT_C TInt ListBoxIndex(TInt aDataIndex) const; |
|
150 |
|
151 /** |
|
152 * Returns the current data index with respect to the ordering of the cells |
|
153 * in the grid. |
|
154 * @return Current data index. |
|
155 */ |
|
156 IMPORT_C TInt CurrentDataIndex() const; |
|
157 |
|
158 /** |
|
159 * Sets the current data index with a value given with respect to the |
|
160 * ordering of the cells in the grid. |
|
161 * @param aDataIndex The index to be set. |
|
162 */ |
|
163 IMPORT_C void SetCurrentDataIndex(TInt aDataIndex); |
|
164 |
|
165 /** |
|
166 * Sets the form of scroll to activate upon reaching the limit when moving |
|
167 * in the primary direction of grid, primary meaning whether the items are |
|
168 * organised vertically or horizontally. |
|
169 * @param aScrollingType The primary scrolling type. |
|
170 */ |
|
171 IMPORT_C void SetPrimaryScrollingType(TScrollingType aScrollingType); |
|
172 /** |
|
173 * Sets the form of scroll to activate upon reaching the limit when moving |
|
174 * in the secondary direction of grid. |
|
175 * @param aSecondaryScrolling The secondary scrolling type. |
|
176 */ |
|
177 IMPORT_C void SetSecondaryScrollingType(TScrollingType aSecondaryScrolling); |
|
178 |
|
179 /** |
|
180 * Checks that number of cells in the grid is always enough to fill the |
|
181 * current grid dimensions. This method should be called after any method |
|
182 * that may alter the amount of data within the grid. |
|
183 * @param aGridDimensions Grid diemnsions. |
|
184 */ |
|
185 IMPORT_C void SetGridCellDimensions(TSize aGridDimensions); |
|
186 |
|
187 /** |
|
188 * Returns the current grid dimensions. |
|
189 * @return The size of the current grid. |
|
190 */ |
|
191 IMPORT_C TSize GridCellDimensions() const; |
|
192 /** |
|
193 * Sets the size of the spaces between items. |
|
194 * @param aSizeOfSpaceBetweenItems The size of the spaces between items. |
|
195 */ |
|
196 IMPORT_C void SetSpacesBetweenItems(TSize aSizeOfSpaceBetweenItems); |
|
197 |
|
198 /** |
|
199 * Returns @c ETrue if the primary dimension of the grid is vertical. |
|
200 * @return @ETrue if vertical is set as primary, otherwise @c EFalse. |
|
201 */ |
|
202 IMPORT_C TBool IsPrimaryVertical() const; |
|
203 |
|
204 /** |
|
205 * Converts a logical position on the grid, where the co-ordinates are with |
|
206 * respect to the top left hand corner of the grid, to an index for the cell |
|
207 * with respect to the ordering of the cells in the grid. |
|
208 * @param aItemIndex Reference to the index for the cell in the grid. |
|
209 * @param aRowIndex The row in the grid. |
|
210 * @param aColIndex The column in the grid. |
|
211 */ |
|
212 IMPORT_C void DataIndexFromLogicalPos( |
|
213 TInt& aItemIndex, |
|
214 TInt aRowIndex, |
|
215 TInt aColIndex) const; |
|
216 |
|
217 /** |
|
218 * Converts an index for a cell in the grid, given with respect to the |
|
219 * ordering of the cells in the grid, to a logical position on the grid, |
|
220 * where the co-ordinates are with respect to the top left hand corner of |
|
221 * the grid. |
|
222 * @param aItemIndex The index for the cell in the grid. |
|
223 * @param aRowIndex Reference to the row in the grid. |
|
224 * @param aColIndex Reference to the column in the grid. |
|
225 */ |
|
226 IMPORT_C void LogicalPosFromDataIndex( |
|
227 TInt aItemIndex, |
|
228 TInt& aRowIndex, |
|
229 TInt& aColIndex) const; |
|
230 |
|
231 /** |
|
232 * Converts a CEikListBox index for a cell in the grid, given with respect |
|
233 * to the snaking listbox top down, left to right structure underlying the |
|
234 * grid structure, to a logical position on the grid, where the co-ordinates |
|
235 * are with respect to the top left hand corner of the grid. |
|
236 * @param aItemIndex Reference to the index for the cell in the grid. |
|
237 * @param aRowIndex The row in the grid. |
|
238 * @param aColIndex The column in the grid. |
|
239 */ |
|
240 IMPORT_C void ListBoxIndexFromLogicalPos( |
|
241 TInt& aItemIndex, |
|
242 TInt aRowIndex, |
|
243 TInt aColIndex) const; |
|
244 /** |
|
245 * Converts a logical position on the grid, where the co-ordinates are with |
|
246 * respect to the top left hand corner of the grid, to a CEikListBox index |
|
247 * for the cell with respect to the snaking listbox top down, left to right |
|
248 * structure underlying the grid structure. |
|
249 * @param aItemIndex The index for the cell in the grid. |
|
250 * @param aRowIndex Reference to the row in the grid. |
|
251 * @param aColIndex Reference to the column in the grid. |
|
252 */ |
|
253 IMPORT_C void LogicalPosFromListBoxIndex( |
|
254 TInt aItemIndex, |
|
255 TInt& aRowIndex, |
|
256 TInt& aColIndex) const; |
|
257 |
|
258 /** |
|
259 * Draws empty grid list. |
|
260 */ |
|
261 IMPORT_C virtual void DrawEmptyList() const; |
|
262 |
|
263 /** |
|
264 * Grid initialisation function. |
|
265 * @param aGridDetails Struct of grid details. |
|
266 */ |
|
267 IMPORT_C void SetGridDetails(SGrid aGridDetails); |
|
268 |
|
269 /** |
|
270 * This moves to the item and draws the grid in the right place. |
|
271 * @param aItemIndex The wanted item index. |
|
272 * @param aSelectionMode Mode for modifying the selection. |
|
273 */ |
|
274 IMPORT_C void MoveToItemIndexL(TInt aItemIndex, TSelectionMode aSelectionMode); |
|
275 |
|
276 /** |
|
277 * This function returns the number of visible columns. |
|
278 * @return The number of visible columns in view. |
|
279 */ |
|
280 IMPORT_C TInt NumberOfColsInView() const; |
|
281 |
|
282 /** |
|
283 * This function returns the number of visible rows. |
|
284 * @return The number of visible rows in view. |
|
285 */ |
|
286 IMPORT_C TInt NumberOfRowsInView() const; |
|
287 |
|
288 /** |
|
289 * Moves cursor with repeats. |
|
290 * @param aNext ETrue if next, EFalse if previous. |
|
291 * @param aSelectionMode selection mode. |
|
292 * @param aAmount Amount of steps to move. |
|
293 * @since S60 3.2 |
|
294 */ |
|
295 void MoveCursorWithRepeatsL( |
|
296 TBool aNextOrPrev, |
|
297 TSelectionMode aSelectionMode, |
|
298 TInt aAmount ); |
|
299 |
|
300 public: // from CListBoxView |
|
301 /** |
|
302 * From @c CListBoxView. Basically empty implementation of |
|
303 * @c CListBoxView::DrawMatcherCursor. |
|
304 */ |
|
305 IMPORT_C virtual void DrawMatcherCursor(); |
|
306 |
|
307 /** |
|
308 * From @c CListBoxView. This function returns the current item in the grid |
|
309 * and -1 if there is no current item, |
|
310 * @return The current item. |
|
311 */ |
|
312 IMPORT_C TInt CurrentItemIndex() const; |
|
313 |
|
314 protected: |
|
315 /** |
|
316 * This function tests whether an item exists. |
|
317 * @param aListBoxIndex Index to test. |
|
318 * @return @c ETrue if the specified item exists, @c EFalse otherwise. |
|
319 */ |
|
320 IMPORT_C TBool ItemExists(TInt aListBoxIndex) const; |
|
321 |
|
322 public: // code moved from CSnakingListBoxView |
|
323 /** |
|
324 * This function sets the width of the grid column. This should only be |
|
325 * called via the selection box class's @c SetColumnWidth method. |
|
326 * @param aColumnWidth The required width of all columns in the view, |
|
327 * in pixels. |
|
328 */ |
|
329 IMPORT_C void SetColumnWidth(TInt aColumnWidth); |
|
330 |
|
331 /** |
|
332 * Overloaded @c MoveCursorL method to process cursor movement according to |
|
333 * orientation of the grid. |
|
334 * @param aCursorMovement The cursor movement to apply |
|
335 * etc. @c ECursorNextItem and @c ECursorPreviousItem. |
|
336 * @param aSelectionMode The selection mode of the calling list box. |
|
337 */ |
|
338 IMPORT_C virtual void MoveCursorL( |
|
339 TCursorMovement aCursorMovement, |
|
340 TSelectionMode aSelectionMode); |
|
341 |
|
342 /** |
|
343 * This function draws every visible item into the specified rectangle. |
|
344 * As implemented in @c CListBoxView, this function's argument is ignored |
|
345 * and the internal viewing rectangle is used. See @c SetViewRect(). |
|
346 * @param @c TRect* @c aClipRect = @c NULL The rectangle to draw into. |
|
347 */ |
|
348 IMPORT_C virtual void Draw(const TRect* aClipRect = NULL) const; |
|
349 |
|
350 /** |
|
351 * This has been overloaded to ensure that only valid cells are drawn and |
|
352 * not the empty cells. |
|
353 * @param aItemIndex Index number of the item to draw. |
|
354 */ |
|
355 IMPORT_C virtual void DrawItem(TInt aItemIndex) const; |
|
356 |
|
357 /** |
|
358 * This function gets the position of the top left corner of the specified |
|
359 * item, in pixels. |
|
360 * @param aItemIndex An item in the model. |
|
361 * @return @c TPoint position of the top left corner of the item, in pixels. |
|
362 */ |
|
363 IMPORT_C virtual TPoint ItemPos(TInt aItemIndex) const; |
|
364 |
|
365 /** |
|
366 * This function has been overloaded to draw items correctly. Recalculates |
|
367 * the bottom item’s index. This is called by the list box control when |
|
368 * either the size or the number of items in its model changes. |
|
369 */ |
|
370 IMPORT_C virtual void CalcBottomItemIndex(); |
|
371 |
|
372 /** |
|
373 * This function gets the item the view would need to be moved to in order |
|
374 * to make the specified item visible. |
|
375 * @param aItemIndex The item to make visible. |
|
376 * @return The item to scroll to to make @c aItemIndex visible. |
|
377 */ |
|
378 IMPORT_C virtual TInt CalcNewTopItemIndexSoItemIsVisible(TInt aItemIndex) const; |
|
379 |
|
380 /** |
|
381 * This function draws every item between the start and end indices |
|
382 * inclusively. |
|
383 * @param aStartItemIndex The first item to draw. |
|
384 * @param aEndItemIndex The final item to draw. |
|
385 */ |
|
386 IMPORT_C virtual void DrawItemRange(TInt aStartItemIndex, TInt aEndItemIndex) const; |
|
387 |
|
388 /** |
|
389 * This function gets the width of all columns in the view. |
|
390 * @return The width of all columns in the view, in pixels. |
|
391 */ |
|
392 inline TInt ColumnWidth() const; |
|
393 |
|
394 /** |
|
395 * Sets which item appears at the top left corner of the view. The function |
|
396 * changes items displayed in the view appropriately. |
|
397 * @param aItemIndex Index of the item to set at the top left. |
|
398 */ |
|
399 IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex); |
|
400 |
|
401 /** |
|
402 * This function sets item height in pixels. |
|
403 * @param aItemHeight New height in pixels for this view’s items. |
|
404 */ |
|
405 IMPORT_C virtual void SetItemHeight(TInt aItemHeight); |
|
406 |
|
407 /* |
|
408 * This function converts an (x, y) pixel position to an item index. |
|
409 * @param aPosition Pixel position in the viewing rectangle. |
|
410 * @param aItemIndex Reference to the item index. |
|
411 * @return Whether there was an item at aPosition. |
|
412 */ |
|
413 IMPORT_C virtual TBool XYPosToItemIndex(TPoint aPosition, TInt& aItemIndex) const; |
|
414 |
|
415 /** |
|
416 * Calculates the data width in columns. @c iDataWidth is calculated based on |
|
417 * model and drawer information. |
|
418 */ |
|
419 IMPORT_C virtual void CalcDataWidth(); |
|
420 |
|
421 /** |
|
422 * Gets the visible width of the specified rectangle in pixels. |
|
423 * @param aRect Reference to the rectangle for which to get the visible |
|
424 * width. |
|
425 * @return Visible width of aRect in pixels. |
|
426 */ |
|
427 IMPORT_C virtual TInt VisibleWidth(const TRect& aRect) const; |
|
428 |
|
429 /** |
|
430 * Makes the specified item visible by moving the view location and |
|
431 * redrawing the control. Index of the item to make visible. |
|
432 * @param aItemIndex Index of the item to make visible. |
|
433 * @return @c ETrue if the control was redrawn, @c EFalse if no redraw |
|
434 * happened (i.e. the item was already visible, or redraw was disabled). |
|
435 */ |
|
436 IMPORT_C virtual TBool ScrollToMakeItemVisible(TInt aItemIndex); |
|
437 |
|
438 /** |
|
439 * Gets the number of columns that this view would need to be scrolled by |
|
440 * to make the specified item visible. The function returns 0 if no |
|
441 * scrolling is needed. @c ScrollToMakeItemVisible() uses this function. |
|
442 * @param aItemIndex Item to make visible. |
|
443 * @return The number of columns to scroll, or zero if no scrolling is |
|
444 * needed. |
|
445 */ |
|
446 IMPORT_C virtual TInt CalculateHScrollOffsetSoItemIsVisible(TInt aItemIndex); |
|
447 |
|
448 /** |
|
449 * Gets the size of the specified item. |
|
450 * @param aItemIndex=0 The index of the item whose size this call is to get. |
|
451 * @return @c TSize The size of the item in pixels. |
|
452 */ |
|
453 IMPORT_C virtual TSize ItemSize(TInt aItemIndex=0) const; |
|
454 |
|
455 /** |
|
456 * Converts an item index into the (row, column) pair describing that item. |
|
457 * @param aItemIndex The item index. |
|
458 * @param aRowIndex Reference to the row index. |
|
459 * @param aColIndex Reference the column index. |
|
460 */ |
|
461 IMPORT_C void CalcRowAndColIndexesFromItemIndex(TInt aItemIndex, TInt& aRowIndex, TInt& aColIndex) const; |
|
462 |
|
463 /** |
|
464 * This function converts a row/column pair into the item index for that |
|
465 * item. |
|
466 * @param aItemIndex Reference to the item index. |
|
467 * @param aRowIndex Row index of the item. |
|
468 * @param aColIndex Column index of the item. |
|
469 */ |
|
470 IMPORT_C void CalcItemIndexFromRowAndColIndexes(TInt& aItemIndex, TInt aRowIndex, TInt aColIndex) const; |
|
471 |
|
472 protected: // code moved from CSnakingListBoxView |
|
473 /** |
|
474 * This function draws every item in every column between the start and end |
|
475 * columns inclusively. |
|
476 * @param aStartColIndex The first column to draw. |
|
477 * @param aEndColIndex The last column to draw. |
|
478 */ |
|
479 IMPORT_C void DrawColumnRange(TInt aStartColIndex, TInt aEndColIndex) const; |
|
480 |
|
481 /** |
|
482 * This function clears each item’s rectangle between the specified start |
|
483 * and finish item’s indexes. |
|
484 * @param aStartItemIndex The first item to clear. |
|
485 * @param aEndItemIndex The last item to clear. |
|
486 */ |
|
487 IMPORT_C void ClearUnusedItemSpace(TInt aStartItemIndex, TInt aEndItemIndex) const; |
|
488 |
|
489 /** |
|
490 * This function updates the horizontal scroll offset (iHScrollOffset) |
|
491 * based on the top item’s index. This function is called internally by |
|
492 * @c CEikSnakingListBoxes when needed. |
|
493 */ |
|
494 IMPORT_C void UpdateHScrollOffsetBasedOnTopItemIndex(); |
|
495 |
|
496 protected: |
|
497 /** |
|
498 * This inline function is grid model helper. |
|
499 * @return A pointer to @c CAknGridM object. |
|
500 */ |
|
501 inline CAknGridM* GridModel() const; |
|
502 |
|
503 /** |
|
504 * This function handles movement routines. |
|
505 * @param aCursorMovement Handles cursor movements etc. @c ECursorNextItem |
|
506 * and @c ECursorPreviousItem. |
|
507 * @param aSelectionMode Modes for modifying the selection. |
|
508 */ |
|
509 IMPORT_C void DoMoveL(TCursorMovement aCursorMovement, TSelectionMode aSelectionMode); |
|
510 |
|
511 private: |
|
512 // movement handling routines |
|
513 IMPORT_C TInt SearchByLines(TInt aX, TInt aY, TCursorMovement aCursorMovement, TBool aBeginSearchOnIndex = EFalse); |
|
514 IMPORT_C TInt FindNextItem(TInt aItemIndex, TBool aLookDown, TBool aLookRight, TBool aFirstLookHorizontal, TBool aBeginSearchOnIndex = EFalse); |
|
515 TBool IsEdgePassed(TInt aItemIndex, TBool aLookDown, TBool aLookRight, TBool aFirstLookHorizontal, TBool aBeginSearchOnIndex, TInt& aNewIndex); |
|
516 |
|
517 TBool IsMoveRight(TCursorMovement aCursorMovement); |
|
518 TBool IsMoveDown(TCursorMovement aCursorMovement); |
|
519 private: // overridden from CListBoxView |
|
520 IMPORT_C virtual TAny* Reserved_1(); |
|
521 |
|
522 private: |
|
523 |
|
524 /** |
|
525 * Draws the portion of the grid view rectangle that contains no items. |
|
526 */ |
|
527 void DrawUnusedViewPortion() const; |
|
528 |
|
529 private: |
|
530 TScrollingType iScrollingType; |
|
531 TScrollingType iScrollInSecondaryDimension; |
|
532 |
|
533 SGrid iGridDetails; |
|
534 TInt iSpare[2]; |
|
535 }; |
|
536 |
|
537 inline CAknGridM* CAknGridView::GridModel() const |
|
538 { |
|
539 return STATIC_CAST(CAknGridM*,iModel); |
|
540 } |
|
541 |
|
542 inline TInt CAknGridView::ColumnWidth() const |
|
543 { return iGridDetails.iSizeOfItems.iWidth; } |
|
544 |
|
545 #endif // __AKNGRIDVIEW_H__ |