Resolve ambiguity between GetClientXXX() methods in wxOSX wxComboBox.

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

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


@@ -194,6 +200,70 @@ public:
     bool IsNull() const;
 };
 
     bool IsNull() const;
 };
 

+/**
+    Anti-aliasing modes used by wxGraphicsContext::SetAntialiasMode().
+*/
+enum wxAntialiasMode
+{
+    /** No anti-aliasing */
+    wxANTIALIAS_NONE,
+
+    /** The default anti-aliasing */
+    wxANTIALIAS_DEFAULT,
+};
+
+/**
+    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
+    wxGraphicsContext::SetCompositionMode().
+
+    The description give a short equation on how the values of a resulting
+    pixel are calculated.
+    @e R = Result, @e S = Source, @e D = Destination, colors premultiplied with alpha
+    @e Ra, @e Sa, @e Da their alpha components
+*/
+enum wxCompositionMode
+{
+    /**
+        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 */
+};

 
 
 /**
 
 
 /**


@@ -272,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.
     */


@@ -316,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


@@ -346,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


@@ -378,13 +483,13 @@ public:
         Draws a polygon.
     */
     virtual void DrawLines(size_t n, const wxPoint2DDouble* points,
         Draws a polygon.
     */
     virtual void DrawLines(size_t n, const wxPoint2DDouble* points,

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

 
     /**
         Draws the path by first filling and then stroking.
     */
     virtual void DrawPath(const wxGraphicsPath& path,
 
     /**
         Draws the path by first filling and then stroking.
     */
     virtual void DrawPath(const wxGraphicsPath& path,

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

 
     /**
         Draws a rectangle.
 
     /**
         Draws a rectangle.


@@ -404,6 +509,12 @@ public:
     /**
         Draws text at the defined position.
 
     /**
         Draws text at the defined position.
 

+        @param str
+            The text to draw.
+        @param x
+            The x coordinate position to draw the text at.
+        @param y
+            The y coordinate position to draw the text at.

         @param angle
             The angle relative to the (default) horizontal direction to draw
             the string.
         @param angle
             The angle relative to the (default) horizontal direction to draw
             the string.


@@ -412,6 +523,12 @@ public:
     /**
         Draws text at the defined position.
 
     /**
         Draws text at the defined position.
 

+        @param str
+            The text to draw.
+        @param x
+            The x coordinate position to draw the text at.
+        @param y
+            The y coordinate position to draw the text at.

         @param backgroundBrush
             Brush to fill the text with.
     */
         @param backgroundBrush
             Brush to fill the text with.
     */


@@ -420,6 +537,12 @@ public:
     /**
         Draws text at the defined position.
 
     /**
         Draws text at the defined position.
 

+        @param str
+            The text to draw.
+        @param x
+            The x coordinate position to draw the text at.
+        @param y
+            The y coordinate position to draw the text at.

         @param angle
             The angle relative to the (default) horizontal direction to draw
             the string.
         @param angle
             The angle relative to the (default) horizontal direction to draw
             the string.


@@ -433,7 +556,7 @@ public:
         Fills the path with the current brush.
     */
     virtual void FillPath(const wxGraphicsPath& path,
         Fills the path with the current brush.
     */
     virtual void FillPath(const wxGraphicsPath& path,

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

 
     /**
         Returns the native context (CGContextRef for Core Graphics, Graphics
 
     /**
         Returns the native context (CGContextRef for Core Graphics, Graphics


@@ -495,7 +618,7 @@ public:
     /**
         Sets the brush for filling paths.
     */
     /**
         Sets the brush for filling paths.
     */

-    void SetBrush(const wxGraphicsBrush& brush);
+    virtual void SetBrush(const wxGraphicsBrush& brush);

 
     /**
         Sets the font for drawing text.
 
     /**
         Sets the font for drawing text.


@@ -504,16 +627,16 @@ public:
     /**
         Sets the font for drawing text.
     */
     /**
         Sets the font for drawing text.
     */

-    void SetFont(const wxGraphicsFont& font);
+    virtual void SetFont(const wxGraphicsFont& font);

 
     /**
         Sets the pen used for stroking.
     */
 
     /**
         Sets the pen used for stroking.
     */

-    void SetPen(const wxGraphicsPen& pen);
+    void SetPen(const wxPen& pen);

     /**
         Sets the pen used for stroking.
     */
     /**
         Sets the pen used for stroking.
     */

-    void SetPen(const wxPen& pen);
+    virtual void SetPen(const wxGraphicsPen& pen);

 
     /**
         Sets the current transformation matrix of this context
 
     /**
         Sets the current transformation matrix of this context


@@ -529,13 +652,15 @@ public:
         Stroke disconnected lines from begin to end points, fastest method
         available for this purpose.
     */
         Stroke disconnected lines from begin to end points, fastest method
         available for this purpose.
     */

-    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.

     */
     */

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

 
     /**
         Strokes along a path with the current pen.
 
     /**
         Strokes along a path with the current pen.


@@ -546,9 +671,162 @@ public:
         Translates the current transformation matrix.
     */
     virtual void Translate(wxDouble dx, wxDouble dy) = 0;
         Translates the current transformation matrix.
     */
     virtual void Translate(wxDouble dx, wxDouble dy) = 0;

+
+    /**
+        Redirects all rendering is done into a fully transparent temporary context
+    */
+    virtual void BeginLayer(wxDouble opacity) = 0;
+
+    /**
+        Composites back the drawings into the context with the opacity given at
+        the BeginLayer call
+    */
+    virtual void EndLayer() = 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 ;
+
+    /**
+        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;
+
+    /**
+        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


@@ -594,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.
     */


@@ -611,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


@@ -648,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