--- 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 <eiktxlbx.h>
+#include <eiklbv.h>
+#include <eikfrlbd.h>
+#include <eikfrlb.h>
+
+#include <AknGridM.h>
+#include <AknGridView.h>
+#include <Aknappui.h>
+
+// 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__
+