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