/*
* 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 "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.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__