1.1 --- a/epoc32/include/mw/akngrid.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/akngrid.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,531 @@
1.4 -akngrid.h
1.5 +/*
1.6 +* Copyright (c) 2002-2004 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 +* This is a concrete class for the handling of a grid. The class handles a
1.20 +* rectangular grid arrangement of items held in any linear ordering i.e
1.21 +* cells ordered top to bottom and left, left to right and down etc.
1.22 +*
1.23 +*
1.24 +*/
1.25 +
1.26 +
1.27 +#if !defined(__AKNGRID_H__)
1.28 +#define __AKNGRID_H__
1.29 +
1.30 +// INCLUDES
1.31 +#include <eiktxlbx.h>
1.32 +#include <eiklbv.h>
1.33 +#include <eikfrlbd.h>
1.34 +#include <eikfrlb.h>
1.35 +
1.36 +#include <AknGridM.h>
1.37 +#include <AknGridView.h>
1.38 +#include <Aknappui.h>
1.39 +
1.40 +// CLASS PREDEFINITIONS
1.41 +class CAknGridExtension;
1.42 +
1.43 +// CLASS DECLARATION
1.44 +
1.45 +/**
1.46 +* Application grid handling class from Avkon.
1.47 +* Provides support for ordering application grids items.
1.48 +*
1.49 +* @since Series 60 0.9
1.50 +*/
1.51 +class CAknGrid : public CEikListBox
1.52 + {
1.53 +private:// enums
1.54 + enum TIndicatorEvent
1.55 + {
1.56 + EMove,
1.57 + EChangeNumOfItems,
1.58 + EResize
1.59 + };
1.60 +public:
1.61 +
1.62 + /**
1.63 + * Base class default constructor.
1.64 + * @return A pointer to a new @c CAknGrid object.
1.65 + */
1.66 + IMPORT_C CAknGrid();
1.67 +
1.68 + /**
1.69 + * Destructor.
1.70 + */
1.71 + IMPORT_C virtual ~CAknGrid();
1.72 +
1.73 + /**
1.74 + * This function gives @c CAknGridM class pointer to @c CAknGrid class.
1.75 + * Usually, the @c CAknGridM class object is instantiated automatically
1.76 + * during the construction phase of the @c CAknGrid object. If an
1.77 + * application programmer provides their own grid model class, the
1.78 + * application programmer must instantiate their own grid model class object
1.79 + * and give it to the @c CAknGrid object using the @c SetModel function
1.80 + * before calling the @c ConstructL/ConstructFromResourceL function.
1.81 + * @param aModel Pointer to @c CAknGridM class.
1.82 + */
1.83 + IMPORT_C void SetModel(CAknGridM* aModel);
1.84 +
1.85 + /**
1.86 + * This is Symbian default constructor. The @c ConstructL function needs to
1.87 + * be called in case resource data is not used. If a leave occurs the
1.88 + * framework generates a Symbian Leave code.
1.89 + * @param aPatent A CCoeControl pointer.
1.90 + * @param aFlags Parameter for @c CEikListBox constructor. If the
1.91 + * parameter is missing default value is 0.
1.92 + */
1.93 + IMPORT_C void ConstructL(const CCoeControl* aParent, TInt aFlags = 0);
1.94 +
1.95 + /**
1.96 + * The @c ConstructFromResourceL function needs to be called in case
1.97 + * resource data is used. Usually, the @c CAknGridM class object is
1.98 + * instantiated automatically during the construction phase of the
1.99 + * @c CAknGrid object. If an application programmer provides their own grid
1.100 + * model class, the application programmer must instantiate their own grid
1.101 + * model class object and give it to the @c CAknGrid object using the
1.102 + * @c SetModel function before calling the
1.103 + * @c ConstructL/ConstructFromResourceL function. If a leave occurs the
1.104 + * framework generates a Symbian Leave code.
1.105 + * @param aReader Construct controls from resource file.
1.106 + */
1.107 + IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);
1.108 +
1.109 + /**
1.110 + * Sets the orientation of the grid, either vertical or horizontal, the
1.111 + * ordering of the data and the size of the primary dimension of the
1.112 + * grid. The value for the parameter @c aNumOfItemsInPrimaryOrient must be
1.113 + * greater than zero since this determines the number of items (be it rows
1.114 + * or columns) in the primary orientation of the grid. If a leave occurs
1.115 + * the framework generates a Symbian Leave code.
1.116 + * @param aVerticalOrientation Items vertical orientation.
1.117 + * @param aLeftToRight @c ETrue left to right.
1.118 + * @param aTopToBottom @c ETrue top to bottom.
1.119 + * @param aNumOfItemsInPrimaryOrient Number of items in primary orient.
1.120 + * @param aNumOfItemsInSecondaryOrient Number of items in Secondary orient.
1.121 + * @param aSizeOfItems Item size.
1.122 + * @param aWidthOfSpaceBetweenItems =0 Width of space between items.
1.123 + * @param aHeightOfSpaceBetweenItems =0 Height of space between items.
1.124 + */
1.125 + IMPORT_C void SetLayoutL(TBool aVerticalOrientation,
1.126 + TBool aLeftToRight,
1.127 + TBool aTopToBottom,
1.128 + TInt aNumOfItemsInPrimaryOrient,
1.129 + TInt aNumOfItemsInSecondaryOrient,
1.130 + TSize aSizeOfItems,
1.131 + TInt aWidthOfSpaceBetweenItems=0,
1.132 + TInt aHeightOfSpaceBetweenItems=0);
1.133 +
1.134 + /**
1.135 + * Sets the layout from a resource. Layout includes orientation (either
1.136 + * vertical or horizontal), horizontal and vertical direction of numbering,
1.137 + * the number of items in the primary and secondary orientation, and the
1.138 + * primary and secondary scrolling types. If a leave occurs the framework
1.139 + * generates a Symbian Leave code.
1.140 + * @param aReader Constructs controls from a resource file.
1.141 + */
1.142 + IMPORT_C void SetLayoutFromResourceL(TResourceReader& aReader);
1.143 +
1.144 + /**
1.145 + * Sets the movement of the cursor with respect to scrolling when the
1.146 + * end item in the current row or column, whichever is the primary
1.147 + * orientation of the data items, is encountered. The movement maybe
1.148 + * either stop, loop back to same row or column or move onto the
1.149 + * next logical data item in the sequence.
1.150 + * @param aScrollingType Items scrolling type enum definition.
1.151 + */
1.152 + IMPORT_C void SetPrimaryScrollingType(CAknGridView::TScrollingType aScrollingType);
1.153 +
1.154 + /**
1.155 + * Sets the movement of the cursor with respect to scrolling when the
1.156 + * end item in the secondary dimension of the grid is encountered.
1.157 + * The movement maybe either stop, loop back back to same row or column
1.158 + * or move onto the next logical data item in the sequence.
1.159 + * @param aSecondaryScrolling Secondary scrolling type enum definition.
1.160 + */
1.161 + IMPORT_C void SetSecondaryScrollingType(CAknGridView::TScrollingType aSecondaryScrolling);
1.162 +
1.163 + /**
1.164 + * Sets the starting position of the data within the grid. A blank page
1.165 + * cannot be accessed (since cannot move into empty cells) so a totally
1.166 + * blank page is the same as if the page never existed since the user
1.167 + * cannot scroll into it. For this reason it is suggested that the start
1.168 + * position be no more than one page into the grid. If a leave occurs
1.169 + * the framework generates a Symbian Leave code.
1.170 + * @param aGridStartPosition Parameter manipulate the grid's starting
1.171 + * position.
1.172 + */
1.173 + IMPORT_C void SetStartPositionL(TPoint aGridStartPosition);
1.174 +
1.175 + /**
1.176 + * @c CurrentDataIndex retrieves the index of the selection. In grids, you
1.177 + * should use this method instead of @c CEikListBox::CurrentItemIndex(),
1.178 + * when you are manipulating data stored in the grid's @c ItemTextArray.
1.179 + * While @c CurrentItemIndex() returns the same value as
1.180 + * @c CurrentItemIndex() on most phones, there will be difference in some
1.181 + * language variants where text reading/writing direction is different from
1.182 + * left-to-right.
1.183 + * @return A current position of highlight.
1.184 + */
1.185 + IMPORT_C TInt CurrentDataIndex() const;
1.186 +
1.187 + /**
1.188 + * Moves the cursor to the required grid data index.
1.189 + * @param aDataIndex Data index value.
1.190 + */
1.191 + IMPORT_C void SetCurrentDataIndex(TInt aDataIndex);
1.192 +
1.193 + /**
1.194 + * The grid position function. Gives the data index by using grid's
1.195 + * position. The position must be given from the top left corner. If
1.196 + * the function returns -1 the item's position is invalid.
1.197 + * @param aGridPosition The data item's co-ordinate values.
1.198 + * @return Activated item's index value.
1.199 + */
1.200 + IMPORT_C TInt IndexOfPosition(TPoint aGridPosition) const;
1.201 +
1.202 + /**
1.203 + * The grid position function. Gives the data item's co-ordinate values
1.204 + * by using item's index value.
1.205 + * @param aItemIndex The data item's index value.
1.206 + * @return @c TPoint co-ordinate values of active item.
1.207 + */
1.208 + IMPORT_C TPoint PositionAtIndex(TInt aItemIndex) const;
1.209 +
1.210 + /**
1.211 + * Item drawer. Gets the pointer to the grid class.
1.212 + * @return A pointer to @c CFormattedCellListBoxItemDrawer object.
1.213 + */
1.214 + IMPORT_C CFormattedCellListBoxItemDrawer* ItemDrawer() const;
1.215 +
1.216 + /**
1.217 + * Function sets a grid text to the data item. If a leave occurs the
1.218 + * framework generates a Symbian Leave code.
1.219 + * @since Series S60 3.0
1.220 + * @param aText Descriptor parameter.
1.221 + */
1.222 + IMPORT_C void SetEmptyGridTextL(const TDesC& aText);
1.223 +
1.224 + /**
1.225 + * This function sets the empty grid text.
1.226 + * @return A pointer to the grid text descriptor.
1.227 + */
1.228 + inline const TDesC* EmptyGridText() const;
1.229 +
1.230 +public:
1.231 +
1.232 + /**
1.233 + * This function creates a new object and returns pointer to it. If the
1.234 + * leave occurs the framework generates a Symbian Leave code.
1.235 + * @return A pointer to @c CListBoxView class.
1.236 + */
1.237 + IMPORT_C virtual CListBoxView* MakeViewClassInstanceL();
1.238 +
1.239 + /**
1.240 + * This function sets the column width of the grid. Column width cannot be
1.241 + * set in a horizontal grid since the number of columns in the grid is
1.242 + * defined by the initialising call to @c SetLayoutL. The column width
1.243 + * cannot be larger than the width of the viewing rectangle.
1.244 + * @param aColumnWidth A parameter defines a width of the column.
1.245 + */
1.246 + IMPORT_C void SetColumnWidth(TInt aColumnWidth);
1.247 +
1.248 + /**
1.249 + * This function gives a width of the column.
1.250 + * @return A width of the column.
1.251 + */
1.252 + IMPORT_C TInt ColumnWidth() const;
1.253 +
1.254 +public: //from CEikListBox
1.255 +
1.256 + /**
1.257 + * This function updates the scrollbars, including item position. This
1.258 + * function is called when the size of the scrollbars or data changes. If
1.259 + * the leave occurs the framework generates a Symbian Leave code.
1.260 + */
1.261 + IMPORT_C virtual void UpdateScrollBarsL();
1.262 +
1.263 + /**
1.264 + * This function should be called after one or more items have been added to
1.265 + * the grid. If a leave occurs the framework generates a Symbian Leave
1.266 + * code.
1.267 + */
1.268 + IMPORT_C void HandleItemAdditionL();
1.269 +
1.270 + /**
1.271 + * This function should be called after one or more items have been removed
1.272 + * from the grid. If a leave occurs the framework generates a Symbian
1.273 + * Leave code.
1.274 + */
1.275 + IMPORT_C void HandleItemRemovalL();
1.276 +
1.277 + /**
1.278 + * This function is from @c CEikAppUi, handles key events. If a leave
1.279 + * occurs the framework generates a Symbian Leave code.
1.280 + * @param aKeyEvent Event to handled.
1.281 + * @param aType of the key event.
1.282 + * @return Response code ( @c EKeyWasConsumed, @c EKeyWasNotConsumed )
1.283 + */
1.284 + IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);
1.285 +
1.286 + /**
1.287 + * This function sets the row height of the grid. Row height cannot be set
1.288 + * in a vertical grid since the number of rows in the grid is defined by
1.289 + * the initialising call to @c SetLayoutL. The row height cannot be larger
1.290 + * than the height of the viewing rectangle. If a leave occurs the
1.291 + * framework generates a Symbian Leave code.
1.292 + * @param aHeight The height of the item's rows.
1.293 + */
1.294 + IMPORT_C void SetItemHeightL(TInt aHeight);
1.295 +
1.296 + /**
1.297 + * This function handles size changes. This routine assumes that
1.298 + * @c SetLayoutL has been called to set up the grid.
1.299 + */
1.300 + IMPORT_C void SizeChanged();
1.301 +
1.302 + /**
1.303 + * This function creates a new object and returns pointer to
1.304 + * @c CTextListBoxModel class.
1.305 + * @return A pointer to @c CTextListBoxModel object.
1.306 + */
1.307 + IMPORT_C CTextListBoxModel* Model() const;
1.308 +
1.309 + /**
1.310 + * This function handles viewable rectangle.
1.311 + * @param aRect Rectangle parameter.
1.312 + */
1.313 + IMPORT_C void SetRect(const TRect& aRect);
1.314 +
1.315 + /**
1.316 + * This function is called when the grid's items, item's data and scroll
1.317 + * bars has been changed. This implementation ensures that the current
1.318 + * item is visible after resize. If a leave occurs the framework generates
1.319 + * a Symbian Leave code.
1.320 + */
1.321 + IMPORT_C virtual void HandleViewRectSizeChangeL();
1.322 +
1.323 + /**
1.324 + * This function sets top item index.
1.325 + * @param aItemIndex Item index value.
1.326 + */
1.327 + IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;
1.328 +
1.329 + /**
1.330 + * This function handles resource changes.
1.331 + * @since Series S60 2.6.
1.332 + * @param aType Message type.
1.333 + */
1.334 + IMPORT_C virtual void HandleResourceChange(TInt aType);
1.335 +
1.336 + /**
1.337 + * Indicates whether the control should be redrawn now. If @c ENoDrawNow,
1.338 + * the function has no immediately effect. EDrawNow redraw control
1.339 + * immediately.
1.340 + * @since Series S60 3.0.
1.341 + */
1.342 + IMPORT_C void FocusChanged(TDrawNow aDrawNow);
1.343 +
1.344 +public: // From CCoeControl
1.345 + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
1.346 +
1.347 +protected: // from CEikListBox
1.348 +
1.349 + /**
1.350 + * This function scroll horizontal by one column when the left/right scroll
1.351 + * arrows (i.e. the nudge buttons) are tapped.
1.352 + * @return A nudge value when the buttons are pressed.
1.353 + */
1.354 + IMPORT_C virtual TInt HorizontalNudgeValue() const;
1.355 +
1.356 + /**
1.357 + * This function gets the granularity for horizontal scrolls. The
1.358 + * granularity is the minimum size of a horizontal move of the client area.
1.359 + * @return A grain size for horizontal scrolling in pixels.
1.360 + */
1.361 + IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;
1.362 +
1.363 + /**
1.364 + * This function called by various functions of this class to ensure that
1.365 + * the top item index is always a sane value. The implementation in
1.366 + * @c CEikListBox tries to ensure the minimum amount of white space at the
1.367 + * bottom of the list box. Note that this function does not affect the
1.368 + * current item index.
1.369 + */
1.370 + IMPORT_C virtual void AdjustTopItemIndex() const;
1.371 +
1.372 + /**
1.373 + * This function handles drag events. If a leave occurs the framework
1.374 + * generates a Symbian Leave code.
1.375 + * @param aPointerPos The position of the @c TPointerEvent for which this
1.376 + * handler is invoked.
1.377 + */
1.378 + IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos);
1.379 +
1.380 + /**
1.381 + * This function calculates the client area. This method is called by
1.382 + * various functions of this class to recalculate the extent of the client
1.383 + * area from @c iViewRect. This implementation takes into account any
1.384 + * rounding of the viewing rectangle made to fit a whole number of items.
1.385 + * @param aClientRect On return contains a size for the client area in
1.386 + * pixels.
1.387 + */
1.388 + IMPORT_C virtual void RestoreClientRectFromViewRect(TRect& aClientRect) const;
1.389 +
1.390 + /**
1.391 + * This function rounds down the height of the rectangle (if necessary) so
1.392 + * that only a whole number of items can be displayed inside the list box.
1.393 + * @param aRect Rectangle parameter.
1.394 + */
1.395 + IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(TRect& aRect) const;
1.396 +
1.397 + /**
1.398 + * Updates the position of grids scroll bars’ thumbs to reflect the vertical
1.399 + * position of selector.
1.400 + */
1.401 + IMPORT_C virtual void UpdateScrollBarThumbs() const;
1.402 +
1.403 + /**
1.404 + * Gets a count of the component controls of this grid.
1.405 + * @return The number of component controls.
1.406 + */
1.407 + IMPORT_C virtual TInt CountComponentControls() const;
1.408 +
1.409 +protected:
1.410 +
1.411 + /**
1.412 + * Moves to the next or previous item on the grid. If a leave occurs the
1.413 + * framework generates a Symbian Leave code.
1.414 + * @param aPoint Co-ordinate object parameter.
1.415 + */
1.416 + IMPORT_C void MoveToNextOrPreviousItemL(TPoint aPoint);
1.417 +
1.418 + /**
1.419 + * This protected function used by functions to check/alter the dimensions
1.420 + * of the grid as data items are added or removed or the size of the items
1.421 + * are altered. It also assumes that @c SetLayoutL has been called.
1.422 + * This will not leave if scrollbars have both been turned off. If a leave
1.423 + * occurs the framework generates a Symbian Leave code.
1.424 + */
1.425 + IMPORT_C virtual void CalcGridSizeL();
1.426 +
1.427 + /**
1.428 + * Creates a formatted list item drawer. If a leave occurs the framework
1.429 + * generates a Symbian Leave code.
1.430 + */
1.431 + IMPORT_C virtual void CreateItemDrawerL();
1.432 +
1.433 +private:
1.434 + __DECLARE_TEST;
1.435 +
1.436 + // grid model helper
1.437 + inline CAknGridM* GridModel() const;
1.438 +
1.439 + // grid view helper
1.440 + inline CAknGridView* GridView() const;
1.441 +
1.442 + /**
1.443 + * This function sets the size and initial layout of items. If a leave
1.444 + * occurs the framework generates a Symbian Leave code.
1.445 + * @param aOrientation
1.446 + * @param aHorizontal
1.447 + * @param aVertical
1.448 + * @param aNumOfItemsInPrimaryOrient
1.449 + * @param aNumOfItemsInSecondaryOrient
1.450 + * @param aSizeOfItems
1.451 + * @param aWidthOfSpaceBetweenItems
1.452 + * @param aHeightOfSpaceBetweenItems
1.453 + */
1.454 + void DoSetLayoutL(TInt aOrientation,
1.455 + TInt aHorizontal,
1.456 + TInt aVertical,
1.457 + TInt aNumOfItemsInPrimaryOrient,
1.458 + TInt aNumOfItemsInSecondaryOrient,
1.459 + TSize aSizeOfItems,
1.460 + TInt aWidthOfSpaceBetweenItems=0,
1.461 + TInt aHeightOfSpaceBetweenItems=0);
1.462 +
1.463 +private:
1.464 + /**
1.465 + * From CAknControl
1.466 + */
1.467 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.468 +private: // from MListBoxModel
1.469 + IMPORT_C virtual TAny* MListBoxModel_Reserved();
1.470 +
1.471 +protected:
1.472 + /**
1.473 + * From @c MEikScrollBarObserver
1.474 + *
1.475 + * This function handles scroll events caused by scroll bar.
1.476 + * It updates grid's view by event and new thumb position.
1.477 + *
1.478 + * @param aScrollBar pointer to scroll bar sent this event
1.479 + * @param aEventType type of event
1.480 + */
1.481 + IMPORT_C virtual void HandleScrollEventL(CEikScrollBar* aScrollBar, TEikScrollEvent aEventType);
1.482 +
1.483 + /**
1.484 + * From @c MObjectProvider.
1.485 + *
1.486 + * Retrieves an object of the same type as that encapsulated in aId. This
1.487 + * function is used to allow controls to ask their owners for access to
1.488 + * other objects that they own.
1.489 + *
1.490 + * @param aId An encapsulated object type ID.
1.491 + * @return Encapsulates the pointer to the object provided.
1.492 + * Note that the encapsulated pointer may be NULL.
1.493 + */
1.494 + IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
1.495 +
1.496 +
1.497 +private:
1.498 + TInt iMinColWidth;
1.499 + TBool iCurrentIsValid;
1.500 + TInt iNumOfColsInView;
1.501 + TInt iNumOfRowsInView;
1.502 + TSize iSpaceBetweenItems;
1.503 + TInt iSpare; // was iNumOfItemsInPrimaryOrient;
1.504 + TBitFlags iOrientationFlags;
1.505 + TBitFlags iHorizontalFlags;
1.506 + TBitFlags iVerticalFlags;
1.507 + CAknGridExtension *iExtension; // spare taken to use as extension class
1.508 + };
1.509 +
1.510 +/**
1.511 + * Return Model
1.512 + */
1.513 +inline CAknGridM* CAknGrid::GridModel() const
1.514 + {
1.515 + return STATIC_CAST(CAknGridM*,iModel);
1.516 + }
1.517 +
1.518 +/**
1.519 + * Return View
1.520 + */
1.521 +inline CAknGridView* CAknGrid::GridView() const
1.522 + {
1.523 + return STATIC_CAST(CAknGridView*,iView);
1.524 + }
1.525 +
1.526 +/**
1.527 + * Return text currently in the empty grid text
1.528 + */
1.529 +inline const TDesC* CAknGrid::EmptyGridText() const
1.530 + {
1.531 + return STATIC_CAST(CAknGridView*,iView)->EmptyListText();
1.532 + }
1.533 +
1.534 +#endif //__AKNGRID_H__
1.535 +