/*
* Copyright (c) 2002 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: 
*
*/

// EIKFRLB.H
//
// Copyright (c) 1997-2001 Symbian Ltd.  All rights reserved.
//
#if !defined(__EIKFRLB_H__)
#define __EIKFRLB_H__

#include <eiklbi.h>
#include <eiklbv.h>
#include <eiktxlbm.h>
#include <eiktxlbx.h>

class CFormattedCellListBoxData;

/**
 *  @c CFormattedCellListBoxItemDrawer draws a single list item and manages
 *  list item properties.
 *
 *  @lib avkon
 */
class CFormattedCellListBoxItemDrawer : public CTextListItemDrawer
	{
public:

    /**
     * C++ default constructor.
     * 
     * @param aTextListBoxModel The list box model class.
     * @param aFont Font to be used in listbox.
     * @param aFormattedCellData Pointer to the list layout drawer class.
     */
	IMPORT_C CFormattedCellListBoxItemDrawer(
            MTextListBoxModel* aTextListBoxModel, 
            const CFont* aFont, 
            CFormattedCellListBoxData* aFormattedCellData);
	
    /**
     * Destructor.
     */
    IMPORT_C ~CFormattedCellListBoxItemDrawer();

    /**
     * Gets the list layout drawer.
     * 
     * @return Pointer to the list layout drawer object.
     */
	IMPORT_C CFormattedCellListBoxData* FormattedCellData() const;

    /**
     * Gets the list layout drawer.
     * 
     * @return Pointer to the list layout drawer object.
     */
	IMPORT_C CFormattedCellListBoxData* ColumnData() const; 
    // for compability with columnlistbox itemdrawer

    /**
     * Draws an empty item to the list box.
     * 
     * @param aItemIndex Not used.
     * @param aItemRectPos Position for the list box item rectangle.
     * @param aViewIsDimmed Not used.
     */
    IMPORT_C virtual void DrawEmptyItem(TInt aItemIndex, TPoint aItemRectPos, 
                                        TBool aViewIsDimmed) const;

    /**
     * This function sets top item index.
     * 
     * @param aTop Item index value.
     */
	IMPORT_C void SetTopItemIndex(TInt aTop);

    /**
     * List item index and color and style properties.
     */
	struct SListProperties 
	    {
        /** List box item index. */
        TInt iItem; // must be first

        /** Colour and style properties for the list item. */
        TListItemProperties iProperties;
	    };

    /**
     * Clears all properties.
     */
	IMPORT_C void ClearAllPropertiesL();

    /** 
     * The SetProperties is convenience method for normal cases.
     * NOTE that it does NOT work correctly if you can insert/delete
     * items from the list -- You need to update all properties if
     * any changes to the item text array happen! Often it is convenient
     * to override the @c Properties() method. Further, use this only
     * for small lists.
     *
     * It has been implemented as sorted list of (index,Property) pairs.
     * 
     * If you're using find, aItemIndex for this method is the same as you give
     * in @c MdcaPoint() points the default @c Properties() does conversion 
     * between indexes.
     * 
     * @param aItemIndex List box item index.
     * @param properties Colour and style properties for the list box item.
     */
    IMPORT_C void SetPropertiesL(TInt aItemIndex, TListItemProperties properties);

    /**
     * Function for getting properties of a certain list box item.
     * 
     * @param aItemIndex The listbox item index.
     * @return Colour and style properties of wanted
     *         list box item.
     */
	IMPORT_C virtual TListItemProperties Properties(TInt aItemIndex) const;

    /**
     * Gets list box item cell size.
     * 
     * @return The list box item cell size.
     */
	TSize LafItemSize() { return iItemCellSize; }

public: // from CTextListItemDrawer

    /**
     * From @c CTextListItemDrawer.
     *
     * Draw an item in a list box.
     * 
     * @param aItemIndex The index into the model's item array of the item 
     *        to draw.
     * @param aItemTextRect The item’s text rectangle. 
     * @param aItemIsCurrent @c ETrue if the item is current. @c EFalse 
     *        otherwise.
     * @param aViewIsEmphasized @c ETrue if the view is emphasized. @c EFalse
     *        otherwise.
     * @param aItemIsSelected @c ETrue if the item is selected. @c EFalse 
     *        otherwise.
     */
	IMPORT_C void DrawItemText(TInt aItemIndex,const  TRect& aItemTextRect,
                               TBool aItemIsCurrent, TBool aViewIsEmphasized, 
                               TBool aItemIsSelected) const;

    /**
     * From @c CTextListItemDrawer.
     *
     * Draws an item tick mark. 
     *
     * A tick mark is used in multiple selection lists to indicate the item is
     * selected.
     *
     * This function is invoked by the framework to draw an item mark if 
     * @c iDrawMark is set. The mark should be drawn into this list item 
     * drawer's graphics context; by default, @c DrawItemMark() draws a tick 
     * using the standard symbol font.
     * 
     * This function does not need to be re-implemented for derived classes 
     * which do not draw item marks.
     * 
     * @param aItemIsSelected Whether the item to draw for is selected.
     * @param aViewIsDimmed Whether the item is dimmed. 
     * @param aMarkPos Position of the mark.
     */
	IMPORT_C void DrawItemMark(TBool aItemIsSelected, TBool aViewIsDimmed, 
                               const TPoint& aMarkPos) const;

public: // from CListItemDrawer

    /**
     * From @c CListItemDrawer.
     *
     * Gets the minimum size of a cell based on the font and the number of 
     * characters in the cell.
     * 
     * @return The minimum size for a cell in pixels.
     */
	IMPORT_C TSize MinimumCellSize() const;

    /**
     * From @c CListItemDrawer.
     *
     * Gets the width in pixels of the specified item.
     * 
     * @param aItemIndex The index of the item for which the width is obtained.
     * @return The specified item's width in pixels.
     */
	IMPORT_C TInt ItemWidthInPixels(TInt aItemIndex) const; 

    /**
     * From @c CListItemDrawer.
     *
     * Sets the item cell size.
     *
     * The cell size is the on-screen size of the entire item, including its 
     * text and its item mark.
     * 
     * @param aSizeInPixels New size for the item cell.
     */
    IMPORT_C void SetItemCellSize(const TSize& aSizeInPixels);

protected:
    
    /**
     * Draws current item rectangle.
     * 
     * @param aRect Current item rectangle.
     */
	void DrawCurrentItemRect(const TRect& aRect) const;

    /**
     * @c WordWrapListItem is used with @c CAknDouble* style listboxes.
     * If listbox does not have 2nd line defined, @c WordWrapListItem
     * wraps 1st line to 2nd line, if text does not fit to 1st line.
     * If listbox does have 2nd line defined, this method truncates
     * both lines.
     *
     * @internal
     * @param aTarget Where to place wrapped item string
     * @param aItemString Text to be wrapped
     * @param aFirstIndex index of 1st subcell to wrap
     * @param aSecondIndex index of 2nd subcell
     */
    void WordWrapListItem( TPtr& aTarget, 
                           const TDesC &aItemString, 
                           TInt aFirstIndex, 
                           TInt aSecondIndex,
                           TInt aItemIndex ) const;
    /**
    * @internal
    */
    void DrawBackgroundAndSeparatorLines( const TRect& aItemTextRect ) const;
                        

private:

	IMPORT_C void CFormattedCellListBoxItemDrawer_Reserved();

protected:

    /**
     * Top item index.
     */
	TInt iTopItemIndex;

    /**
     * Array for list box item's properties.
     * Own.
     */
	CArrayFix<SListProperties>* iPropertyArray;

private:

	TInt iSpare;
	};


