support for iPhone callbacks

[wxWidgets.git] / interface / wx / graphics.h

diff --git a/interface/wx/graphics.h b/interface/wx/graphics.h
index ac78c4cae0b2a3723d62e73640be71a7f95f2d2f..a748cb3f309442c13569ea7e8b6df1be50ea1140 100644 (file)
--- a/interface/wx/graphics.h
+++ b/interface/wx/graphics.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of various wxGraphics* classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of various wxGraphics* classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -22,18 +22,24 @@ class wxGraphicsPath : public wxGraphicsObject
 {
 public:
     /**
 {
 public:
     /**

-        Adds an arc of a circle centering at (@a x,@a y) with radius (@a r)
-        from @a startAngle to @a endAngle.
+        Adds an arc of a circle.
+
+        The circle is defined by the coordinates of its centre (@a x, @a y) or
+        @a c and its radius @a r. The arc goes from the starting angle @a
+        startAngle to @a endAngle either clockwise or counter-clockwise
+        depending on the value of @a clockwise argument.
+
+        The angles are measured in radians but, contrary to the usual
+        mathematical convention, are always @e clockwise from the horizontal
+        axis.

     */
     */

+    //@{

     virtual void AddArc(wxDouble x, wxDouble y, wxDouble r,
                         wxDouble startAngle, wxDouble endAngle,
                         bool clockwise);
     virtual void AddArc(wxDouble x, wxDouble y, wxDouble r,
                         wxDouble startAngle, wxDouble endAngle,
                         bool clockwise);

-    /**
-        Adds an arc of a circle centering at @a c with radius (@a r)
-        from @a startAngle to @a endAngle.
-    */

     void AddArc(const wxPoint2DDouble& c, wxDouble r,
                 wxDouble startAngle, wxDouble endAngle, bool clockwise);
     void AddArc(const wxPoint2DDouble& c, wxDouble r,
                 wxDouble startAngle, wxDouble endAngle, bool clockwise);

+    //@}

 
     /**
         Appends a an arc to two tangents connecting (current) to (@a x1,@a y1)
 
     /**
         Appends a an arc to two tangents connecting (current) to (@a x1,@a y1)


@@ -110,12 +116,12 @@ public:
         @return @true if the point is within the path.
     */
     bool Contains(const wxPoint2DDouble& c,
         @return @true if the point is within the path.
     */
     bool Contains(const wxPoint2DDouble& c,

-                  int fillStyle = wxODDEVEN_RULE) const;
+                  wxPolygonFillMode fillStyle = wxODDEVEN_RULE) const;

     /**
         @return @true if the point is within the path.
     */
     virtual bool Contains(wxDouble x, wxDouble y,
     /**
         @return @true if the point is within the path.
     */
     virtual bool Contains(wxDouble x, wxDouble y,

-                          int fillStyle = wxODDEVEN_RULE) const;
+                          wxPolygonFillMode fillStyle = wxODDEVEN_RULE) const;

 
     /**
         Gets the bounding box enclosing all points (possibly including control
 
     /**
         Gets the bounding box enclosing all points (possibly including control


@@ -195,49 +201,110 @@ public:
 };
 
 /**
 };
 
 /**

-    Anti-aliasing modes used by wxGraphicsContext::SetAntialisingMode
+    Anti-aliasing modes used by wxGraphicsContext::SetAntialiasMode().

 */
 enum wxAntialiasMode
 {
     /** No anti-aliasing */
 */
 enum wxAntialiasMode
 {
     /** No anti-aliasing */

-    wxANTIALIAS_NONE, 
-    
+    wxANTIALIAS_NONE,
+

     /** The default anti-aliasing */
     wxANTIALIAS_DEFAULT,
 };
 
 /**
     /** The default anti-aliasing */
     wxANTIALIAS_DEFAULT,
 };
 
 /**

-    Compositing is done using Porter-Duff compositions 
+    Interpolation quality used by wxGraphicsContext::SetInterpolationQuality().
+ */
+enum wxInterpolationQuality
+{
+    /** default interpolation, based on type of context, in general medium quality */
+    wxINTERPOLATION_DEFAULT,
+    /** no interpolation */
+    wxINTERPOLATION_NONE, 
+    /** fast interpolation, suited for interactivity */
+    wxINTERPOLATION_FAST,
+    /** better quality */
+    wxINTERPOLATION_GOOD,
+    /** best quality, not suited for interactivity */
+    wxINTERPOLATION_BEST
+};
+
+/**
+    Compositing is done using Porter-Duff compositions

     (see http://keithp.com/~keithp/porterduff/p253-porter.pdf) with
     (see http://keithp.com/~keithp/porterduff/p253-porter.pdf) with

-    wxGraphicsContext::SetCompositionMode
+    wxGraphicsContext::SetCompositionMode().

 
     The description give a short equation on how the values of a resulting
     pixel are calculated.
 
     The description give a short equation on how the values of a resulting
     pixel are calculated.

-    @R = Result, @S = Source, @D = Destination, colors premultiplied with alpha
-    @Ra, @Sa, @Da their alpha components
+    @e R = Result, @e S = Source, @e D = Destination, colors premultiplied with alpha
+    @e Ra, @e Sa, @e Da their alpha components

 */
 enum wxCompositionMode
 {
 */
 enum wxCompositionMode
 {

-    
-    /** classic Porter-Duff compositions */
-    wxCOMPOSITION_CLEAR, /**< @R = 0 */
-    wxCOMPOSITION_SOURCE, /**< @R = S */
-    wxCOMPOSITION_OVER, /**< @R = @S + @D*(1 - @Sa) */
-    wxCOMPOSITION_IN, /**< @R = @S*@Da */
-    wxCOMPOSITION_OUT, /**< @R = @S*(1 - @Da) */
-    wxCOMPOSITION_ATOP, /**< @R = @S*@Da + @D*(1 - @Sa) */
-
-    wxCOMPOSITION_DEST, /**< @R = @D, essentially a noop */
-    wxCOMPOSITION_DEST_OVER, /**< @R = @S*(1 - @Da) + @D */
-    wxCOMPOSITION_DEST_IN, /**< @R = @D*@Sa */
-    wxCOMPOSITION_DEST_OUT, /**< @R = @D*(1 - @Sa) */
-    wxCOMPOSITION_DEST_ATOP, /**< @R = @S*(1 - @Da) + @D*@Sa */
-    wxCOMPOSITION_XOR, /**< @R = @S*(1 - @Da) + @D*(1 - @Sa) */
-    
-    /** mathematical compositions */
-    wxCOMPOSITION_ADD, /**< @R = @S + @D */
+    /**
+        Indicates invalid or unsupported composition mode.
+
+        This value can't be passed to wxGraphicsContext::SetCompositionMode().
+
+        @since 2.9.2
+     */
+    wxCOMPOSITION_INVALID = -1,
+    wxCOMPOSITION_CLEAR, /**< @e R = 0 */
+    wxCOMPOSITION_SOURCE, /**< @e R = S */
+    wxCOMPOSITION_OVER, /**< @e R = @e S + @e D*(1 - @e Sa) */
+    wxCOMPOSITION_IN, /**< @e R = @e S*@e Da */
+    wxCOMPOSITION_OUT, /**< @e R = @e S*(1 - @e Da) */
+    wxCOMPOSITION_ATOP, /**< @e R = @e S*@e Da + @e D*(1 - @e Sa) */
+
+    wxCOMPOSITION_DEST, /**< @e R = @e D, essentially a noop */
+    wxCOMPOSITION_DEST_OVER, /**< @e R = @e S*(1 - @e Da) + @e D */
+    wxCOMPOSITION_DEST_IN, /**< @e R = @e D*@e Sa */
+    wxCOMPOSITION_DEST_OUT, /**< @e R = @e D*(1 - @e Sa) */
+    wxCOMPOSITION_DEST_ATOP, /**< @e R = @e S*(1 - @e Da) + @e D*@e Sa */
+    wxCOMPOSITION_XOR, /**< @e R = @e S*(1 - @e Da) + @e D*(1 - @e Sa) */
+    wxCOMPOSITION_ADD  /**< @e R = @e S + @e D */

 };
 
 };
 

+/**
+    Represents a bitmap.
+
+    The objects of this class are not created directly but only via
+    wxGraphicsContext or wxGraphicsRenderer CreateBitmap(),
+    CreateBitmapFromImage() or CreateSubBitmap() methods. They can subsequently
+    be used with wxGraphicsContext::DrawBitmap(). The only other operation is
+    testing for the bitmap validity which can be performed using IsNull()
+    method inherited from the base class.
+ */
+class wxGraphicsBitmap : public wxGraphicsObject
+{
+public:
+    /**
+        Default constructor creates an invalid bitmap.
+     */
+    wxGraphicsBitmap() {}
+
+    /**
+        Return the contents of this bitmap as wxImage.
+
+        Using this method is more efficient than converting wxGraphicsBitmap to
+        wxBitmap first and then to wxImage and can be useful if, for example,
+        you want to save wxGraphicsBitmap as a disk file in a format not
+        directly supported by wxBitmap.
+
+        Invalid image is returned if the bitmap is invalid.
+
+        @since 2.9.3
+     */
+    wxImage ConvertToImage() const;
+
+    /**
+        Return the pointer to the native bitmap data. (CGImageRef for Core Graphics, 
+        cairo_surface_t for Cairo, Bitmap* for GDI+.)
+
+        @since 2.9.4
+     */
+    void* GetNativeBitmap() const;
+};

 
 /**
     @class wxGraphicsContext
 
 /**
     @class wxGraphicsContext


@@ -297,14 +364,14 @@ public:
 
         @see wxGraphicsRenderer::CreateContext()
     */
 
         @see wxGraphicsRenderer::CreateContext()
     */

-    static wxGraphicsContext* Create(const wxWindowDC& dc);
+    static wxGraphicsContext* Create(const wxWindowDC& windowDC);

 
     /**
         Creates a wxGraphicsContext from a wxMemoryDC
 
         @see wxGraphicsRenderer::CreateContext()
     */
 
     /**
         Creates a wxGraphicsContext from a wxMemoryDC
 
         @see wxGraphicsRenderer::CreateContext()
     */

-    static wxGraphicsContext* Create(const wxMemoryDC& dc);
+    static wxGraphicsContext* Create(const wxMemoryDC& memoryDC);

 
     /**
         Creates a wxGraphicsContext from a wxPrinterDC. Under GTK+, this will
 
     /**
         Creates a wxGraphicsContext from a wxPrinterDC. Under GTK+, this will


@@ -313,7 +380,35 @@ public:
 
         @see wxGraphicsRenderer::CreateContext(), @ref overview_unixprinting
     */
 
         @see wxGraphicsRenderer::CreateContext(), @ref overview_unixprinting
     */

-    static wxGraphicsContext* Create(const wxPrinterDC& dc);
+    static wxGraphicsContext* Create(const wxPrinterDC& printerDC);
+
+    /**
+        Creates a wxGraphicsContext from a wxEnhMetaFileDC.
+
+        This function, as wxEnhMetaFileDC class itself, is only available only
+        under MSW.
+
+        @see wxGraphicsRenderer::CreateContext()
+    */
+    static wxGraphicsContext* Create(const wxEnhMetaFileDC& metaFileDC);
+
+    /**
+        Creates a wxGraphicsContext associated with a wxImage.
+
+        The image specifies the size of the context as well as whether alpha is
+        supported (if wxImage::HasAlpha()) or not and the initial contents of
+        the context. The @a image object must have a life time greater than
+        that of the new context as the context copies its contents back to the
+        image when it is destroyed.
+
+        @since 2.9.3
+     */
+    static wxGraphicsContext* Create(wxImage& image);
+
+    /**
+       Create a lightweight context that can be used only for measuring text.
+    */
+    static wxGraphicsContext* Create();

 
     /**
         Clips drawings to the specified region.
 
     /**
         Clips drawings to the specified region.


@@ -331,6 +426,35 @@ public:
     */
     virtual void ConcatTransform(const wxGraphicsMatrix& matrix) = 0;
 
     */
     virtual void ConcatTransform(const wxGraphicsMatrix& matrix) = 0;
 

+    /**
+        Creates wxGraphicsBitmap from an existing wxBitmap.
+
+        Returns an invalid wxNullGraphicsBitmap on failure.
+     */
+    virtual wxGraphicsBitmap CreateBitmap( const wxBitmap &bitmap ) = 0;
+
+    /**
+        Creates wxGraphicsBitmap from an existing wxImage.
+
+        This method is more efficient than converting wxImage to wxBitmap first
+        and then calling CreateBitmap() but otherwise has the same effect.
+
+        Returns an invalid wxNullGraphicsBitmap on failure.
+
+        @since 2.9.3
+     */
+    virtual wxGraphicsBitmap CreateBitmapFromImage(const wxImage& image);
+
+    /**
+        Extracts a sub-bitmap from an existing bitmap.
+
+        Currently this function is implemented in the native MSW and OS X
+        versions but not when using Cairo.
+     */
+    virtual wxGraphicsBitmap CreateSubBitmap(const wxGraphicsBitmap& bitmap,
+                                             wxDouble x, wxDouble y,
+                                             wxDouble w, wxDouble h) = 0;
+

     /**
         Creates a native brush from a wxBrush.
     */
     /**
         Creates a native brush from a wxBrush.
     */


@@ -342,6 +466,19 @@ public:
     virtual wxGraphicsFont CreateFont(const wxFont& font,
                                       const wxColour& col = *wxBLACK) const;
 
     virtual wxGraphicsFont CreateFont(const wxFont& font,
                                       const wxColour& col = *wxBLACK) const;
 

+    /**
+        Creates a font object with the specified attributes.
+
+        The use of overload taking wxFont is preferred, see
+        wxGraphicsRenderer::CreateFont() for more details.
+
+        @since 2.9.3
+     */
+    virtual wxGraphicsFont CreateFont(double sizeInPixels,
+                                      const wxString& facename,
+                                      int flags = wxFONTFLAG_DEFAULT,
+                                      const wxColour& col = *wxBLACK) const;
+

     /**
         Creates a wxGraphicsContext from a native context. This native context
         must be a CGContextRef for Core Graphics, a Graphics pointer for
     /**
         Creates a wxGraphicsContext from a native context. This native context
         must be a CGContextRef for Core Graphics, a Graphics pointer for


@@ -359,15 +496,25 @@ public:
     static wxGraphicsContext* CreateFromNativeWindow(void* window);
 
     /**
     static wxGraphicsContext* CreateFromNativeWindow(void* window);
 
     /**

-        Creates a native brush, having a linear gradient, starting at
-        (@a x1, @a y1) with color @a c1 to (@a x2, @a y2) with color @a c2.
+        Creates a native brush with a linear gradient.
+
+        The brush starts at (@a x1, @a y1) and ends at (@a x2, @a y2). Either
+        just the start and end gradient colours (@a c1 and @a c2) or full set
+        of gradient @a stops can be specified.
+
+        The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1.

     */
     */

-    virtual wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
-                                                      wxDouble y1,
-                                                      wxDouble x2,
-                                                      wxDouble y2,
-                                                      const wxColour& c1,
-                                                      const wxColour& c2) const;
+    //@{
+    wxGraphicsBrush
+    CreateLinearGradientBrush(wxDouble x1, wxDouble y1,
+                              wxDouble x2, wxDouble y2,
+                              const wxColour& c1, const wxColour& c2) const;
+
+    wxGraphicsBrush
+    CreateLinearGradientBrush(wxDouble x1, wxDouble y1,
+                              wxDouble x2, wxDouble y2,
+                              const wxGraphicsGradientStops& stops) const;
+    //@}

 
     /**
         Creates a native affine transformation matrix from the passed in
 
     /**
         Creates a native affine transformation matrix from the passed in


@@ -378,6 +525,14 @@ public:
                                           wxDouble tx = 0.0,
                                           wxDouble ty = 0.0) const;
 
                                           wxDouble tx = 0.0,
                                           wxDouble ty = 0.0) const;
 

+    /**
+        Creates a native affine transformation matrix from the passed
+        generic one.
+
+        @since 2.9.4
+    */
+    wxGraphicsMatrix CreateMatrix(const wxAffineMatrix2DBase& mat) const;
+

     /**
         Creates a native graphics path which is initially empty.
     */
     /**
         Creates a native graphics path which is initially empty.
     */


