X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4feecbb929662fa002239fe7fc46d464b12f758e..fb5117ce44fad7b0a856e5ac1d82e53c389f3248:/interface/wx/dc.h diff --git a/interface/wx/dc.h b/interface/wx/dc.h index 1e4e08bc1a..4089c9e389 100644 --- a/interface/wx/dc.h +++ b/interface/wx/dc.h @@ -3,7 +3,7 @@ // Purpose: interface of wxDC // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -79,6 +79,28 @@ enum wxMappingMode wxMM_POINTS }; +/** + Simple collection of various font metrics. + + This object is returned by wxDC::GetFontMetrics(). + + @since 2.9.2 + + @library{wxcore} + @category{dc,gdi} + */ +struct wxFontMetrics +{ + /// Constructor initializes all fields to 0. + wxFontMetrics(); + + int height, ///< Total character height. + ascent, ///< Part of the height above the baseline. + descent, ///< Part of the height below the baseline. + internalLeading, ///< Intra-line spacing. + externalLeading, ///< Inter-line spacing. + averageWidth; ///< Average font width, a.k.a. "x-width". +}; /** @@ -91,7 +113,7 @@ enum wxMappingMode 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 @@ -121,7 +143,7 @@ enum wxMappingMode a device unit is a @e pixel. For a printer, the device unit is defined by the resolution of the printer (usually given in @c DPI: dot-per-inch). - All wxDC functions use instead @b logical units, unless where explicitely + All wxDC functions use instead @b logical units, unless where explicitly stated. Logical units are arbitrary units mapped to device units using the current mapping mode (see wxDC::SetMapMode). @@ -131,9 +153,25 @@ enum wxMappingMode @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} @@ -222,15 +260,21 @@ public: /** Draws an arc of a circle, centred on (@a xc, @a yc), with starting - point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is - used for the outline and the current brush for filling the shape. + point (@a xStart, @a yStart) and ending at (@a xEnd, @a yEnd). + The current pen is used for the outline and the current brush for + filling the shape. The arc is drawn in a counter-clockwise direction from the start point to the end point. */ - void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, + void DrawArc(wxCoord xStart, wxCoord yStart, wxCoord xEnd, wxCoord yEnd, wxCoord xc, wxCoord yc); + /** + @overload + */ + void DrawArc(const wxPoint& ptStart, const wxPoint& ptEnd, const wxPoint& centre); + /** Draw a bitmap on the device context at the specified point. If @a transparent is @true and the bitmap has a transparency mask, the @@ -246,6 +290,12 @@ public: void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, bool useMask = false); + /** + @overload + */ + void DrawBitmap(const wxBitmap &bmp, const wxPoint& pt, + bool useMask = false); + /** Draws a check mark inside the given rectangle. */ @@ -306,6 +356,12 @@ public: void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double start, double end); + /** + @overload + */ + void DrawEllipticArc(const wxPoint& pt, const wxSize& sz, + double sa, double ea); + /** Draw an icon on the display (does nothing if the device context is PostScript). This can be the simplest way of drawing bitmaps on a @@ -313,13 +369,18 @@ public: */ void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); + /** + @overload + */ + void DrawIcon(const wxIcon& icon, const wxPoint& pt); + /** Draw optional bitmap and the text into the given rectangle and aligns it as specified by alignment parameter; it also will emphasize the 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); @@ -339,6 +400,11 @@ public: */ void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); + /** + @overload + */ + void DrawLine(const wxPoint& pt1, const wxPoint& pt2); + /** 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. @@ -347,6 +413,10 @@ public: The wxPython version of this method accepts a Python list of wxPoint objects. @endWxPythonOnly + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0); @@ -359,6 +429,12 @@ public: 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 + of wxPoint objects. + @endWxPerlOnly */ void DrawLines(const wxPointList* points, wxCoord xoffset = 0, wxCoord yoffset = 0); @@ -369,6 +445,11 @@ public: */ void DrawPoint(wxCoord x, wxCoord y); + /** + @overload + */ + void DrawPoint(const wxPoint& pt); + /** Draws a filled polygon using an array of points of size @a n, adding the optional offset coordinate. The first and last points are @@ -379,6 +460,10 @@ public: The current pen is used for drawing the outline, and the current brush for filling the shape. Using a transparent brush suppresses filling. + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0, @@ -400,6 +485,12 @@ public: 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 + of wxPoint objects. + @endWxPerlOnly */ void DrawPolygon(const wxPointList* points, wxCoord xoffset = 0, wxCoord yoffset = 0, @@ -443,6 +534,16 @@ public: */ void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + /** + @overload + */ + void DrawRectangle(const wxPoint& pt, const wxSize& sz); + + /** + @overload + */ + void DrawRectangle(const wxRect& rect); + /** Draws the text rotated by @a angle degrees (positive angles are counterclockwise; the full angle is 360 degrees). @@ -457,6 +558,12 @@ public: void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, double angle); + /** + @overload + */ + void DrawRotatedText(const wxString& text, const wxPoint& point, + double angle); + /** Draws a rectangle with the given top left corner, and with the given size. The corners are quarter-circles using the given radius. The @@ -473,6 +580,17 @@ public: void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double radius); + /** + @overload + */ + void DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz, + double radius); + + /** + @overload + */ + void DrawRoundedRectangle(const wxRect& rect, double radius); + /** Draws a spline between all given points using the current pen. @@ -480,16 +598,32 @@ public: The wxPython version of this method accepts a Python list of wxPoint objects. @endWxPythonOnly + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ void DrawSpline(int n, wxPoint points[]); /** @overload + + + @beginWxPerlOnly + The wxPerl version of this method accepts + as its first parameter a reference to an array + of wxPoint objects. + @endWxPerlOnly */ void DrawSpline(const wxPointList* points); /** @overload + + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord x3, wxCoord y3); @@ -500,13 +634,23 @@ public: The coordinates refer to the top-left corner of the rectangle bounding the string. See GetTextExtent() for how to get the dimensions of a text - string, which can be used to position the text more precisely. + string, which can be used to position the text more precisely and + DrawLabel() if you need to align the string differently. + + Starting from wxWidgets 2.9.2 @a text parameter can be a multi-line + string, i.e. contain new line characters, and will be rendered + correctly. @note The current @ref GetLogicalFunction() "logical function" is ignored by this function. */ void DrawText(const wxString& text, wxCoord x, wxCoord y); + /** + @overload + */ + void DrawText(const wxString& text, const wxPoint& pt); + /** Fill the area specified by rect with a radial gradient, starting from @a initialColour at the centre of the circle and fading to @@ -563,10 +707,23 @@ 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); + /** + @overload + */ + bool FloodFill(const wxPoint& pt, const wxColour& col, + wxFloodFillStyle style = wxFLOOD_SURFACE); + /** Displays a cross hair using the current pen. This is a vertical and horizontal line the height and width of the window, centred on the @@ -574,6 +731,11 @@ public: */ void CrossHair(wxCoord x, wxCoord y); + /** + @overload + */ + void CrossHair(const wxPoint& pt); + //@} @@ -656,6 +818,21 @@ public: */ wxCoord GetCharWidth() const; + /** + Returns the various font characteristics. + + This method allows to retrieve some of the font characteristics not + returned by GetTextExtent(), notably internal leading and average + character width. + + Currently this method returns correct results only under wxMSW, in the + other ports the internal leading will always be 0 and the average + character width will be computed as the width of the character 'x'. + + @since 2.9.2 + */ + wxFontMetrics GetFontMetrics() const; + /** Gets the dimensions of the string using the currently selected font. @a string is the text string to measure, @e heightLine, if non @NULL, @@ -669,6 +846,12 @@ public: @note This function works with both single-line and multi-line strings. + @beginWxPerlOnly + In wxPerl this method is implemented as + GetMultiLineTextExtent(string, font = undef) returning a + 3-element list (width, height, line_height) + @endWxPerlOnly + @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() */ void GetMultiLineTextExtent(const wxString& string, wxCoord* w, @@ -684,6 +867,10 @@ public: @note This function works with both single-line and multi-line strings. + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly + @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() */ wxSize GetMultiLineTextExtent(const wxString& string) const; @@ -701,6 +888,11 @@ public: of integers. @endWxPythonOnly + @beginWxPerlOnly + In wxPerl this method only takes the @a text parameter and + returns the widths as a list of integers. + @endWxPerlOnly + @see GetMultiLineTextExtent(), GetTextExtent() */ bool GetPartialTextExtents(const wxString& text, @@ -729,6 +921,12 @@ public: 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, + descent, externalLeading) + @endWxPerlOnly + @see wxFont, SetFont(), GetPartialTextExtents(), GetMultiLineTextExtent() */ @@ -739,6 +937,11 @@ public: /** @overload + + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ wxSize GetTextExtent(const wxString& string) const; @@ -959,7 +1162,7 @@ public: This sequence of operations ensures that the source's transparent area need not be black, and logical functions are supported. @n @b Note: on Windows, blitting with masks can be speeded up - considerably by compiling wxWidgets with the wxUSE_DC_CACHE option + considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option enabled. You can also influence whether MaskBlt or the explicit mask blitting code above is used, by using wxSystemOptions and setting the @c no-maskblt option to 1. @@ -1030,7 +1233,7 @@ public: This sequence of operations ensures that the source's transparent area need not be black, and logical functions are supported. @n @b Note: on Windows, blitting with masks can be speeded up - considerably by compiling wxWidgets with the wxUSE_DC_CACHE option + considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option enabled. You can also influence whether MaskBlt or the explicit mask blitting code above is used, by using wxSystemOptions and setting the @c no-maskblt option to 1. @@ -1170,6 +1373,9 @@ public: @note Setting a pixel can be done using DrawPoint(). + @note This method shouldn't be used with wxPaintDC as accessing the DC + while drawing can result in unexpected results, notably in wxGTK. + @beginWxPythonOnly The wxColour value is returned and is not required as a parameter. @endWxPythonOnly @@ -1203,6 +1409,13 @@ public: - 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: + - GetSize(): returns a Wx::Size object. + - GetSizeWH(): returns a 2-element list (width, height). + @endWxPerlOnly */ void GetSize(wxCoord* width, wxCoord* height) const; @@ -1224,6 +1437,11 @@ public: /** Gets the current user scale factor. + @beginWxPerlOnly + In wxPerl this method takes no arguments and return a two + element array (x, y). + @endWxPerlOnly + @see SetUserScale() */ void GetUserScale(double* x, double* y) const; @@ -1302,6 +1520,66 @@ 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(); + + //@} + + + 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; + }; @@ -1344,7 +1622,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); //@} @@ -1437,6 +1715,16 @@ public: class wxDCTextColourChanger { public: + /** + Trivial constructor not changing anything. + + This constructor is useful if you don't know beforehand if the colour + needs to be changed or not. It simply creates the object which won't do + anything in its destructor unless Set() is called -- in which case it + would reset the previous colour. + */ + wxDCTextColourChanger(wxDC& dc); + /** Sets @a col on the given @a dc, storing the old one. @@ -1447,6 +1735,17 @@ public: */ wxDCTextColourChanger(wxDC& dc, const wxColour& col); + /** + Set the colour to use. + + This method is meant to be called once only and only on the objects + created with the constructor overload not taking wxColour argument and + has the same effect as the other constructor, i.e. sets the colour to + the given @a col and ensures that the old value is restored when this + object is destroyed. + */ + void Set(const wxColour& col); + /** Restores the colour originally selected in the DC passed to the ctor. */ @@ -1472,6 +1771,18 @@ public: class wxDCFontChanger { public: + /** + Trivial constructor not changing anything. + + This constructor is useful if you don't know beforehand if the font + needs to be changed or not. It simply creates the object which won't do + anything in its destructor unless Set() is called -- in which case it + would reset the previous font. + + @since 2.9.1 + */ + wxDCFontChanger(wxDC& dc); + /** Sets @a font on the given @a dc, storing the old one. @@ -1483,7 +1794,18 @@ public: wxDCFontChanger(wxDC& dc, const wxFont& font); /** - Restores the colour originally selected in the DC passed to the ctor. + Set the font to use. + + This method is meant to be called once only and only on the objects + created with the constructor overload not taking wxColour argument and + has the same effect as the other constructor, i.e. sets the font to + the given @a font and ensures that the old value is restored when this + object is destroyed. + */ + void Set(const wxFont& font); + + /** + Restores the font originally selected in the DC passed to the ctor. */ ~wxDCFontChanger(); };