// Purpose: interface of various wxGraphics* classes
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
{
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);
- /**
- 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);
+ //@}
/**
Appends a an arc to two tangents connecting (current) to (@a x1,@a y1)
};
/**
- Anti-aliasing modes used by wxGraphicsContext::SetAntialisingMode
+ Anti-aliasing modes used by wxGraphicsContext::SetAntialiasMode().
*/
enum wxAntialiasMode
{
/** No anti-aliasing */
- wxANTIALIAS_NONE,
-
+ wxANTIALIAS_NONE,
+
/** The default anti-aliasing */
wxANTIALIAS_DEFAULT,
};
/**
- Compositing is done using Porter-Duff compositions
+ Compositing is done using Porter-Duff compositions
(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.
- @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
{
-
- /** 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 */
+ 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 */
};
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
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 originats 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
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;
- /**
- 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;
- /**
+ /**
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 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
*/
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 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,
- const wxColour& c1,
- const wxColour& c2) = 0;
+ const wxGraphicsGradientStops& stops) = 0;
/**
Creates a native affine transformation matrix from the passed in
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,
- 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
projects / wxWidgets.git / blobdiff