@@ -389,22 +544,43 @@ public:
     virtual wxGraphicsPen CreatePen(const wxPen& pen) const;
 
     /**
     virtual wxGraphicsPen CreatePen(const wxPen& pen) const;
 
     /**

-        Creates a native brush, having a radial gradient originating at
-        (@a xo, @a yc) with color @a oColour and ends on a circle around
-        (@a xc, @a yc) with the given @a radius and color @a cColour.
+        Creates a native brush with a radial gradient.
+
+        The brush originates at (@a xo, @a yc) and ends on a circle around
+        (@a xc, @a yc) with the given @a radius.
+
+        The gradient may be specified either by its start and end colours @a
+        oColor and @a cColor or by a full set of gradient @a stops.
+
+        The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1.

     */
     */

-    virtual wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
-                                                      wxDouble xc, wxDouble yc,
-                                                      wxDouble radius,
-                                                      const wxColour& oColor,
-                                                      const wxColour& cColor) const;
+    //@{
+    virtual wxGraphicsBrush
+    CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
+                              wxDouble xc, wxDouble yc,
+                              wxDouble radius,
+                              const wxColour& oColor,
+                              const wxColour& cColor) const;
+
+    virtual wxGraphicsBrush
+    CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
+                              wxDouble xc, wxDouble yc,
+                              wxDouble radius,
+                              const wxGraphicsGradientStops& stops) = 0;
+    //@}

 
     /**
         Draws the bitmap. In case of a mono bitmap, this is treated as a mask
         and the current brushed is used for filling.
     */
 
     /**
         Draws the bitmap. In case of a mono bitmap, this is treated as a mask
         and the current brushed is used for filling.
     */

