/*

 * 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