/*
* 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:  Pictograph drawer interface.
*
*
*/


#ifndef AKN_PICTOGRAPH_DRAWER_INTERFACE_H
#define AKN_PICTOGRAPH_DRAWER_INTERFACE_H

// INCLUDES
#include <e32std.h>
#include <gdi.h>

// CONSTANTS

enum TAknPictographHeight
    {
    EHeight12 = 0,
    EHeight16 = 1,
    EHeight18 = 2,
    EHeight24 = 3,
    EHeight30 = 4
    };

enum TAknPictographDrawingMode
    {
    EDrawingModeNormal = 0,
    EDrawingModeWhite  = 1
    };

// FORWARD DECLARATIONS

class CBitmapContext;
class CFont;

// CLASS DECLARATION

class MAknPictographAnimatorCallBack
    {
    public:
        /**
        * This function is called when a redraw is needed for drawing
        * new frames of animated pictographs. It should
        *
        * 1) Draw or clear the background of pictographs
        * 2) If the pictographs are amongst text, draw the text
        * 3) Draw the pictographs using MAknPictographDrawer interface
        *
        * In many cases, it is sufficient to implement this simply by
        * calling CCoeControl::DrawNow for the appropriate control.
        */
        virtual void DrawPictographArea() = 0;
    };

/**
* Pictograph drawer interface
*
*  @lib N/A
*  @since 2.6
*/
NONSHARABLE_CLASS(MAknPictographDrawer) 
	{
    public:  // Constructors and destructor

        /**
        * Destructor.
        */
        inline virtual ~MAknPictographDrawer() {};

    public: // New functions

        /**
        * Returns a heap descriptor filled with all supported
        * pictograph codes.
        * They are sorted in ascending pictograph code order.
        * Ownership of the returned object is transferred to the caller.
        *
        * @since 2.6
        * @return Heap descriptor filled with all supported
        *         pictograph codes.
        */
        virtual HBufC* SupportedPictographCodesL() const = 0;

        /**
        * Tells whether the character is in the pictograph code range.
        *
        * @since 2.6
        * @param aCode Character code in Unicode.
        * @return ETrue if in pictograph code range, EFalse if not.
        */
        virtual TBool IsPictograph( TText aCode ) const = 0;

        /**
        * Tells whether the text contains any pictographs.
        *
        * @since 2.6
        * @param aText Text.
        * @return ETrue if the text contains any pictographs, EFalse if not.
        */
        virtual TBool ContainsPictographs( const TDesC& aText ) const = 0;

        /**
        * Draws pictograph bitmap in the given position.
        * This method sets aGc to use CGraphicsContext::ENullBrush.
        *
        * @since 2.6
        * @param aGc Graphics context.
        * @param aTopLeft Top left coordinates of the rendering position .
        * @param aCode Pictograph code in Unicode.
        * @param aHeight Pictograph height.
        */
	    virtual void DrawPictograph(
            CBitmapContext& aGc,
            const TPoint& aTopLeft,
            TText aCode,
            TAknPictographHeight aHeight ) const = 0;

        /**
        * Draws pictograph bitmap centered in the given rect.
        * This method sets aGc to use CGraphicsContext::ENullBrush.
        *
        * @since 2.6
        * @param aGc Graphics context.
        * @param aRect Rectangle, where the pictograph is centered in.
        * @param aCode Pictograph code in Unicode.
        * @param aHeight Pictograph height.
        */
	    virtual void DrawPictograph(
            CBitmapContext& aGc,
            const TRect& aRect,
            TText aCode,
            TAknPictographHeight aHeight ) const = 0;

        /**
        * Draws pictograph bitmap centered in the given rect,
        * clipped with clipping rect.
        * This method sets aGc to use CGraphicsContext::ENullBrush.
        *
        * @since 2.6
        * @param aGc Graphics context.
        * @param aRect Rectangle, where the pictograph is centered in.
        * @param aClipRect Clipping rectangle.
        * @param aCode Pictograph code in Unicode.
        * @param aHeight Pictograph height.
        */
	    virtual void DrawPictograph(
            CBitmapContext& aGc,
            const TRect& aRect,
            const TRect& aClipRect,
            TText aCode,
            TAknPictographHeight aHeight ) const = 0;

        /**
        * Draws text using CGraphicsContext::DrawText and then
        * draws pictographs on top of that.
        *
        * Suitable pictograph height is chosen based on aFont.
        *
        * The graphics context aGc must be set to use font aFont
        * before calling this method.
        *
        * This method sets aGc to use CGraphicsContext::ENullBrush.
        *
        * @since 2.6
        * @param aGc Graphics context.
        * @param aFont Used font.
        * @param aText Text.
        * @param aPosition Text baseline coordinates of the starting position.
        */
        virtual void DrawText(
            CBitmapContext& aGc,
            const CFont& aFont,
            const TDesC& aText,
            const TPoint& aPosition ) const = 0;

        /**
        * Draws text using CGraphicsContext::DrawText and then
        * draws pictographs on top of that.
        *
        * Suitable pictograph height is chosen based on aFont.
        *
        * The graphics context aGc must be set to use font aFont
        * before calling this method.
        *
        * This method sets aGc to use CGraphicsContext::ENullBrush.
        *
        * @since 2.6
        * @param aGc Graphics context.
        * @param aFont Used font.
        * @param aText Text.
        * @param aBox Rectangle, where the text is rendered.
        * @param aBaselineOffset Offset from the top of the rectangle to
        *   the baseline to the text.
        * @param aAlignment Text alignment.
        * @param aLeftMargin The left margin for left-aligned text, or the right
        *   margin for right-aligned text
        */
        virtual void DrawText(
            CBitmapContext& aGc,
            const CFont& aFont,
            const TDesC& aText,
            const TRect& aBox,
            TInt aBaselineOffset,
            CGraphicsContext::TTextAlign aAlignment =
                CGraphicsContext::ELeft,
            TInt aLeftMargin = 0 ) const = 0;

        /**
        * Draws pictographs that are encountered in the text.
        * Suitable pictograph height is chosen based on aFont.
        * This method sets aGc to use CGraphicsContext::ENullBrush.
        *
        * @since 2.6
        * @param aGc Graphics context.
        * @param aFont Used font.
        * @param aText Text.
        * @param aPosition Text baseline coordinates of the starting position.
        */
        virtual void DrawPictographsInText(
            CBitmapContext& aGc,
            const CFont& aFont,
            const TDesC& aText,
            const TPoint& aPosition ) const = 0;

        /**
        * Draws pictographs that are encountered in the text.
        * This method sets aGc to use CGraphicsContext::ENullBrush.
        *
        * @since 2.6
        * @param aGc Graphics context.
        * @param aFont Used font.
        * @param aText Text.
        * @param aBox Rectangle, where the text is rendered.
        * @param aBaselineOffset Offset from the top of the rectangle to
        *   the baseline to the text.
        * @param aAlignment Text alignment.
        * @param aLeftMargin The left margin for left-aligned text, or the right
        *   margin for right-aligned text
        */
        virtual void DrawPictographsInText(
            CBitmapContext& aGc,
            const CFont& aFont,
            const TDesC& aText,
            const TRect& aBox,
            TInt aBaselineOffset,
            CGraphicsContext::TTextAlign aAlignment =
                CGraphicsContext::ELeft,
            TInt aLeftMargin = 0 ) const = 0;

        /**
        * Tells whether the given pictograph is animated or not.
        *
        * @since 2.6
        * @param aCode Pictograph code in Unicode.
        */
        virtual TBool IsAnimated( TText aCode, TAknPictographHeight aHeight ) const = 0;

        /**
        * Tries to find a matching pictograph height for a given font.
        *
        * @since 2.8
        * @param aFont Used font.
        * @param aHeight Pictograph height.
        * @return KErrNone if a supported pictograph height is found that matches
        *         aFont otherwise returns KErrNotSupported
        */
        virtual TInt SelectPictographHeightForFont(
            const CFont& aFont,
            TAknPictographHeight& aHeight
            ) const = 0;

        /**
        * Sets the pictograph drawing mode for DrawPictograph calls. Other functions e.g.
        * DrawText, etc are unaffected by this function.
        * The drawing mode is set to EDrawingModeNormal by default.
        * Note: When drawing mode EDrawingModeWhite is set only a single DrawPictograph call
        * is supported per component->Draw() call.
        *
        * @since 2.8
        * @param aDrawingMode the new pictograph drawing mode to be used.
        * @return the value of the previous pictograph drawing mode.
        */
        virtual TAknPictographDrawingMode SetPictographDrawingMode(
            TAknPictographDrawingMode aDrawingMode) = 0;
    };

#endif // AKN_PICTOGRAPH_DRAWER_INTERFACE_H
            
// End of File