-    virtual void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y,
+    //@{
+    virtual void DrawBitmap(const wxGraphicsBitmap& bmp,
+                            wxDouble x, wxDouble y,
+                            wxDouble w, wxDouble h ) = 0;
+    virtual void DrawBitmap(const wxBitmap& bmp,
+                            wxDouble x, wxDouble y,

                             wxDouble w, wxDouble h) = 0;
                             wxDouble w, wxDouble h) = 0;

+    //@}

 
     /**
         Draws an ellipse.
 
     /**
         Draws an ellipse.


@@ -593,8 +769,10 @@ public:
     virtual void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints,
                              const wxPoint2DDouble* endPoints);
     /**
     virtual void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints,
                              const wxPoint2DDouble* endPoints);
     /**

-        Stroke disconnected lines from begin to end points, fastest method
-        available for this purpose.
+        Stroke lines connecting all the points.
+
+        Unlike the other overload of this function, this method draws a single
+        polyline and not a number of disconnected lines.

     */
     virtual void StrokeLines(size_t n, const wxPoint2DDouble* points);
 
     */
     virtual void StrokeLines(size_t n, const wxPoint2DDouble* points);
 


@@ -609,39 +787,222 @@ public:
     virtual void Translate(wxDouble dx, wxDouble dy) = 0;
 
     /**
     virtual void Translate(wxDouble dx, wxDouble dy) = 0;
 
     /**

-        Redirects all rendering is done into a fully transparent temporary context 
+        Redirects all rendering is done into a fully transparent temporary context

     */
     virtual void BeginLayer(wxDouble opacity) = 0;
 
     */
     virtual void BeginLayer(wxDouble opacity) = 0;
 