/** 
 * Avkon base class similar to uikon's column listbox.
 *
 * @code
 *  ListBox <>--> View ---> ItemDrawer ---> Model
 *  ListBox <>--> ItemDrawer <>---> Data
 *  ListBox <>--> Model <>---> MDesCArray <--- Array <>---> Engine
 * @endcode
 * 
 * Content for list items are tab-separated strings.
 *
 * See concrete classes derived from @c CEikFormattedCellListBox for details.
 *
 * Starting from 3.0 listbox uses highlight animations. Starting and stopping
 * animation is connected to focus events. To support highlight animations
 * properly you have to make sure that the list has focus when it has 'visual
 * focus'. Common issues:
 * - In many cases list is in a container which sits on top of the control
 *   stack. The container receives all focus events and should hand them to the
 *   list too. E.g. 
 * @code       void CContainer::FocusChanged( TDrawNow aDrawNow )
 *                 {
 *                 ... some code ...
 *                 if( iListBox )
 *                     iListBox->SetFocus( IsFocused(), aDrawNow );
 *                 }
 * @endcode
 * - When switching components programmatically, e.g. from one list to another
 *   in the same view, make sure that you remove focus from the other
 *   component.
 * - In more complex cases you may have to add a dummy interceptor control to
 *   the top of control stack to hand focus events to list.
 * - Make sure you handle resource changes correctly. If resource handle chain
 *   is solid it should reach @c CCoeControl::HandleResourceChange, which 
 *   informs child components about resource change.
 *
 * See methods
 *   @c CEikListBox::ConstructL()
 *   @c CEikTextListBox::SetItemTextArray()
 *   @c CEikFormattedCellListBoxData::SetIconArray()
 * 
 * Related flags for dialogs (@c avkon.hrh)
 *   @c EAknDialogSelectionList
 *   @c EAknDialogMenuList
 *   @c EAknDialogMultiselectionList
 *
 * Check also:
 *   @c CAknSelectionListDialog (@c aknselectionlist.h)
 *   @c CAknMarkableListDialog  (@c aknselectionlist.h)
 *   @c CAknPopupList           (@c aknpopup.h)
 *   @c CAknListQueryDialog     (@c aknquerydialog.h)
 *   @c CAknColumnListBox       (@c aknlists.h)
 *
 *  @lib avkon
 */
