/*

* Copyright (c) 2007-2008 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:   Canvas visual

*

*/

#ifndef C_ALFCANVASVISUAL_H

#define C_ALFCANVASVISUAL_H

#include <alf/alfvisual.h>

#include <alf/alftimedvalue.h>

#include <alf/alfrealline.h>

#include <alf/alfgc.h>

#include <gdi.h>

class CAlfControl;

class CAlfLayout;

class CAlfGc;

class CAlfCanvasVisual;

class CAlfTexture;

class CAlfTextStyle;

/**

 * Provides callback method for getting notifications when there is a need 

 * to update the canvas content. 

 *

 * Implementation of this method should do the drawing using given canvas

 * and its drawing methods.

 *

 * @param aCanvas Canvas visual which is about to be refreshed.

 */

class MAlfCanvasObserver

    {

public:

    virtual void UpdateCanvas(CAlfCanvasVisual& aCanvas) = 0;

    };

/**

 *  Canvas visual can be used to draw custom graphics such as images, texts, 

 *  lines, polygons,...into the display using simple drawing primitives.

 *

 *  Usage:

 *  @code

 *  void CMyCanvasControl::ConstructL()

 *     {

 *     ...    

 *     iCanvasVisual = CAlfCanvasVisual::AddNewL(*this, iLayout);

 *     iCanvasVisual->SetCanvasObserver(this);

 *     UpdateCanvas(*iCanvasVisual);

 *     ...

 *     }

 *   

 *  void CMyCanvasControl::UpdateCanvas(CAlfCanvasVisual& aCanvas)

 *      {

 *      aCanvas.BeginDraw();

 *      aCanvas.SetPenColor(KRgbBlue);

 *      aCanvas.DrawText(_L("Hello world !"), iTextRect);    

 *      aCanvas.EndDraw();

 *      }

 *

 *  @endcode

 * 

 *  @lib alfclient.lib

 *  @since S60 v5.0

 */