-    /** 
-        Composites back the drawings into the context with the opacity given at 
+    /**
+        Composites back the drawings into the context with the opacity given at

         the BeginLayer call
     */
     virtual void EndLayer() = 0;
 
         the BeginLayer call
     */
     virtual void EndLayer() = 0;
 

-    /** 
+    /**

         Sets the antialiasing mode, returns true if it supported
     */
     virtual bool SetAntialiasMode(wxAntialiasMode antialias) = 0;
 
         Sets the antialiasing mode, returns true if it supported
     */
     virtual bool SetAntialiasMode(wxAntialiasMode antialias) = 0;
 

-    /** 
+    /**

         Returns the current shape antialiasing mode
     */
     virtual wxAntialiasMode GetAntialiasMode() const ;
         Returns the current shape antialiasing mode
     */
     virtual wxAntialiasMode GetAntialiasMode() const ;

-    
+
+    /**
+        Sets the interpolation quality, returns true if it is supported.
+
+        Not implemented in Cairo backend currently.
+     */
+    virtual bool SetInterpolationQuality(wxInterpolationQuality interpolation) = 0;
+
+    /**
+        Returns the current interpolation quality.
+     */
+    virtual wxInterpolationQuality GetInterpolationQuality() const;
+

     /**
         Sets the compositing operator, returns true if it supported
     */
     virtual bool SetCompositionMode(wxCompositionMode op) = 0;
 
     /**
         Sets the compositing operator, returns true if it supported
     */
     virtual bool SetCompositionMode(wxCompositionMode op) = 0;
 

