X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/403695b3236ce0ccca5ba7493736926566c9addc..487f6627541e49810f6fb48947a7226717fe17a8:/interface/wx/dc.h diff --git a/interface/wx/dc.h b/interface/wx/dc.h index 32b986bd1e..54b0053602 100644 --- a/interface/wx/dc.h +++ b/interface/wx/dc.h @@ -163,6 +163,17 @@ struct wxFontMetrics 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} @category{dc,gdi} @@ -369,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); @@ -398,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 @@ -414,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 @@ -470,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 @@ -507,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, @@ -550,7 +542,7 @@ public: /** @overload */ - void DrawRotatedText(const wxString& text, const wxPoint&, + void DrawRotatedText(const wxString& text, const wxPoint& point, double angle); /** @@ -583,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 @@ -696,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); @@ -704,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 @@ -735,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; @@ -865,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. @@ -896,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, @@ -1100,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. @@ -1167,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. @@ -1230,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 @@ -1355,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; @@ -1382,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: @@ -1499,6 +1481,82 @@ 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(); + + //@} + + + /** + 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; + + + 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; + }; @@ -1506,10 +1564,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) @@ -1526,6 +1586,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} @@ -1541,7 +1607,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); //@}