X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1058f652031c9b99daa7c701f09f16c3af7159c1..fb5117ce44fad7b0a856e5ac1d82e53c389f3248:/interface/wx/dc.h diff --git a/interface/wx/dc.h b/interface/wx/dc.h index 131277e2bb..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. @@ -379,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 @@ -463,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). @@ -477,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 @@ -493,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. @@ -536,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 @@ -599,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 @@ -610,6 +731,11 @@ public: */ void CrossHair(wxCoord x, wxCoord y); + /** + @overload + */ + void CrossHair(const wxPoint& pt); + //@} @@ -692,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, @@ -1021,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. @@ -1092,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. @@ -1232,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 @@ -1376,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; + }; @@ -1418,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); //@}