X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ac55e6b01ed16aa52eae867bc4fe3fb864c6c4f6..0c3e2a5baacbb9f9a43f0887521061c9aa0239d4:/interface/wx/dc.h diff --git a/interface/wx/dc.h b/interface/wx/dc.h index da232bc282..582474020b 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 ///////////////////////////////////////////////////////////////////////////// @@ -222,15 +222,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 +252,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 +318,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,6 +331,11 @@ 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 @@ -339,6 +362,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 +375,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 +391,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 +407,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 +422,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 +447,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 +496,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 +520,12 @@ public: void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, double angle); + /** + @overload + */ + void DrawRotatedText(const wxString& text, const wxPoint&, + 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 +542,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 +560,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 +596,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 @@ -567,6 +673,12 @@ public: bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, wxFloodFillStyle style = wxFLOOD_SURFACE); + /** + @overload + */ + bool FloodFill(const wxPoint& pt, const wxColour& col, + int 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 +686,11 @@ public: */ void CrossHair(wxCoord x, wxCoord y); + /** + @overload + */ + void CrossHair(const wxPoint& pt); + //@} @@ -602,13 +719,20 @@ public: /** Sets the clipping region for this device context to the intersection of the given region described by the parameters of this method and the - previously set clipping region. You should call DestroyClippingRegion() - if you want to set the clipping region exactly to the region specified. + previously set clipping region. The clipping region is an area to which drawing is restricted. Possible uses for the clipping region are for clipping text or for speeding up window redraws when only a known area of the screen is damaged. + Notice that you need to call DestroyClippingRegion() if you want to set + the clipping region exactly to the region specified. + + Also note that if the clipping region is empty, any previously set + clipping region is destroyed, i.e. it is equivalent to calling + DestroyClippingRegion(), and not to clipping out all drawing on the DC + as might be expected. + @see DestroyClippingRegion(), wxRegion */ void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); @@ -662,6 +786,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, @@ -677,6 +807,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; @@ -694,6 +828,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, @@ -722,6 +861,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() */ @@ -732,6 +877,11 @@ public: /** @overload + + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ wxSize GetTextExtent(const wxString& string) const; @@ -952,7 +1102,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. @@ -1023,7 +1173,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. @@ -1115,6 +1265,19 @@ public: //@} + /** + Copy attributes from another DC. + + The copied attributes currently are: + - Font + - Text foreground and background colours + - Background brush + - Layout direction + + @param dc + A valid (i.e. its IsOk() must return @true) source device context. + */ + void CopyAttributes(const wxDC& dc); /** Returns the depth (number of bits/pixel) of this DC. @@ -1183,6 +1346,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; @@ -1204,6 +1374,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; @@ -1417,6 +1592,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. @@ -1427,6 +1612,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. */ @@ -1452,6 +1648,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. @@ -1463,7 +1671,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(); };