class CEikFormattedCellListBox : public CEikTextListBox 
	{

public:

    /**
     * C++ default constructor.
     */
	IMPORT_C CEikFormattedCellListBox();

    /**
     * Constructs list box from resource file. See @c LISTBOX resource 
     * definition.
     *
     * Flags: 
     *    @c EAknListBoxSelectionList, 
     *    @c EAknListBoxMenuList, 
     *    @c EAknListBoxMarkableList, 
     *    @c EAknListBoxMultiselectionList, 
     *    @c EAknListBoxViewerFlags
     * 
     * @param aReader Reference to resource reader @c TResourceReader object.
     */
	IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);
	
    /** 
     * By default Symbian 2nd phase constructor is private. Must be called 
     * if resource data is not used.
     * 
     * @param aParent Pointer to @c CCoeControl class, parent control.
     * @param aFlags Flags for @c CEikListBox constructor. Possible flags : 
     *        @c EAknListBoxSelectionList, 
     *        @c EAknListBoxMenuList, 
     *        @c EAknListBoxMarkableList, 
     *        @c EAknListBoxMultiselectionList, 
     *        @c EAknListBoxViewerFlags
	 */
	IMPORT_C void ConstructL(const CCoeControl* aParent, TInt aFlags);

public:

    /**
     * Gets model class of the list box.
     * 
     * @return Pointer to list box model class instance.
     */
	IMPORT_C CTextListBoxModel* Model() const;

    /**
    * Gets list box item drawer.
    * 
    * @return Pointer to item drawer object.
    */
	IMPORT_C CFormattedCellListBoxItemDrawer* ItemDrawer() const;

    /**
    * Sets icon sizes for visible list box items.
    */
    void SetIconSizes();

public:

	/**
     * Enable or disable logical to visual reordering in listbox data text
     * drawing. By default, it is enabled. This has any effect only when 
     * bidirectional text is rendered.
     *
     * If you convert text to visual order prior to passing it to the listbox
     * (for example by wrapping text to lines with methods in 
     * @c AknBidiTextUtils), then you should disable conversion in listbox 
     * by calling this method.
     *
     * @since S60 2.0
     * @param aUseConversion If @c ETrue enable conversion. 
     */
	IMPORT_C void UseLogicalToVisualConversion( TBool aUseConversion );