-    /** 
+    /**

         Returns the current compositing operator
     */
     virtual wxCompositionMode GetCompositionMode() const;
         Returns the current compositing operator
     */
     virtual wxCompositionMode GetCompositionMode() const;

+
+
+    /**
+       Push the current state of the context's transformation matrix on a
+       stack.
+
+       @see wxGraphicsContext::PopState
+    */
+    virtual void PushState() = 0;
+
+    /**
+       Pops a stored state from the stack and sets the current transformation
+       matrix to that state.
+
+       @see wxGraphicsContext::PopState
+    */
+    virtual void PopState() = 0;
+
+
+    virtual bool ShouldOffset() const;
+    virtual void EnableOffset(bool enable = true);
+    void DisableOffset();
+    bool OffsetEnabled();
+
+    /**
+       Begin a new document (relevant only for printing / pdf etc.)
+       If there is a progress dialog, message will be shown.
+    */
+    virtual bool StartDoc( const wxString& message );
+
+    /**
+       Done with that document (relevant only for printing / pdf etc.)
+    */
+    virtual void EndDoc();
+
+    /**
+       Opens a new page (relevant only for printing / pdf etc.) with the given
+       size in points.  (If both are null the default page size will be used.)
+    */
+    virtual void StartPage( wxDouble width = 0, wxDouble height = 0 );
+
+    /**
+       Ends the current page  (relevant only for printing / pdf etc.)
+    */
+    virtual void EndPage();
+
+    /**
+       Make sure that the current content of this context is immediately visible.
+    */
+    virtual void Flush();
+
+    /**
+       Returns the size of the graphics context in device coordinates.
+    */
+    void GetSize(wxDouble* width, wxDouble* height) const;

     
     

