Add new sample project files.

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

diff --git a/interface/wx/graphics.h b/interface/wx/graphics.h
index ac78c4cae0b2a3723d62e73640be71a7f95f2d2f..7425c4a78add69012c674d3710639e57874dc883 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)


@@ -195,47 +201,68 @@ 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 */

 };
 
 
 };
 
 


@@ -315,6 +342,16 @@ public:
     */
     static wxGraphicsContext* Create(const wxPrinterDC& dc);
 
     */
     static wxGraphicsContext* Create(const wxPrinterDC& dc);
 

+    /**
+        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& dc);
+

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


@@ -359,15 +396,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


@@ -389,15 +436,30 @@ 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
 
     /**
         Draws the bitmap. In case of a mono bitmap, this is treated as a mask


@@ -593,8 +655,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 +673,160 @@ 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 supported
+     */
+    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;

-    
+
+};
+
+/**
+    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.
+    */
+    unsigned 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


@@ -687,6 +872,14 @@ public:
     */
     virtual wxGraphicsContext* CreateContext(const wxPrinterDC& dc) = 0 ;
 
     */
     virtual wxGraphicsContext* CreateContext(const wxPrinterDC& dc) = 0 ;
 

+    /**
+        Creates a wxGraphicsContext from a wxEnhMetaFileDC.
+
+        This function, as wxEnhMetaFileDC class itself, is only available only
+        under MSW.
+    */
+    virtual wxGraphicsContext* CreateContext(const wxEnhMetaFileDC& dc) = 0;
+

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


@@ -704,22 +897,30 @@ 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.
     */
     virtual wxGraphicsFont CreateFont(const wxFont& font,
                                       const wxColour& col = *wxBLACK) = 0;
 
     /**
         Creates a native graphics font from a wxFont and a text colour.
     */
     virtual wxGraphicsFont CreateFont(const wxFont& font,
                                       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 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 +942,15 @@ 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;

 
     /**
         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