public:

    /**
     * This method needs to be called to enable extended drawing features such
     * as skinning, pictograph drawing and marquee text in the listbox draw
     * routine.
     *
     * Methods @c CEikFormattedCellListBox::ConstructL and
     * @c CEikFormattedCellListBox::ConstructFromResourceL call this method. 
     * So, you only need to call this if your listbox implementation does not 
     * call either of those.
     * 
     * This method can be safely called more than once.
     * Item drawer must be created before calling this method, or a panic is 
     * raised.
     *
     * @since S60 2.6
     * @panic EAknPanicListBoxItemDrawerNotCreated Panics if the item drawer 
     *        for the current class has not been defined.
     */
    IMPORT_C void EnableExtendedDrawingL();
    
    /**
    * Enables/disables list stretching. When a list is stretched its second line
    * is moved after the first line. This is intented for devices with a large
    * screen. This feature might be set as default by a product specific flag.
    *
    * Item drawer must be created before calling this method.
    *
    * @since S60 3.1
    * @param aEnabled ETrue to enable list stretching.
    */
    IMPORT_C void EnableStretching( const TBool aEnabled );

    /**
    * Hides the second row of a double style listbox. This feature is disabled
    * by default.
    *
    * @since S60 3.1
    * @param aHide ETrue to hide the second row.
    */
    IMPORT_C void HideSecondRow( const TBool aHide );
protected:

    /**
     * Creates item draver for the listbox.
     */
	IMPORT_C virtual void CreateItemDrawerL();

    /**
     * From @c CEikListBox.
     *
     * 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 The rectangle to be modified.
     * @return The number of pixels reduced.
     */
	IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(
                                    TRect &aRect) const;

public: // from CEikListBox

    /**
     * From @c CEikListBox.
     *
     * Creates the list box view.
     * 
     * @return Pointer to new list box view class instance.
     */
	IMPORT_C CListBoxView* MakeViewClassInstanceL();

    /**
     * From @c CEikListBox.
     *
     * Handles focus changes.
     *
     * The function emphasizes or de-emphasizes the view as needed, 
     * and shows or hides the matcher cursor.
     *
     * @param aDrawNow If @c EDrawNow, a redraw is performed immediately.
     */
    IMPORT_C void FocusChanged(TDrawNow aDrawNow);

public: // from CCoeControl

    /**
     * From @c CCoeControl.
     *
     * Gets the list of logical colors used to draw the control.
     * 
     * @param aColorUseList The color list.
     */
	IMPORT_C void GetColorUseListL(
        CArrayFix<TCoeColorUse>& aColorUseList) const;
	
    /**
     * From @c CCoeControl.
     *
     * Handles a change to the control's resources.
     *
     * @param aType A message UID value.
     */
    IMPORT_C void HandleResourceChange(TInt aType);
    
    /**
     * From @c CCoeControl.
     *
     * Handles pointer events.
     *
     * @param aPointerEvent The pointer event.
     */
    IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

protected: // from MObjectProvider

    /**
     * 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: 

    /**
     * From @c CAknControl
     */
	IMPORT_C void* ExtensionInterface( TUid aInterface );

private: // listbox use only

	IMPORT_C virtual void CEikListBox_Reserved(); 

private: // data

    TInt iSpare;
};


/**
 *  @c CFormattedCellListBoxView draws all the list items and manages
 *  the area of the screen allocated for list itself. In particular,
 *  this class does not handle margins of the whole list.
 *
 *  @lib avkon
 */
class CFormattedCellListBoxView : public CListBoxView
	{

public: // from CListBoxView

    /**
     * From @c CListBoxView.
     *
     * Draws every visible item into the specified rectangle. 
     *
     * @param aClipRect The rectangle to draw into. This is not used.
     */
	IMPORT_C void Draw(const TRect* aClipRect = NULL) const;

    /**
     * From @c CListBoxView.
     *
     * Draws empty list. 
     *
     * @param aClientRect The rectangle to draw into.
     */
	IMPORT_C virtual void DrawEmptyList(const TRect &aClientRect) const;
	
    /**
     * From @c CListBoxView.
     *
     * Recalculates the index of the bottom item in the list from the top item
     * index and the size of the display. This function is called by the owning
     * list box control when either the size of the list box or the number of 
     * items in its model changes. 
     */
    IMPORT_C virtual void CalcBottomItemIndex();

private: // overridden from CListBoxView

	IMPORT_C virtual TAny* Reserved_1();
	};


#endif  // __EIKFRLB_H__

// End of File