+    /**
+       Returns the resolution of the graphics context in device points per inch.
+    */
+    virtual void GetDPI( wxDouble* dpiX, wxDouble* dpiY);
+
+};
+
+/**
+    Represents a single gradient stop in a collection of gradient stops as
+    represented by wxGraphicsGradientStops.
+
+    @library{wxcore}
+    @category{gdi}
+
+    @since 2.9.1
+*/
+class wxGraphicsGradientStop
+{
+public:
+    /**
+        Creates a stop with the given colour and position.
+
+        @param col The colour of this stop. Note that the alpha component of
+            the colour is honoured thus allowing the background colours to
+            partially show through the gradient.
+        @param pos The stop position, must be in [0, 1] range with 0 being the
+            beginning and 1 the end of the gradient.
+    */
+    wxGraphicsGradientStop(wxColour col = wxTransparentColour, float pos = 0.);
+
+    /// Return the stop colour.
+    const wxColour& GetColour() const;
+
+    /**
+        Change the stop colour.
+
+        @param col The new colour.
+    */
+    void SetColour(const wxColour& col);
+
+    /// Return the stop position.
+    float GetPosition() const;
+
+    /**
+        Change the stop position.
+
+        @param pos The new position, must always be in [0, 1] range.
+    */
+    void SetPosition(float pos);

 };
 
 };
 

+/**
+    Represents a collection of wxGraphicGradientStop values for use with
+    CreateLinearGradientBrush and CreateRadialGradientBrush.
+
+    The stops are maintained in order of position.  If two or more stops are
+    added with the same position then the one(s) added later come later.
+    This can be useful for producing discontinuities in the colour gradient.
+
+    Notice that this class is write-once, you can't modify the stops once they
+    had been added.
+
+    @library{wxcore}
+    @category{gdi}
+
+    @since 2.9.1
+*/
+class wxGraphicsGradientStops
+{
+public:
+    /**
+        Initializes the gradient stops with the given boundary colours.
+
+        Creates a wxGraphicsGradientStops instance with start colour given
+        by @a startCol and end colour given by @a endCol.
+    */
+    wxGraphicsGradientStops(wxColour startCol = wxTransparentColour,
+                            wxColour endCol = wxTransparentColour);
+
+    /**
+        Add a new stop.
+    */
+    //@{
+    void Add(const wxGraphicsGradientStop& stop);
+    void Add(wxColour col, float pos);
+    //@}
+
+    /**
+        Returns the stop at the given index.
+
+        @param n The index, must be in [0, GetCount()) range.
+    */
+    wxGraphicsGradientStop Item(unsigned n) const;
+
+    /**
+        Returns the number of stops.
+    */
+    size_t GetCount() const;
+
+    /**
+        Set the start colour to @a col
+    */
+    void SetStartColour(wxColour col);
+
+    /**
+        Returns the start colour.
+    */
+    wxColour GetStartColour() const;

 
 

+    /**
+        Set the end colour to @a col
+    */
+    void SetEndColour(wxColour col);
+
+    /**
+        Returns the end colour.
+    */
+    wxColour GetEndColour() const;
+};

 
 /**
     @class wxGraphicsRenderer
 
 /**
     @class wxGraphicsRenderer


@@ -667,6 +1028,41 @@ public:
 class wxGraphicsRenderer : public wxObject
 {
 public:
 class wxGraphicsRenderer : public wxObject
 {
 public:

+    /**
+        Creates wxGraphicsBitmap from an existing wxBitmap.
+
+        Returns an invalid wxNullGraphicsBitmap on failure.
+     */
+    virtual wxGraphicsBitmap CreateBitmap( const wxBitmap &bitmap ) = 0;
+
+    /**
+        Creates wxGraphicsBitmap from an existing wxImage.
+
+        This method is more efficient than converting wxImage to wxBitmap first
+        and then calling CreateBitmap() but otherwise has the same effect.
+
+        Returns an invalid wxNullGraphicsBitmap on failure.
+
+        @since 2.9.3
+     */
+    virtual wxGraphicsBitmap CreateBitmapFromImage(const wxImage& image) = 0;
+
+    /**
+       Creates a wxImage from a wxGraphicsBitmap.
+
+       This method is used by the more convenient wxGraphicsBitmap::ConvertToImage.
+    */
+    virtual wxImage CreateImageFromBitmap(const wxGraphicsBitmap& bmp) = 0;
+
+    /**
+        Creates wxGraphicsBitmap from a native bitmap handle.
+
+        @a bitmap meaning is platform-dependent. Currently it's a GDI+ @c
+        Bitmap pointer under MSW, @c CGImage pointer under OS X or a @c
+        cairo_surface_t pointer when using Cairo under any platform.
+     */
+    virtual wxGraphicsBitmap CreateBitmapFromNativeBitmap( void* bitmap ) = 0;
+

     /**
         Creates a wxGraphicsContext from a wxWindow.
     */
     /**
         Creates a wxGraphicsContext from a wxWindow.
     */