NONSHARABLE_CLASS( CAlfCanvasVisual ) : public CAlfVisual

    {

public:

    /**

     * Constructor, which gives ownership to the control.

     *

     * @param aOwnerControl The control

     * @param aParentLayout If given, the parent layout.

     * @return New instance. Ownership NOT transreffed (owned by control)

     */

    IMPORT_C static CAlfCanvasVisual* AddNewL(CAlfControl& aOwnerControl,

                                            CAlfLayout* aParentLayout = 0);

    /**

     * Constructor.

     */

    IMPORT_C CAlfCanvasVisual();

    /**

     * Second-phase constructor.

     */

    IMPORT_C void ConstructL(CAlfControl& aOwner);

    /**

     * Destructor.

     */

    IMPORT_C virtual ~CAlfCanvasVisual();

    /**

     * Sets canvas observer which is responsible for doing the actual drawing

     * commands into canvas.

     *

     * @param aObserver Canvas observer.

     */

    IMPORT_C void SetCanvasObserver( MAlfCanvasObserver* aObserver );

    /**

     * Prepares the canvas for drawing.

     * This method should be called before calling any drawing commands

     */

    IMPORT_C void BeginDraw();

    /**

     * Ends the actual drawing on the canvas.

     * This method should be called after calling last drawing method. 

     *

     */

    IMPORT_C void EndDraw();

    /**

     * Draws an image on the canvas visual. For more flexible image drawing 

     * consider using CAlfImageVisual. 

     *

     * @param aTexture Image Texture

     * @param aDestinationRect Bounding rectangle for the image

     */

    IMPORT_C void DrawImage(const CAlfTexture& aTexture, const TAlfRealRect& aDestinationRect);    

    /**

     * Draws a text on the canvas visual. For more flexible text drawing 

     * consider using CAlfTextVisual.  

     *

     * @param aText Text to be displayed

     * @param aDestinationRect Bounding rectangle for the text

     */    

    IMPORT_C void DrawText(const TDesC& aText, const TAlfRealRect& aDestinationRect);  

   /**

     * Draws lines on the canvas visual 

     * @param aLines Array of Lines which is split into the number of lines specified in aLineCount

     * @param aLineCount Number of linesl

     */

    IMPORT_C void DrawLines(const TAlfRealLine* aLines, TInt aLineCount);

   /**

    * Draws ellipse on the canvas visual 

    * @param aDestinationRect Bounding rectangle for the ellipse

    */

    IMPORT_C void DrawEllipse(const TAlfRealRect& aDestinationRect);

   /**

    * Draws points  on the canvas visual 

    * @param aPoints Array of Points to be drawn

    * @param aPointcount Number of Points

    */    

    IMPORT_C void DrawPoints(const TAlfRealPoint* aPoints, TInt aPointCount); 

   /**

    * Draws a polygon on the canvas visual 

    * @param aPoints Array of points defining the polygon

    * @param aPointcount Number of Points

    */

    IMPORT_C void DrawPolygon(const TAlfRealPoint* aPoints, TInt aPointCount);

   /**

    * Draws rectangles on the canvas visual

    * @param aRects Array of rectangles to be drawn

    * @param aRectCount Number of rectangles

    */

    IMPORT_C void DrawRects(const TAlfRealRect* aRects, TInt aRectCount);

   /**

    * Sets the Text style. 

    * Subsequent calls to DrawText will use this Text style

    * @param aTextStyle Text style

    */

    IMPORT_C void SetTextStyle(const CAlfTextStyle& aTextStyle);

   /**

    * Sets the pen color for an object to be drawn

    * Subsequent calls to Draw methods will use this pen color

    * @param 

    */	

    IMPORT_C void SetPenColor(const TRgb& aColor);

   /**

    * Sets the pen width for an object to be drawn

    * Subsequent calls to Draw methods will use this pen width

    * @param 

    */

	IMPORT_C void SetPenWidth(const TReal32& aWidth);

   /**

    * Sets the opacity for an object to be drawn

    * Subsequent calls to Draw methods will use this opacity

    * @param

    */

	IMPORT_C void SetPenOpacity(const TReal32& aOpacity);

   /**

    * Sets the mode for filling a polygon

    * @param aPolygonDrawMode Even-Odd fill or Non-Zero fill

    */

    IMPORT_C void SetPolygonDrawMode(TAlfPolygonDrawMode aPolygonDrawMode);

   /**

    * Sets the allignment of Text to be drawn

    * Subsequent DrawText will draw text with this allignment

    * @param aAlignHorizontal horizontal allignment

    * @param aAlignVertical Vertical allignment

    */

  	IMPORT_C void SetTextAlign(TAlfAlignHorizontal aAlignHorizontal, TAlfAlignVertical aAlignVertical);

   /**

    * Loads identity matrix for canvas draw methods. Note that this does not

    * affect on the visuals transformation that can be accessed using 

    * CAlfVisual::Transfromation().

    */

 	IMPORT_C void LoadIdentity();

   /**

    * Translates the canvas

    * @param aX X-axis offset

    * @param aY Y-axis offset

    * @param aZ Z-axis offset

    */	

    IMPORT_C void Translate(const TReal32& aX, const TReal32& aY, const TReal32& aZ);

   /**

    * Scales the canvas

    * @param aX X-axis offset

    * @param aY Y-axis offset

    * @param aZ Z-axis offset

    */

    IMPORT_C void Scale(const TReal32& aX, const TReal32& aY, const TReal32& aZ);

   /**

    * Rotates the canvas

    * @param aX X-axis offset

    * @param aY Y-axis offset

    * @param aZ Z-axis offset

    */

    IMPORT_C void Rotate(const TReal32& aAngle, const TReal32& aX, const TReal32& aY, const TReal32& aZ);

    /**

     * From CAlfVisual

     * @see CAlfVisual

     */

    IMPORT_C void RemoveAndDestroyAllD();

    IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0);

    IMPORT_C CAlfVisual* FindTag(const TDesC8& aTag);

protected:

    void SendBuffer( const TPtrC8& aBuffer );

    /**

     * From CAlfVisual

     * @see CAlfVisual

     */

    IMPORT_C void DoRemoveAndDestroyAllD();

    IMPORT_C void PropertyOwnerExtension(const TUid& aExtensionUid, TAny** aExtensionParams);

private:

    struct TCanvasVisualPrivateData;

    TCanvasVisualPrivateData* iCanvasVisualData;    

    };

#endif // C_ALFCANVASVISUAL_H