X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4c51a665c649f7579fb39e62070cef4f66b3210d..ca282726be518ce2f214b890dbaafce736f14e36:/interface/wx/dc.h diff --git a/interface/wx/dc.h b/interface/wx/dc.h index d3e8875f60..d496f73703 100644 --- a/interface/wx/dc.h +++ b/interface/wx/dc.h @@ -113,7 +113,7 @@ struct wxFontMetrics wxWidgets offers an alternative drawing API based on the modern drawing backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer and related classes. There is also a wxGCDC linking the APIs by offering - the wxDC API ontop of a wxGraphicsContext. + the wxDC API on top of a wxGraphicsContext. wxDC is an abstract base class and cannot be created directly. Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or @@ -153,9 +153,25 @@ struct wxFontMetrics @section dc_alpha_support Support for Transparency / Alpha Channel - On Mac OS X colours with alpha channel are supported. Instances of wxPen - or wxBrush that are built from wxColour use the colour's alpha values - when stroking or filling. + In general wxDC methods don't support alpha transparency and the alpha + component of wxColour is simply ignored and you need to use wxGraphicsContext + for full transparency support. There are, however, a few exceptions: first, + under Mac OS X colours with alpha channel are supported in all the normal + wxDC-derived classes as they use wxGraphicsContext internally. Second, + under all platforms wxSVGFileDC also fully supports alpha channel. In both + of these cases the instances of wxPen or wxBrush that are built from + wxColour use the colour's alpha values when stroking or filling. + + + @section Support for Transformation Matrix + + On some platforms (currently only under MSW and only on Windows NT, i.e. + not Windows 9x/ME, systems) wxDC has support for applying an arbitrary + affine transformation matrix to its coordinate system. Call + CanUseTransformMatrix() to check if this support is available and then call + SetTransformMatrix() if it is. If the transformation matrix is not + supported, SetTransformMatrix() always simply returns false and doesn't do + anything. @library{wxcore} @@ -364,7 +380,7 @@ public: character with the given index if it is != -1 and return the bounding rectangle if required. */ - void DrawLabel(const wxString& text, const wxBitmap& image, + void DrawLabel(const wxString& text, const wxBitmap& bitmap, const wxRect& rect, int alignment = wxALIGN_LEFT | wxALIGN_TOP, int indexAccel = -1, wxRect* rectBounding = NULL); @@ -393,11 +409,6 @@ public: Draws lines using an array of points of size @a n adding the optional offset coordinate. The current pen is used for drawing the lines. - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly - @beginWxPerlOnly Not supported by wxPerl. @endWxPerlOnly @@ -409,11 +420,6 @@ public: coordinate. The programmer is responsible for deleting the list of points. - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly - @beginWxPerlOnly The wxPerl version of this method accepts as its first parameter a reference to an array @@ -465,11 +471,6 @@ public: The programmer is responsible for deleting the list of points. - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly - @beginWxPerlOnly The wxPerl version of this method accepts as its first parameter a reference to an array @@ -502,10 +503,6 @@ public: call to DrawPolyPolygon() must be closed. Unlike polygons created by the DrawPolygon() member function, the polygons created by this method are not closed automatically. - - @beginWxPythonOnly - Not implemented yet. - @endWxPythonOnly */ void DrawPolyPolygon(int n, int count[], wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0, @@ -545,7 +542,7 @@ public: /** @overload */ - void DrawRotatedText(const wxString& text, const wxPoint&, + void DrawRotatedText(const wxString& text, const wxPoint& point, double angle); /** @@ -578,11 +575,6 @@ public: /** Draws a spline between all given points using the current pen. - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly - @beginWxPerlOnly Not supported by wxPerl. @endWxPerlOnly @@ -691,6 +683,13 @@ public: @note The present implementation for non-Windows platforms may fail to find colour borders if the pixels do not match the colour exactly. However the function will still return @true. + + @note This method shouldn't be used with wxPaintDC under non-Windows + platforms as it uses GetPixel() internally and this may give + wrong results, notably in wxGTK. If you need to flood fill + wxPaintDC, create a temporary wxMemoryDC, flood fill it and then + blit it to, or draw as a bitmap on, wxPaintDC. See the example of + doing this in the drawing sample and wxBufferedPaintDC class. */ bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, wxFloodFillStyle style = wxFLOOD_SURFACE); @@ -699,7 +698,7 @@ public: @overload */ bool FloodFill(const wxPoint& pt, const wxColour& col, - int style = wxFLOOD_SURFACE); + wxFloodFillStyle style = wxFLOOD_SURFACE); /** Displays a cross hair using the current pen. This is a vertical and @@ -730,11 +729,6 @@ public: /** Gets the rectangle surrounding the current clipping region. - - @beginWxPythonOnly - No arguments are required and the four values defining the rectangle - are returned as a tuple. - @endWxPythonOnly */ void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const; @@ -860,11 +854,6 @@ public: function that is faster or more accurate than the generic implementation then it should be used instead. - @beginWxPythonOnly - This method only takes the @a text parameter and returns a Python list - of integers. - @endWxPythonOnly - @beginWxPerlOnly In wxPerl this method only takes the @a text parameter and returns the widths as a list of integers. @@ -891,13 +880,6 @@ public: @note This function only works with single-line strings. - @beginWxPythonOnly - The following methods are implemented in wxPython: - - GetTextExtent(string) - Returns a 2-tuple, (width, height). - - GetFullTextExtent(string, font=NULL) - - Returns a 4-tuple, (width, height, descent, externalLeading). - @endWxPythonOnly - @beginWxPerlOnly In wxPerl this method is implemented as GetTextExtent(string, font = undef) returning a 4-element list (width, height, @@ -1095,10 +1077,17 @@ public: //@{ /** - Copy from a source DC to this DC, specifying the destination - coordinates, size of area to copy, source DC, source coordinates, - logical function, whether to use a bitmap mask, and mask source - position. + Copy from a source DC to this DC. + + With this method you can specify the destination coordinates and the + size of area to copy which will be the same for both the source and + target DCs. If you need to apply scaling while copying, use + StretchBlit(). + + Notice that source DC coordinates @a xsrc and @a ysrc are interpreted + using the current source DC coordinate system, i.e. the scale, origin + position and axis directions are taken into account when transforming + them to physical (pixel) coordinates. @param xdest Destination device context x position. @@ -1162,10 +1151,18 @@ public: wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord); /** - Copy from a source DC to this DC, specifying the destination - coordinates, destination size, source DC, source coordinates, size of - source area to copy, logical function, whether to use a bitmap mask, - and mask source position. + Copy from a source DC to this DC possibly changing the scale. + + Unlike Blit(), this method allows to specify different source and + destination region sizes, meaning that it can stretch or shrink it + while copying. The same can be achieved by changing the scale of the + source or target DC but calling this method is simpler and can also be + more efficient if the platform provides a native implementation of it. + + The meaning of its other parameters is the same as with Blit(), in + particular all source coordinates are interpreted using the source DC + coordinate system, i.e. are affected by its scale, origin translation + and axis direction. @param xdest Destination device context x position. @@ -1225,8 +1222,6 @@ public: There is partial support for Blit() in wxPostScriptDC, under X. - StretchBlit() is only implemented under wxMAC and wxMSW. - See wxMemoryDC for typical usage. @since 2.9.0 @@ -1350,9 +1345,8 @@ public: @note Setting a pixel can be done using DrawPoint(). - @beginWxPythonOnly - The wxColour value is returned and is not required as a parameter. - @endWxPythonOnly + @note This method shouldn't be used with wxPaintDC as accessing the DC + while drawing can result in unexpected results, notably in wxGTK. */ bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const; @@ -1377,13 +1371,6 @@ public: dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); @endcode - @beginWxPythonOnly - In place of a single overloaded method name, wxPython implements the - following methods: - - GetSize() - Returns a wxSize. - - GetSizeWH() - Returns a 2-tuple (width, height). - @endWxPythonOnly - @beginWxPerlOnly In wxPerl there are two methods instead of a single overloaded method: @@ -1494,6 +1481,105 @@ public: 'zooming'. */ void SetUserScale(double xScale, double yScale); + + + /** + @name Transformation matrix + + See the notes about the availability of these functions in the class + documentation. + */ + //@{ + + /** + Check if the use of transformation matrix is supported by the current + system. + + Currently this function always returns @false for non-MSW platforms and + may return @false for old (Windows 9x/ME) Windows systems. Normally + support for the transformation matrix is always available in any + relatively recent Windows versions. + + @since 2.9.2 + */ + bool CanUseTransformMatrix() const; + + /** + Set the transformation matrix. + + If transformation matrix is supported on the current system, the + specified @a matrix will be used to transform between wxDC and physical + coordinates. Otherwise the function returns @false and doesn't change + the coordinate mapping. + + @since 2.9.2 + */ + bool SetTransformMatrix(const wxAffineMatrix2D& matrix); + + /** + Return the transformation matrix used by this device context. + + By default the transformation matrix is the identity matrix. + + @since 2.9.2 + */ + wxAffineMatrix2D GetTransformMatrix() const; + + /** + Revert the transformation matrix to identity matrix. + + @since 2.9.2 + */ + void ResetTransformMatrix(); + + //@} + + + /** + @name query capabilities + */ + //@{ + + /** + Does the DC support drawing bitmaps? + */ + bool CanDrawBitmap() const; + + /** + Does the DC supoprt calculating the size required to draw text? + */ + bool CanGetTextExtent() const; + + //@} + + /** + Returns a value that can be used as a handle to the native drawing + context, if this wxDC has something that could be thought of in that + way. (Not all of them do.) + + For example, on Windows the return value is an HDC, on OSX it is a + CGContextRef and on wxGTK it will be a GdkDrawable. If the DC is a + wxGCDC then the return value will be the value returned from + wxGraphicsContext::GetNativeContext. A value of NULL is returned if + the DC does not have anything that fits the handle concept. + + @since 2.9.5 + */ + void* GetHandle() const; + + + /** + If supported by the platform and the type of DC, fetch the contents of the DC, or a subset of it, as a bitmap. + */ + wxBitmap GetAsBitmap(const wxRect *subrect = NULL) const; + + + void SetLogicalScale(double x, double y); + void GetLogicalScale(double *x, double *y) const; + void SetLogicalOrigin(wxCoord x, wxCoord y); + void GetLogicalOrigin(wxCoord *x, wxCoord *y) const; + wxPoint GetLogicalOrigin() const; + }; @@ -1501,10 +1587,12 @@ public: /** @class wxDCClipper - wxDCClipper is a small helper class for setting a clipping region on a wxDC - and unsetting it automatically. An object of wxDCClipper class is typically - created on the stack so that it is automatically destroyed when the object - goes out of scope. A typical usage example: + wxDCClipper is a helper class for setting a clipping region on a wxDC + during its lifetime. + + An object of wxDCClipper class is typically created on the stack so that it + is automatically destroyed when the object goes out of scope. A typical + usage example: @code void MyFunction(wxDC& dc) @@ -1521,6 +1609,12 @@ public: } @endcode + @note Unlike other similar classes such as wxDCFontChanger, wxDCClipper + currently doesn't restore the previously active clipping region when it + is destroyed but simply resets clipping on the associated wxDC. This + may be changed in the future wxWidgets versions but has to be taken + into account explicitly in the current one. + @library{wxcore} @category{gdi} @@ -1536,7 +1630,7 @@ public: The clipping region is automatically unset when this object is destroyed. */ - wxDCClipper(wxDC& dc, const wxRegion& r); + wxDCClipper(wxDC& dc, const wxRegion& region); wxDCClipper(wxDC& dc, const wxRect& rect); wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h); //@}