diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/akngrid.h --- a/epoc32/include/mw/akngrid.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/akngrid.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,531 @@ -akngrid.h +/* +* Copyright (c) 2002-2004 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: +* This is a concrete class for the handling of a grid. The class handles a +* rectangular grid arrangement of items held in any linear ordering i.e +* cells ordered top to bottom and left, left to right and down etc. +* +* +*/ + + +#if !defined(__AKNGRID_H__) +#define __AKNGRID_H__ + +// INCLUDES +#include +#include +#include +#include + +#include +#include +#include + +// CLASS PREDEFINITIONS +class CAknGridExtension; + +// CLASS DECLARATION + +/** +* Application grid handling class from Avkon. +* Provides support for ordering application grids items. +* +* @since Series 60 0.9 +*/ +class CAknGrid : public CEikListBox + { +private:// enums + enum TIndicatorEvent + { + EMove, + EChangeNumOfItems, + EResize + }; +public: + + /** + * Base class default constructor. + * @return A pointer to a new @c CAknGrid object. + */ + IMPORT_C CAknGrid(); + + /** + * Destructor. + */ + IMPORT_C virtual ~CAknGrid(); + + /** + * This function gives @c CAknGridM class pointer to @c CAknGrid class. + * Usually, the @c CAknGridM class object is instantiated automatically + * during the construction phase of the @c CAknGrid object. If an + * application programmer provides their own grid model class, the + * application programmer must instantiate their own grid model class object + * and give it to the @c CAknGrid object using the @c SetModel function + * before calling the @c ConstructL/ConstructFromResourceL function. + * @param aModel Pointer to @c CAknGridM class. + */ + IMPORT_C void SetModel(CAknGridM* aModel); + + /** + * This is Symbian default constructor. The @c ConstructL function needs to + * be called in case resource data is not used. If a leave occurs the + * framework generates a Symbian Leave code. + * @param aPatent A CCoeControl pointer. + * @param aFlags Parameter for @c CEikListBox constructor. If the + * parameter is missing default value is 0. + */ + IMPORT_C void ConstructL(const CCoeControl* aParent, TInt aFlags = 0); + + /** + * The @c ConstructFromResourceL function needs to be called in case + * resource data is used. Usually, the @c CAknGridM class object is + * instantiated automatically during the construction phase of the + * @c CAknGrid object. If an application programmer provides their own grid + * model class, the application programmer must instantiate their own grid + * model class object and give it to the @c CAknGrid object using the + * @c SetModel function before calling the + * @c ConstructL/ConstructFromResourceL function. If a leave occurs the + * framework generates a Symbian Leave code. + * @param aReader Construct controls from resource file. + */ + IMPORT_C void ConstructFromResourceL(TResourceReader& aReader); + + /** + * Sets the orientation of the grid, either vertical or horizontal, the + * ordering of the data and the size of the primary dimension of the + * grid. The value for the parameter @c aNumOfItemsInPrimaryOrient must be + * greater than zero since this determines the number of items (be it rows + * or columns) in the primary orientation of the grid. If a leave occurs + * the framework generates a Symbian Leave code. + * @param aVerticalOrientation Items vertical orientation. + * @param aLeftToRight @c ETrue left to right. + * @param aTopToBottom @c ETrue top to bottom. + * @param aNumOfItemsInPrimaryOrient Number of items in primary orient. + * @param aNumOfItemsInSecondaryOrient Number of items in Secondary orient. + * @param aSizeOfItems Item size. + * @param aWidthOfSpaceBetweenItems =0 Width of space between items. + * @param aHeightOfSpaceBetweenItems =0 Height of space between items. + */ + IMPORT_C void SetLayoutL(TBool aVerticalOrientation, + TBool aLeftToRight, + TBool aTopToBottom, + TInt aNumOfItemsInPrimaryOrient, + TInt aNumOfItemsInSecondaryOrient, + TSize aSizeOfItems, + TInt aWidthOfSpaceBetweenItems=0, + TInt aHeightOfSpaceBetweenItems=0); + + /** + * Sets the layout from a resource. Layout includes orientation (either + * vertical or horizontal), horizontal and vertical direction of numbering, + * the number of items in the primary and secondary orientation, and the + * primary and secondary scrolling types. If a leave occurs the framework + * generates a Symbian Leave code. + * @param aReader Constructs controls from a resource file. + */ + IMPORT_C void SetLayoutFromResourceL(TResourceReader& aReader); + + /** + * Sets the movement of the cursor with respect to scrolling when the + * end item in the current row or column, whichever is the primary + * orientation of the data items, is encountered. The movement maybe + * either stop, loop back to same row or column or move onto the + * next logical data item in the sequence. + * @param aScrollingType Items scrolling type enum definition. + */ + IMPORT_C void SetPrimaryScrollingType(CAknGridView::TScrollingType aScrollingType); + + /** + * Sets the movement of the cursor with respect to scrolling when the + * end item in the secondary dimension of the grid is encountered. + * The movement maybe either stop, loop back back to same row or column + * or move onto the next logical data item in the sequence. + * @param aSecondaryScrolling Secondary scrolling type enum definition. + */ + IMPORT_C void SetSecondaryScrollingType(CAknGridView::TScrollingType aSecondaryScrolling); + + /** + * Sets the starting position of the data within the grid. A blank page + * cannot be accessed (since cannot move into empty cells) so a totally + * blank page is the same as if the page never existed since the user + * cannot scroll into it. For this reason it is suggested that the start + * position be no more than one page into the grid. If a leave occurs + * the framework generates a Symbian Leave code. + * @param aGridStartPosition Parameter manipulate the grid's starting + * position. + */ + IMPORT_C void SetStartPositionL(TPoint aGridStartPosition); + + /** + * @c CurrentDataIndex retrieves the index of the selection. In grids, you + * should use this method instead of @c CEikListBox::CurrentItemIndex(), + * when you are manipulating data stored in the grid's @c ItemTextArray. + * While @c CurrentItemIndex() returns the same value as + * @c CurrentItemIndex() on most phones, there will be difference in some + * language variants where text reading/writing direction is different from + * left-to-right. + * @return A current position of highlight. + */ + IMPORT_C TInt CurrentDataIndex() const; + + /** + * Moves the cursor to the required grid data index. + * @param aDataIndex Data index value. + */ + IMPORT_C void SetCurrentDataIndex(TInt aDataIndex); + + /** + * The grid position function. Gives the data index by using grid's + * position. The position must be given from the top left corner. If + * the function returns -1 the item's position is invalid. + * @param aGridPosition The data item's co-ordinate values. + * @return Activated item's index value. + */ + IMPORT_C TInt IndexOfPosition(TPoint aGridPosition) const; + + /** + * The grid position function. Gives the data item's co-ordinate values + * by using item's index value. + * @param aItemIndex The data item's index value. + * @return @c TPoint co-ordinate values of active item. + */ + IMPORT_C TPoint PositionAtIndex(TInt aItemIndex) const; + + /** + * Item drawer. Gets the pointer to the grid class. + * @return A pointer to @c CFormattedCellListBoxItemDrawer object. + */ + IMPORT_C CFormattedCellListBoxItemDrawer* ItemDrawer() const; + + /** + * Function sets a grid text to the data item. If a leave occurs the + * framework generates a Symbian Leave code. + * @since Series S60 3.0 + * @param aText Descriptor parameter. + */ + IMPORT_C void SetEmptyGridTextL(const TDesC& aText); + + /** + * This function sets the empty grid text. + * @return A pointer to the grid text descriptor. + */ + inline const TDesC* EmptyGridText() const; + +public: + + /** + * This function creates a new object and returns pointer to it. If the + * leave occurs the framework generates a Symbian Leave code. + * @return A pointer to @c CListBoxView class. + */ + IMPORT_C virtual CListBoxView* MakeViewClassInstanceL(); + + /** + * This function sets the column width of the grid. Column width cannot be + * set in a horizontal grid since the number of columns in the grid is + * defined by the initialising call to @c SetLayoutL. The column width + * cannot be larger than the width of the viewing rectangle. + * @param aColumnWidth A parameter defines a width of the column. + */ + IMPORT_C void SetColumnWidth(TInt aColumnWidth); + + /** + * This function gives a width of the column. + * @return A width of the column. + */ + IMPORT_C TInt ColumnWidth() const; + +public: //from CEikListBox + + /** + * This function updates the scrollbars, including item position. This + * function is called when the size of the scrollbars or data changes. If + * the leave occurs the framework generates a Symbian Leave code. + */ + IMPORT_C virtual void UpdateScrollBarsL(); + + /** + * This function should be called after one or more items have been added to + * the grid. If a leave occurs the framework generates a Symbian Leave + * code. + */ + IMPORT_C void HandleItemAdditionL(); + + /** + * This function should be called after one or more items have been removed + * from the grid. If a leave occurs the framework generates a Symbian + * Leave code. + */ + IMPORT_C void HandleItemRemovalL(); + + /** + * This function is from @c CEikAppUi, handles key events. If a leave + * occurs the framework generates a Symbian Leave code. + * @param aKeyEvent Event to handled. + * @param aType of the key event. + * @return Response code ( @c EKeyWasConsumed, @c EKeyWasNotConsumed ) + */ + IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType); + + /** + * This function sets the row height of the grid. Row height cannot be set + * in a vertical grid since the number of rows in the grid is defined by + * the initialising call to @c SetLayoutL. The row height cannot be larger + * than the height of the viewing rectangle. If a leave occurs the + * framework generates a Symbian Leave code. + * @param aHeight The height of the item's rows. + */ + IMPORT_C void SetItemHeightL(TInt aHeight); + + /** + * This function handles size changes. This routine assumes that + * @c SetLayoutL has been called to set up the grid. + */ + IMPORT_C void SizeChanged(); + + /** + * This function creates a new object and returns pointer to + * @c CTextListBoxModel class. + * @return A pointer to @c CTextListBoxModel object. + */ + IMPORT_C CTextListBoxModel* Model() const; + + /** + * This function handles viewable rectangle. + * @param aRect Rectangle parameter. + */ + IMPORT_C void SetRect(const TRect& aRect); + + /** + * This function is called when the grid's items, item's data and scroll + * bars has been changed. This implementation ensures that the current + * item is visible after resize. If a leave occurs the framework generates + * a Symbian Leave code. + */ + IMPORT_C virtual void HandleViewRectSizeChangeL(); + + /** + * This function sets top item index. + * @param aItemIndex Item index value. + */ + IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const; + + /** + * This function handles resource changes. + * @since Series S60 2.6. + * @param aType Message type. + */ + IMPORT_C virtual void HandleResourceChange(TInt aType); + + /** + * Indicates whether the control should be redrawn now. If @c ENoDrawNow, + * the function has no immediately effect. EDrawNow redraw control + * immediately. + * @since Series S60 3.0. + */ + IMPORT_C void FocusChanged(TDrawNow aDrawNow); + +public: // From CCoeControl + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent); + +protected: // from CEikListBox + + /** + * This function scroll horizontal by one column when the left/right scroll + * arrows (i.e. the nudge buttons) are tapped. + * @return A nudge value when the buttons are pressed. + */ + IMPORT_C virtual TInt HorizontalNudgeValue() const; + + /** + * This function gets the granularity for horizontal scrolls. The + * granularity is the minimum size of a horizontal move of the client area. + * @return A grain size for horizontal scrolling in pixels. + */ + IMPORT_C virtual TInt HorizScrollGranularityInPixels() const; + + /** + * This function called by various functions of this class to ensure that + * the top item index is always a sane value. The implementation in + * @c CEikListBox tries to ensure the minimum amount of white space at the + * bottom of the list box. Note that this function does not affect the + * current item index. + */ + IMPORT_C virtual void AdjustTopItemIndex() const; + + /** + * This function handles drag events. If a leave occurs the framework + * generates a Symbian Leave code. + * @param aPointerPos The position of the @c TPointerEvent for which this + * handler is invoked. + */ + IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos); + + /** + * This function calculates the client area. This method is called by + * various functions of this class to recalculate the extent of the client + * area from @c iViewRect. This implementation takes into account any + * rounding of the viewing rectangle made to fit a whole number of items. + * @param aClientRect On return contains a size for the client area in + * pixels. + */ + IMPORT_C virtual void RestoreClientRectFromViewRect(TRect& aClientRect) const; + + /** + * This function rounds down the height of the rectangle (if necessary) so + * that only a whole number of items can be displayed inside the list box. + * @param aRect Rectangle parameter. + */ + IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(TRect& aRect) const; + + /** + * Updates the position of grids scroll bars’ thumbs to reflect the vertical + * position of selector. + */ + IMPORT_C virtual void UpdateScrollBarThumbs() const; + + /** + * Gets a count of the component controls of this grid. + * @return The number of component controls. + */ + IMPORT_C virtual TInt CountComponentControls() const; + +protected: + + /** + * Moves to the next or previous item on the grid. If a leave occurs the + * framework generates a Symbian Leave code. + * @param aPoint Co-ordinate object parameter. + */ + IMPORT_C void MoveToNextOrPreviousItemL(TPoint aPoint); + + /** + * This protected function used by functions to check/alter the dimensions + * of the grid as data items are added or removed or the size of the items + * are altered. It also assumes that @c SetLayoutL has been called. + * This will not leave if scrollbars have both been turned off. If a leave + * occurs the framework generates a Symbian Leave code. + */ + IMPORT_C virtual void CalcGridSizeL(); + + /** + * Creates a formatted list item drawer. If a leave occurs the framework + * generates a Symbian Leave code. + */ + IMPORT_C virtual void CreateItemDrawerL(); + +private: + __DECLARE_TEST; + + // grid model helper + inline CAknGridM* GridModel() const; + + // grid view helper + inline CAknGridView* GridView() const; + + /** + * This function sets the size and initial layout of items. If a leave + * occurs the framework generates a Symbian Leave code. + * @param aOrientation + * @param aHorizontal + * @param aVertical + * @param aNumOfItemsInPrimaryOrient + * @param aNumOfItemsInSecondaryOrient + * @param aSizeOfItems + * @param aWidthOfSpaceBetweenItems + * @param aHeightOfSpaceBetweenItems + */ + void DoSetLayoutL(TInt aOrientation, + TInt aHorizontal, + TInt aVertical, + TInt aNumOfItemsInPrimaryOrient, + TInt aNumOfItemsInSecondaryOrient, + TSize aSizeOfItems, + TInt aWidthOfSpaceBetweenItems=0, + TInt aHeightOfSpaceBetweenItems=0); + +private: + /** + * From CAknControl + */ + IMPORT_C void* ExtensionInterface( TUid aInterface ); +private: // from MListBoxModel + IMPORT_C virtual TAny* MListBoxModel_Reserved(); + +protected: + /** + * From @c MEikScrollBarObserver + * + * This function handles scroll events caused by scroll bar. + * It updates grid's view by event and new thumb position. + * + * @param aScrollBar pointer to scroll bar sent this event + * @param aEventType type of event + */ + IMPORT_C virtual void HandleScrollEventL(CEikScrollBar* aScrollBar, TEikScrollEvent aEventType); + + /** + * From @c MObjectProvider. + * + * Retrieves an object of the same type as that encapsulated in aId. This + * function is used to allow controls to ask their owners for access to + * other objects that they own. + * + * @param aId An encapsulated object type ID. + * @return Encapsulates the pointer to the object provided. + * Note that the encapsulated pointer may be NULL. + */ + IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId); + + +private: + TInt iMinColWidth; + TBool iCurrentIsValid; + TInt iNumOfColsInView; + TInt iNumOfRowsInView; + TSize iSpaceBetweenItems; + TInt iSpare; // was iNumOfItemsInPrimaryOrient; + TBitFlags iOrientationFlags; + TBitFlags iHorizontalFlags; + TBitFlags iVerticalFlags; + CAknGridExtension *iExtension; // spare taken to use as extension class + }; + +/** + * Return Model + */ +inline CAknGridM* CAknGrid::GridModel() const + { + return STATIC_CAST(CAknGridM*,iModel); + } + +/** + * Return View + */ +inline CAknGridView* CAknGrid::GridView() const + { + return STATIC_CAST(CAknGridView*,iView); + } + +/** + * Return text currently in the empty grid text + */ +inline const TDesC* CAknGrid::EmptyGridText() const + { + return STATIC_CAST(CAknGridView*,iView)->EmptyListText(); + } + +#endif //__AKNGRID_H__ +