X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2e4d0e91bf92fb9b6f7c8382dcbcd763a89ca9f1..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/graphics.h diff --git a/interface/wx/graphics.h b/interface/wx/graphics.h index 10c2ea7485..96b3457508 100644 --- a/interface/wx/graphics.h +++ b/interface/wx/graphics.h @@ -2,8 +2,7 @@ // Name: graphics.h // Purpose: interface of various wxGraphics* classes // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -116,12 +115,12 @@ public: @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, - int fillStyle = wxODDEVEN_RULE) const; + wxPolygonFillMode fillStyle = wxODDEVEN_RULE) const; /** Gets the bounding box enclosing all points (possibly including control @@ -201,21 +200,38 @@ public: }; /** - 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 + 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 + wxGraphicsContext::SetCompositionMode(). The description give a short equation on how the values of a resulting pixel are calculated. @@ -224,6 +240,14 @@ enum wxAntialiasMode */ 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) */ @@ -237,9 +261,49 @@ enum wxCompositionMode 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 */ + 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 @@ -299,14 +363,14 @@ public: @see wxGraphicsRenderer::CreateContext() */ - static wxGraphicsContext* Create(const wxWindowDC& dc); + static wxGraphicsContext* Create(const wxWindowDC& windowDC); /** 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 @@ -315,7 +379,35 @@ public: @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. @@ -333,6 +425,35 @@ public: */ 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. */ @@ -344,6 +465,19 @@ public: 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 @@ -361,15 +495,25 @@ public: 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 @@ -380,6 +524,14 @@ public: 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. */ @@ -391,22 +543,43 @@ public: 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. */ - 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; + //@} /** Draws an ellipse. @@ -595,8 +768,10 @@ public: 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); @@ -611,39 +786,222 @@ public: 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 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; - /** + /** 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 @@ -669,6 +1027,41 @@ 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. */ @@ -677,17 +1070,35 @@ public: /** 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 */ - virtual wxGraphicsContext* CreateContext(const wxMemoryDC& dc) = 0 ; + virtual wxGraphicsContext* CreateContext(const wxMemoryDC& memoryDC) = 0 ; /** 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. @@ -707,7 +1118,7 @@ public: virtual wxGraphicsContext* CreateContextFromNativeWindow(void* window) = 0; /** - Creates a wxGraphicsContext that can be used for measuring texts only. + Creates a wxGraphicsContext that can be used for measuring texts only. No drawing commands are allowed. */ virtual wxGraphicsContext * CreateMeasuringContext() = 0; @@ -719,15 +1130,46 @@ public: 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, - const wxColour& c1, - const wxColour& c2) = 0; + const wxGraphicsGradientStops& stops) = 0; /** Creates a native affine transformation matrix from the passed in @@ -749,15 +1191,25 @@ public: 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; + + /** + 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 @@ -765,6 +1217,8 @@ public: on GTK we currently default to the cairo renderer. */ static wxGraphicsRenderer* GetDefaultRenderer(); + static wxGraphicsRenderer* GetCairoRenderer(); + }; @@ -887,7 +1341,10 @@ public: 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); @@ -920,3 +1377,10 @@ public: 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;