/*

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

*

*/

//

// EIKFRLBD.H

//

// Copyright (c) 2001 Symbian Ltd.  All rights reserved.

//

#if !defined(__EIKFRLBD_H__)

#define __EIKFRLBD_H__

#include <e32base.h>

#include <gdi.h>

#include <eiklbd.h>

#include <eikfrlb.h>

#include <avkon.hrh>

#include <AknsDrawUtils.h> // for TAknsQsnTextColorsIndex

#include <babitflags.h>    // for TBitFlags32

class CWindowGc;

class CGulIcon;

class CFormattedCellListBoxDataExtension;

class MAknsControlContext;

class TAknsItemID;

class CAknLayoutData;

class CAknsEffectAnim;

class TAknTextLineLayout;

class TAknWindowLineLayout;

class TAknTextComponentLayout;

class TAknWindowComponentLayout;

/**

* A callback interface for overriding highlight animation input layer

* preparation in derived classes. Usually drawing the background under the

* highlight rect will yield the right kind of result. The size of the render

* target is equal to item cell size.

*

* @since 3.0

*/

class MListBoxAnimBackgroundDrawer

    {

    public:

    /**

     * @param aGc Bitmapped graphical context to draw to.

     * @return 

     */ 

        virtual TBool DrawHighlightAnimBackground( CFbsBitGc& aGc ) const = 0;

    };

/**

 * @c CFormattedCellListBoxData can draw list items.

 * This is similar class than @c CColumnListBoxData, but it can more freely

 * layout the list items; more parameters can be used to position the elements.

 * In particular, the position of the elements is free, and not tied to fixed

 * width columns.

 *

 * This class is used to draw most of the S60 list and grid layouts.

 *

 * It also handles truncation of the text elements, centering and cropping of

 * images, z-order/overlapping cells, bi-directional text drawing, backgrounds

 * for lists, highlight drawing, various text and image properties and finally

 * the parts of the separator lines that are inside list items.

 *

 * This is a very low level class. The less you use this class, the better.

 * Applications should be using @c CAknSelectionListDialog or

 * @c CAknMarkableListDialog or @c CAknListQueryDialog to use lists. There are

 * enough predefined list layouts available, so there should be no need for

 * applications to use this class. See Style Guide for more information. Use of

 * this class may cause your application to not look ok when properties of the

 * device change.

 *

 * @lib avkon

 */