@@ -675,17 +1071,35 @@ public:
     /**
         Creates a wxGraphicsContext from a wxWindowDC
     */
     /**
         Creates a wxGraphicsContext from a wxWindowDC
     */

-    virtual wxGraphicsContext* CreateContext(const wxWindowDC& dc) = 0 ;
+    virtual wxGraphicsContext* CreateContext(const wxWindowDC& windowDC) = 0 ;

 
     /**
         Creates a wxGraphicsContext from a wxMemoryDC
     */
 
     /**
         Creates a wxGraphicsContext from a wxMemoryDC
     */

-    virtual wxGraphicsContext* CreateContext(const wxMemoryDC& dc) = 0 ;
+    virtual wxGraphicsContext* CreateContext(const wxMemoryDC& memoryDC) = 0 ;

 
     /**
         Creates a wxGraphicsContext from a wxPrinterDC
     */
 
     /**
         Creates a wxGraphicsContext from a wxPrinterDC
     */

-    virtual wxGraphicsContext* CreateContext(const wxPrinterDC& dc) = 0 ;
+    virtual wxGraphicsContext* CreateContext(const wxPrinterDC& printerDC) = 0 ;
+
+    /**
+        Creates a wxGraphicsContext from a wxEnhMetaFileDC.
+
+        This function, as wxEnhMetaFileDC class itself, is only available only
+        under MSW.
+    */
+    virtual wxGraphicsContext* CreateContext(const wxEnhMetaFileDC& metaFileDC) = 0;
+
+    /**
+        Creates a wxGraphicsContext associated with a wxImage.
+
+        This function is used by wxContext::CreateFromImage() and is not
+        normally called directly.
+
+        @since 2.9.3
+     */
+    wxGraphicsContext* CreateContextFromImage(wxImage& image);

 
     /**
         Creates a native brush from a wxBrush.
 
     /**
         Creates a native brush from a wxBrush.


@@ -704,6 +1118,12 @@ public:
     */
     virtual wxGraphicsContext* CreateContextFromNativeWindow(void* window) = 0;
 
     */
     virtual wxGraphicsContext* CreateContextFromNativeWindow(void* window) = 0;
 

+    /**
+        Creates a wxGraphicsContext that can be used for measuring texts only.
+        No drawing commands are allowed.
+    */
+    virtual wxGraphicsContext * CreateMeasuringContext() = 0;
+

     /**
         Creates a native graphics font from a wxFont and a text colour.
     */
     /**
         Creates a native graphics font from a wxFont and a text colour.
     */


@@ -711,15 +1131,46 @@ public:
                                       const wxColour& col = *wxBLACK) = 0;
 
     /**
                                       const wxColour& col = *wxBLACK) = 0;
 
     /**

-        Creates a native brush, having a linear gradient, starting at
-        (@a x1, @a y1) with color @a c1 to (@a x2, @a y2) with color @a c2.
+        Creates a graphics font with the given characteristics.
+
+        If possible, the CreateFont() overload taking wxFont should be used
+        instead. The main advantage of this overload is that it can be used
+        without X server connection under Unix when using Cairo.
+
+        @param sizeInPixels
+            Height of the font in user space units, i.e. normally pixels.
+            Notice that this is different from the overload taking wxFont as
+            wxFont size is specified in points.
+        @param facename
+            The name of the font. The same font name might not be available
+            under all platforms so the font name can also be empty to use the
+            default platform font.
+        @param flags
+            Combination of wxFontFlag enum elements. Currently only
+            @c wxFONTFLAG_ITALIC and @c wxFONTFLAG_BOLD are supported. By
+            default the normal font version is used.
+        @param col
+            The font colour, black by default.
+
+        @since 2.9.3
+     */
+    virtual wxGraphicsFont CreateFont(double sizeInPixels,
+                                      const wxString& facename,
+                                      int flags = wxFONTFLAG_DEFAULT,
+                                      const wxColour& col = *wxBLACK) = 0;
+
+
+    /**
+        Creates a native brush with a linear gradient.
+
+        Stops support is new since wxWidgets 2.9.1, previously only the start
+        and end colours could be specified.

     */
     virtual wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
                                                       wxDouble y1,
                                                       wxDouble x2,
                                                       wxDouble y2,
     */
     virtual wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
                                                       wxDouble y1,
                                                       wxDouble x2,
                                                       wxDouble y2,

-                                                      const wxColour& c1,
-                                                      const wxColour& c2) = 0;
+                                                      const wxGraphicsGradientStops& stops) = 0;

 
     /**
         Creates a native affine transformation matrix from the passed in
 
     /**
         Creates a native affine transformation matrix from the passed in


@@ -741,15 +1192,25 @@ public:
     virtual wxGraphicsPen CreatePen(const wxPen& pen) = 0;
 
     /**
     virtual wxGraphicsPen CreatePen(const wxPen& pen) = 0;
 
     /**

-        Creates a native brush, having a radial gradient originating at
-        (@a xo, @a yc) with color @a oColour and ends on a circle around
-        (@a xc, @a yc) with the given @a radius and color @a cColour.
+        Creates a native brush with a radial gradient.
+
+        Stops support is new since wxWidgets 2.9.1, previously only the start
+        and end colours could be specified.

     */
     virtual wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
                                                       wxDouble xc, wxDouble yc,
                                                       wxDouble radius,
     */
     virtual wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
                                                       wxDouble xc, wxDouble yc,
                                                       wxDouble radius,

-                                                      const wxColour& oColour,
-                                                      const wxColour& cColour) = 0;
+                                                      const wxGraphicsGradientStops& stops) = 0;
+
+    /**
+        Extracts a sub-bitmap from an existing bitmap.
+
+        Currently this function is implemented in the native MSW and OS X
+        versions but not when using Cairo.
+     */
+    virtual wxGraphicsBitmap CreateSubBitmap(const wxGraphicsBitmap& bitmap,
+                                             wxDouble x, wxDouble y,
+                                             wxDouble w, wxDouble h) = 0;

 
     /**
         Returns the default renderer on this platform. On OS X this is the Core
 
     /**
         Returns the default renderer on this platform. On OS X this is the Core


@@ -757,6 +1218,8 @@ public:
         on GTK we currently default to the cairo renderer.
     */
     static wxGraphicsRenderer* GetDefaultRenderer();
         on GTK we currently default to the cairo renderer.
     */
     static wxGraphicsRenderer* GetDefaultRenderer();

+    static wxGraphicsRenderer* GetCairoRenderer();
+

 };
 
 
 };
 
 


@@ -879,7 +1342,10 @@ public:
     virtual bool IsIdentity() const;
 
     /**
     virtual bool IsIdentity() const;
 
     /**

-        Rotates this matrix (in radians).
+        Rotates this matrix clockwise (in radians).
+
+        @param angle
+            Rotation angle in radians, clockwise.

     */
     virtual void Rotate(wxDouble angle);
 
     */
     virtual void Rotate(wxDouble angle);
 


@@ -912,3 +1378,10 @@ public:
     virtual void Translate(wxDouble dx, wxDouble dy);
 };
 
     virtual void Translate(wxDouble dx, wxDouble dy);
 };
 

+
+const wxGraphicsPen     wxNullGraphicsPen;
+const wxGraphicsBrush   wxNullGraphicsBrush;
+const wxGraphicsFont    wxNullGraphicsFont;
+const wxGraphicsBitmap  wxNullGraphicsBitmap;
+const wxGraphicsMatrix  wxNullGraphicsMatrix;
+const wxGraphicsPath    wxNullGraphicsPath;