class CFormattedCellListBoxData : public CListBoxData

    {

    friend class CFormattedCellListBoxDataExtension;

public:

    //INNER CLASS DECLARATION

    /*

     * A container class for storage of colour values.                           

     * Used by @c CFormattedCellListBoxData.

     */

    class TColors

        {

    public:

        /**

         * C++ default constructor.

         */

        IMPORT_C TColors();

    public:

        /** 

         * The text colour.

         */

        TRgb iText;

        /** 

         * The background colour.

         */

        TRgb iBack;

        /** 

         * The highlighted text colour.

         */

        TRgb iHighlightedText;

        /** 

         * The highlighted background colour.

         */

        TRgb iHighlightedBack;

        /** 

         * The separator line colour.

         *

         * @deprecated The separator line colour is no longer used because the

         *             separator lines are skinned.

         */

        TRgb iRightSeparatorColor;

        };

public:

    /**

     * Two-phased constructor.

     *

     * @return Pointer to a new formatted cell listbox data object.

     */

    IMPORT_C static CFormattedCellListBoxData* NewL();

    /**

     * Destructor.

     */

    IMPORT_C ~CFormattedCellListBoxData();

public:

    /**

     * Gets colours attached to the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return Text and background colors.

     */

    IMPORT_C const TColors& SubCellColors(TInt aSubCellIndex) const;

    /**

     * Sets colours attached to the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aColors Text and background colors.

     */

    IMPORT_C void SetSubCellColorsL(TInt aSubCellIndex, const TColors &aColors);

    /**

     * Gets baseline position from top of the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return Baseline y-position.

     */

    IMPORT_C TInt SubCellBaselinePos(TInt aSubCellIndex) const;

    /**

     * Sets baseline position from top of the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aPos Position which is set for the item.

     */

    IMPORT_C void SetSubCellBaselinePosL(TInt aSubCellIndex, TInt aPos);

    /**

     * Gets cell size in pixels.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return Cell size.

     */

    IMPORT_C TSize SubCellSize(TInt aSubCellIndex) const;

    /**

     * Sets cell size in pixels.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aSize Cell size.

     */

    IMPORT_C void SetSubCellSizeL(TInt aSubCellIndex, TSize aSize);

    /**

     * Gets cell position inside an item.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return Cell position.

     */

    IMPORT_C TPoint SubCellPosition(TInt aSubCellIndex) const;

    /**

     * Sets cell position inside an item.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aPosition New position for cell.

     */

    IMPORT_C void SetSubCellPositionL(TInt aSubCellIndex, TPoint aPosition);

    /**

     * Determines whether this cell can overlap with one of the previous cells.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return @c ETrue if cell overlaps another one, @c EFalse if cell allocates 

     *         area from other cells.

     */

    IMPORT_C TBool SubCellIsTransparent(TInt aSubCellIndex) const;

    /**

     * Modifies whether the cell can overlap with one of the previous cells.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aIsTransparent @c ETrue if transparent, @c EFalse if not.

     */

    IMPORT_C void SetTransparentSubCellL(TInt aSubCellIndex, 

                                         TBool aIsTransparent);

    /**

     * Checks whether drawing algorithm always draws the cell or whether empty 

     * string in list item can disable the drawing of the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return @c ETrue when empty string disables cell, 

     *         @c EFalse if always drawn.

     */

    IMPORT_C TBool SubCellIsNotAlwaysDrawn(TInt aSubCellIndex) const;

    /**

     * Sets whether drawing algorithm always draws the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aIsNotAlwaysDrawn If @c ETrue, empty string disables cell.

     */

    IMPORT_C void SetNotAlwaysDrawnSubCellL(TInt aSubCellIndex,

                                            TBool aIsNotAlwaysDrawn);

    /**

     * Gets margins used for the content inside the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return Margins in pixels.

     */

    IMPORT_C TMargins SubCellMargins(TInt aSubCellIndex) const;

    /**

     * Sets margins for the content inside the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aMargins Margins for the content inside the cell.

     */

    IMPORT_C void SetSubCellMarginsL(TInt aSubCellIndex, TMargins aMargins);

    /**

     * Gets font attached to the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return Handle to the attached font.

     */

    IMPORT_C const CFont* SubCellFont(TInt aSubCellIndex) const;

    /**

     * Sets the font attached to the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aFont Font to attach to the cell.

     */

    IMPORT_C void SetSubCellFontL(TInt aSubCellIndex, const CFont* aFont);

    /**

     * Gets the alignment attached to the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return Alignment of the text.

     */

    IMPORT_C CGraphicsContext::TTextAlign SubCellAlignment(TInt aSubCellIndex)

        const;

    /**

     * Sets the alignment attached to the cell.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aAlign Alignment that is attached to the cell

     */

    IMPORT_C void SetSubCellAlignmentL(TInt aSubCellIndex,

                                       CGraphicsContext::TTextAlign aAlign);

    /**

     * Checks whetherdrawing algorithm considers the text

     * string in list item as unicode text string displayable on the screen,

     * or as string representation of an index to icon array.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return @c ETrue if graphics cell, @c EFalse if text cell.

     */

    IMPORT_C TBool SubCellIsGraphics(TInt aSubCellIndex) const;

    /**

     * Sets whether drawing algorithm considers the text string in list item as

     * unicode text string displayable on the screen, or as string 

     * representation of an index to icon array.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aIsGraphics @c ETrue if graphics cell, @c EFalse if text cell.

     */

    IMPORT_C void SetGraphicsSubCellL(TInt aSubCellIndex, TBool aIsGraphics);

    /**

     * Checks whether vertical line is drawn to the right side of the cell.

     *

     * @param aColumn Index number of the subcell.

     * @return Style of pen used to draw a line for the right side of the cell.

     */

    IMPORT_C CGraphicsContext::TPenStyle 

        SubCellRightSeparatorStyle(TInt aColumn) const;

    /**

     * Sets whether vertical line is drawn to the right side of the cell.

     *

     * @param aSubCell Index number of the subcell.

     * @param aStyle Style of a pen used to draw a line for the right side of 

     *        the cell.

     */

    IMPORT_C void SetSubCellRightSeparatorStyleL(TInt aSubCell,

                                            CGraphicsContext::TPenStyle aStyle);

    /**

     * Gets the amount of pixels text margins is grown if it is truncated. 

     * This is usually very small number used to make the layout look more 

     * balanced when text is truncated. (the glyph used for truncation is 

     * almost empty and on narrow text elements, it looks odd if the truncated

     * text element is exactly same size as non-truncated version.)

     *

     * @param aSubCellIndex Index number of the subcell.

     * @return Amount of pixels that are used for growing the text margins in 

     *         truncation.

     */

    IMPORT_C TInt SubCellTextClipGap(TInt aSubCellIndex) const;

    /**

     * Sets the amount of pixels truncation grows a text element.

     *

     * @param aSubCellIndex Index number of the subcell.

     * @param aGap The amount of pixels that are required for growing the text 

     *        element when it is truncated. 

     */

    IMPORT_C void SetSubCellTextClipGapL(TInt aSubCellIndex, TInt aGap);

    /**

     * SkinEnabled checks whether skins are enabled on this list.

     *

     * @since Symbian 2.0 

     * @return @c ETrue if enabled, @c EFalse if disabled.

     */

    IMPORT_C TBool SkinEnabled() const;

    /**

     * Sets whether skins are enabled on this list.

     * The default value is determined from global setting from @c CAknAppUi.

     *

     * @since Symbian 2.0

     * @param aEnabled If @c ETrue skins are set enabled. 

     *        If @c EFalse skins are set disabled.

     */

    IMPORT_C void SetSkinEnabledL(TBool aEnabled);

    /**

     * Checks whether the cell is used for numbers.

     *

     * @since Symbian 2.0

     * @param aSubCellIndex Index number of the subcell.

     * @return @c ETrue if enabled, @c EFalse if disabled.

     */

    IMPORT_C TBool SubCellIsNumberCell(TInt aSubCellIndex) const;

    /**

     * Sets whether the cell is used for numbers.

     *

     * @since Symbian 2.0

     * @param aSubCellIndex Index number of the subcell.

     * @param aIsNumberCell New value for the flag.

     */

    IMPORT_C void SetNumberCellL(TInt aSubCellIndex, TBool aIsNumberCell);

    /**

     * Gets the icon array used when drawing bitmaps for the listbox items.

     */

    IMPORT_C CArrayPtr<CGulIcon>* IconArray() const;

    /**

     * Sets the icon array used when drawing bitmaps.

     * The array can be modified (no need to call this method when modifying),

     * even in @c MdcaPoint() or @c MdcaCount() methods of @c MDesCArray class.

     * See also @c CTextListBoxModel::SetItemTextArray().

     * 

     * The most common way to crash a listbox is by forgetting to call this 

     * method, or the list item string for graphics cell is not an index of 

     * a bitmap.

     *

     * @param aArray Pointer to the icon array.

     */

    IMPORT_C void SetIconArrayL(CArrayPtr<CGulIcon>* aArray);

    /**

     * SetIconArray sets the icon array used when drawing bitmaps.

     * The array can be modified (no need to call this method when modifying),

     * even in @c MdcaPoint() or @c MdcaCount() methods of @c MDesCArray class.

     * See also @c CTextListBoxModel::SetItemTextArray().

     * 

     * The most common way to crash a listbox is by forgetting to call this

     * method, or the list item string for graphics cell is not an index of

     * a bitmap.

     *

     * @param aArray Pointer to the icon array.

     */

    IMPORT_C void SetIconArray(CArrayPtr<CGulIcon>* aArray);

    /**

     * Font access to the font used in subcell.

     *

     * @param aItemProperties Not used in code.

     * @param aSubCellIndex Index number of the subcell.

     * @return Font used in subcell.

     */

    IMPORT_C CFont* Font(const TListItemProperties& aItemProperties,

                         TInt aSubCellIndex) const;

    /**

     * From @c CListBoxData.

     *

     * @c Draw() is the most important method in 

     * @c CEikFormattedCellListBoxData.

     * This is the only method that needs to be implemented in this class and

     * it draws the whole list item.

     *

     * @param aProperties Properties attached to the list item.

     * @param aGc Graphics Context used for drawing the list item.

     * @param aText A text string describing the list item cells.

     * @param aRect The area of the screen for the whole list item.

     * @param aHighlight Whether the list item is selected.

     * @param aColors The colours used for drawing the item.

     */

    IMPORT_C virtual void Draw(TListItemProperties aProperties,

                               CWindowGc& aGc,

                               const TDesC* aText,

                               const TRect& aRect,

                               TBool aHighlight,

                               const TColors& aColors) const;

    /**

     * Indicates if sub cell is using its own colors rather than common colors.

     *

     * @param aSubCell Index number of the subcell.

     * @return Boolean indicating whether own colors enabled.

     *         @c ETrue enabled, @c EFalse disabled.

     */

    IMPORT_C TBool UseSubCellColors(TInt aSubCell) const;

    /**

     * Ability for a skin subsystem to access Mop chain through current 

     * listbox control.

     *

     * @since Symbian 2.0

     * @return Current listbox instance or NULL.

     */

    IMPORT_C CCoeControl* Control() const;

    /**

     * Ability for a skin subsystem to access mop chain through current listbox

     * control.

     *

     * @since Symbian 2.0

     * @param aControlOrNull Current listbox instance or NULL. Cannot be other

     *        control than the current listbox!

     */

    IMPORT_C void SetControl(CCoeControl* aControlOrNull);

    /**

     * Access to the background context of the listbox.

     *

     * @since Symbian 2.0

     * @return Skin background context.

     */

    IMPORT_C MAknsControlContext* SkinBackgroundContext() const;

    /**

     * Modify properties of the skin context (background).

     *

     * @since Symbian 2.0

     * @param aId Skin background identifier.

     * @param aRect Skin background rectangle.

     */

    IMPORT_C void SetBackgroundSkinStyle(const TAknsItemID *aId,

                                         const TRect &aRect);

    /**

     * Modify properties of the skin context (AB-column).

     *

     * @since Symbian 2.0

     * @param aId Skin background identifier.

     * @param aTileRect Skin background area from LAF.

     */

    IMPORT_C void SetSkinStyle(const TAknsItemID* aId, const TRect& aTileRect);

    /**

     * Modify position of the parent for list default context.

     *

     * @since Symbian 2.0