1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: dc.h 3 // Purpose: interface of wxDC 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 9 /** 10 Logical raster operations which can be used with wxDC::SetLogicalFunction 11 and some other wxDC functions (e.g. wxDC::Blit and wxDC::StretchBlit). 12 13 The description of the values below refer to how a generic @e src source pixel 14 and the corresponding @e dst destination pixel gets combined together to produce 15 the final pixel. E.g. @c wxCLEAR and @c wxSET completely ignore the source 16 and the destination pixel and always put zeroes or ones in the final surface. 17 18 Note that not all modes are supported under all platforms. Notably wxGTK3 19 and wxMac only support the following modes: 20 - wxCOPY 21 - wxOR 22 - wxNO_OP 23 - wxCLEAR 24 - wxXOR 25 and, in particular, do @em not support the commonly used @c wxINVERT. 26 */ 27 enum wxRasterOperationMode 28 { 29 wxCLEAR, //!< 0 30 wxXOR, //!< @e src XOR @e dst 31 wxINVERT, //!< NOT @e dst 32 wxOR_REVERSE, //!< @e src OR (NOT @e dst) 33 wxAND_REVERSE, //!< @e src AND (NOT @e dst) 34 wxCOPY, //!< @e src 35 wxAND, //!< @e src AND @e dst 36 wxAND_INVERT, //!< (NOT @e src) AND @e dst 37 wxNO_OP, //!< @e dst 38 wxNOR, //!< (NOT @e src) AND (NOT @e dst) 39 wxEQUIV, //!< (NOT @e src) XOR @e dst 40 wxSRC_INVERT, //!< (NOT @e src) 41 wxOR_INVERT, //!< (NOT @e src) OR @e dst 42 wxNAND, //!< (NOT @e src) OR (NOT @e dst) 43 wxOR, //!< @e src OR @e dst 44 wxSET //!< 1 45 }; 46 47 /** 48 Flood styles used by wxDC::FloodFill. 49 */ 50 enum wxFloodFillStyle 51 { 52 /** The flooding occurs until a colour other than the given colour is encountered. */ 53 wxFLOOD_SURFACE = 1, 54 55 /** The area to be flooded is bounded by the given colour. */ 56 wxFLOOD_BORDER 57 }; 58 59 /** 60 The mapping used to transform @e logical units to @e device units. 61 See wxDC::SetMapMode. 62 */ 63 enum wxMappingMode 64 { 65 /** 66 Each logical unit is 1 device pixel. 67 This is the default mapping mode for all wxDC-derived classes. 68 */ 69 wxMM_TEXT = 1, 70 71 /** Each logical unit is 1 millimeter. */ 72 wxMM_METRIC, 73 74 /** Each logical unit is 1/10 of a millimeter. */ 75 wxMM_LOMETRIC, 76 77 /** 78 Each logical unit is 1/20 of a @e "printer point", or 1/1440 of an inch 79 (also known as "twip"). Equivalent to about 17.64 micrometers. 80 */ 81 wxMM_TWIPS, 82 83 /** 84 Each logical unit is a @e "printer point" i.e.\ 1/72 of an inch. 85 Equivalent to about 353 micrometers. 86 */ 87 wxMM_POINTS 88 }; 89 90 /** 91 Simple collection of various font metrics. 92 93 This object is returned by wxDC::GetFontMetrics(). 94 95 @since 2.9.2 96 97 @library{wxcore} 98 @category{dc,gdi} 99 */ 100 struct wxFontMetrics 101 { 102 /// Constructor initializes all fields to 0. 103 wxFontMetrics(); 104 105 int height, ///< Total character height. 106 ascent, ///< Part of the height above the baseline. 107 descent, ///< Part of the height below the baseline. 108 internalLeading, ///< Intra-line spacing. 109 externalLeading, ///< Inter-line spacing. 110 averageWidth; ///< Average font width, a.k.a. "x-width". 111 }; 112 113 114 /** 115 @class wxDC 116 117 A wxDC is a @e "device context" onto which graphics and text can be drawn. 118 It is intended to represent different output devices and offers a common 119 abstract API for drawing on any of them. 120 121 wxWidgets offers an alternative drawing API based on the modern drawing 122 backends GDI+, CoreGraphics, Cairo and Direct2D. See wxGraphicsContext, 123 wxGraphicsRenderer and related classes. There is also a wxGCDC linking 124 the APIs by offering the wxDC API on top of a wxGraphicsContext. 125 126 wxDC is an abstract base class and cannot be created directly. 127 Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or 128 wxPrinterDC. Notice that device contexts which are associated with windows 129 (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours 130 by default (starting with wxWidgets 2.9.0) but the other device context 131 classes use system-default values so you always must set the appropriate 132 fonts and colours before using them. 133 134 In addition to the versions of the methods documented below, there 135 are also versions which accept single wxPoint parameter instead 136 of the two wxCoord ones or wxPoint and wxSize instead of the four 137 wxCoord parameters. 138 139 Beginning with wxWidgets 2.9.0 the entire wxDC code has been 140 reorganized. All platform dependent code (actually all drawing code) 141 has been moved into backend classes which derive from a common 142 wxDCImpl class. The user-visible classes such as wxClientDC and 143 wxPaintDC merely forward all calls to the backend implementation. 144 145 146 @section dc_units Device and logical units 147 148 In the wxDC context there is a distinction between @e logical units and @e device units. 149 150 @b Device units are the units native to the particular device; e.g. for a screen, 151 a device unit is a @e pixel. For a printer, the device unit is defined by the 152 resolution of the printer (usually given in @c DPI: dot-per-inch). 153 154 All wxDC functions use instead @b logical units, unless where explicitly 155 stated. Logical units are arbitrary units mapped to device units using 156 the current mapping mode (see wxDC::SetMapMode). 157 158 This mechanism allows reusing the same code which prints on e.g. a window 159 on the screen to print on e.g. a paper. 160 161 162 @section dc_alpha_support Support for Transparency / Alpha Channel 163 164 In general wxDC methods don't support alpha transparency and the alpha 165 component of wxColour is simply ignored and you need to use wxGraphicsContext 166 for full transparency support. There are, however, a few exceptions: first, 167 under macOS and GTK+ 3 colours with alpha channel are supported in all the normal 168 wxDC-derived classes as they use wxGraphicsContext internally. Second, 169 under all platforms wxSVGFileDC also fully supports alpha channel. In both 170 of these cases the instances of wxPen or wxBrush that are built from 171 wxColour use the colour's alpha values when stroking or filling. 172 173 174 @section dc_transform_support Support for Transformation Matrix 175 176 On some platforms (currently under MSW, GTK+ 3, macOS) wxDC has support for 177 applying an arbitrary affine transformation matrix to its coordinate system 178 (since 3.1.1 this feature is also supported by wxGCDC in all ports). 179 Call CanUseTransformMatrix() to check if this support is available and then 180 call SetTransformMatrix() if it is. If the transformation matrix is not 181 supported, SetTransformMatrix() always simply returns @c false and doesn't 182 do anything. 183 184 This feature is only available when @c wxUSE_DC_TRANSFORM_MATRIX build 185 option is enabled. 186 187 188 @library{wxcore} 189 @category{dc,gdi} 190 191 @see @ref overview_dc, wxGraphicsContext, wxDCFontChanger, wxDCTextColourChanger, 192 wxDCPenChanger, wxDCBrushChanger, wxDCClipper 193 194 @todo Precise definition of default/initial state. 195 @todo Pixelwise definition of operations (e.g. last point of a line not 196 drawn). 197 */ 198 class wxDC : public wxObject 199 { 200 public: 201 /** 202 @name Coordinate conversion functions 203 */ 204 //@{ 205 206 /** 207 Convert @e device X coordinate to logical coordinate, using the current 208 mapping mode, user scale factor, device origin and axis orientation. 209 210 @note Affine transformation applied to the coordinate system 211 with SetTransformMatrix() is not taken into account. 212 */ 213 wxCoord DeviceToLogicalX(wxCoord x) const; 214 215 /** 216 Convert @e device X coordinate to relative logical coordinate, using the 217 current mapping mode and user scale factor but ignoring the 218 axis orientation. Use this for converting a horizontal distance like 219 for example a width. 220 221 @note Affine transformation applied to the coordinate system 222 with SetTransformMatrix() is not taken into account. 223 */ 224 wxCoord DeviceToLogicalXRel(wxCoord x) const; 225 226 /** 227 Converts @e device Y coordinate to logical coordinate, using the current 228 mapping mode, user scale factor, device origin and axis orientation. 229 230 @note Affine transformation applied to the coordinate system 231 with SetTransformMatrix() is not taken into account. 232 */ 233 wxCoord DeviceToLogicalY(wxCoord y) const; 234 235 /** 236 Convert @e device Y coordinate to relative logical coordinate, using the 237 current mapping mode and user scale factor but ignoring the 238 axis orientation. Use this for converting a vertical distance like 239 for example a height. 240 241 @note Affine transformation applied to the coordinate system 242 with SetTransformMatrix() is not taken into account. 243 */ 244 wxCoord DeviceToLogicalYRel(wxCoord y) const; 245 246 /** 247 Converts logical X coordinate to device coordinate, using the current 248 mapping mode, user scale factor, device origin and axis orientation. 249 250 @note Affine transformation applied to the coordinate system 251 with SetTransformMatrix() is not taken into account. 252 */ 253 wxCoord LogicalToDeviceX(wxCoord x) const; 254 255 /** 256 Converts logical X coordinate to relative device coordinate, using the 257 current mapping mode and user scale factor but ignoring the 258 axis orientation. Use this for converting a horizontal distance like 259 for example a width. 260 261 @note Affine transformation applied to the coordinate system 262 with SetTransformMatrix() is not taken into account. 263 */ 264 wxCoord LogicalToDeviceXRel(wxCoord x) const; 265 266 /** 267 Converts logical Y coordinate to device coordinate, using the current 268 mapping mode, user scale factor, device origin and axis orientation. 269 270 @note Affine transformation applied to the coordinate system 271 with SetTransformMatrix() is not taken into account. 272 */ 273 wxCoord LogicalToDeviceY(wxCoord y) const; 274 275 /** 276 Converts logical Y coordinate to relative device coordinate, using the 277 current mapping mode and user scale factor but ignoring the 278 axis orientation. Use this for converting a vertical distance like 279 for example a height. 280 281 @note Affine transformation applied to the coordinate system 282 with SetTransformMatrix() is not taken into account. 283 */ 284 wxCoord LogicalToDeviceYRel(wxCoord y) const; 285 286 /** 287 Converts device (@a x, @a y) coordinates to logical coordinates 288 taking into account all applied transformations like the current 289 mapping mode, scale factors, device origin, axes orientation, 290 affine transformation. 291 292 @since 3.1.5 293 */ 294 wxPoint DeviceToLogical(wxCoord x, wxCoord y) const; 295 296 /** 297 @overload 298 299 @since 3.1.5 300 */ 301 wxPoint DeviceToLogical(const wxPoint& pt) const; 302 303 /** 304 Converts device @a x, @a y coordinates to relative logical coordinates 305 taking into account all applied transformations like the current 306 mapping mode, scale factors, affine transformation. 307 Use this for converting distances like e.g. width and height. 308 309 @since 3.1.5 310 */ 311 wxSize DeviceToLogicalRel(int x, int y) const; 312 313 /** 314 @overload 315 316 @since 3.1.5 317 */ 318 wxSize DeviceToLogicalRel(const wxSize& dim) const; 319 320 /** 321 Converts logical (@a x, @a y) coordinates to device coordinates 322 taking into account all applied transformations like the current 323 mapping mode, scale factors, device origin, axes orientation, 324 affine transformation. 325 326 @since 3.1.5 327 */ 328 wxPoint LogicalToDevice(wxCoord x, wxCoord y) const; 329 330 /** 331 @overload 332 333 @since 3.1.5 334 */ 335 wxPoint LogicalToDevice(const wxPoint& pt) const; 336 337 /** 338 Converts logical @a x, @a y coordinates to relative device coordinates 339 taking into account all applied transformations like the current 340 mapping mode, scale factors, affine transformation. 341 Use this for converting distances like e.g. width and height. 342 343 @since 3.1.5 344 */ 345 wxSize LogicalToDeviceRel(int x, int y) const; 346 347 /** 348 @overload 349 350 @since 3.1.5 351 */ 352 wxSize LogicalToDeviceRel(const wxSize& dim) const; 353 354 //@} 355 356 357 358 /** 359 @name Drawing functions 360 */ 361 //@{ 362 363 /** 364 Clears the device context using the current background brush. 365 366 Note that SetBackground() method must be used to set the brush used by 367 Clear(), the brush used for filling the shapes set by SetBrush() is 368 ignored by it. 369 370 If no background brush was set, solid white brush is used to clear the 371 device context. 372 */ 373 void Clear(); 374 375 /** 376 Draws an arc from the given start to the given end point. 377 378 @note DrawEllipticArc() has more clear semantics and it is recommended 379 to use it instead of this function. 380 381 The arc drawn is an arc of the circle centered at (@a xc, @a yc). Its 382 start point is (@a xStart, @a yStart) whereas its end point is the 383 point of intersection of the line passing by (@a xc, @a yc) and (@a 384 xEnd, @a yEnd) with the circle passing by (@a xStart, @a yStart). 385 386 The arc is drawn in a counter-clockwise direction between the start and 387 the end points. 388 389 The current pen is used for the outline and the current brush for 390 filling the shape. Notice that unless the brush is transparent, the 391 lines connecting the centre of the circle to the end points of the arc 392 are drawn as well. 393 */ 394 void DrawArc(wxCoord xStart, wxCoord yStart, wxCoord xEnd, wxCoord yEnd, 395 wxCoord xc, wxCoord yc); 396 397 /** 398 @overload 399 */ 400 void DrawArc(const wxPoint& ptStart, const wxPoint& ptEnd, const wxPoint& centre); 401 402 /** 403 Draw a bitmap on the device context at the specified point. If 404 @a useMask is @true and the bitmap has a transparency mask, the 405 bitmap will be drawn transparently. 406 407 When drawing a mono-bitmap, the current text foreground colour will be 408 used to draw the foreground of the bitmap (all bits set to 1), and the 409 current text background colour to draw the background (all bits set to 410 0). 411 412 @see SetTextForeground(), SetTextBackground(), wxMemoryDC 413 */ 414 void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, 415 bool useMask = false); 416 417 /** 418 @overload 419 */ 420 void DrawBitmap(const wxBitmap &bmp, const wxPoint& pt, 421 bool useMask = false); 422 423 /** 424 Draws a check mark inside the given rectangle. 425 */ 426 void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); 427 428 /** 429 @overload 430 */ 431 void DrawCheckMark(const wxRect& rect); 432 433 /** 434 Draws a circle with the given centre and radius. 435 436 @see DrawEllipse() 437 */ 438 void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); 439 440 /** 441 @overload 442 */ 443 void DrawCircle(const wxPoint& pt, wxCoord radius); 444 445 /** 446 Draws an ellipse contained in the rectangle specified either with the 447 given top left corner and the given size or directly. The current pen 448 is used for the outline and the current brush for filling the shape. 449 450 @see DrawCircle() 451 */ 452 void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); 453 454 /** 455 @overload 456 */ 457 void DrawEllipse(const wxPoint& pt, const wxSize& size); 458 459 /** 460 @overload 461 */ 462 void DrawEllipse(const wxRect& rect); 463 464 /** 465 Draws an arc of an ellipse. The current pen is used for drawing the arc 466 and the current brush is used for drawing the pie. 467 468 @a x and @a y specify the x and y coordinates of the upper-left corner 469 of the rectangle that contains the ellipse. 470 471 @a width and @a height specify the width and height of the rectangle 472 that contains the ellipse. 473 474 @a start and @a end specify the end points of the arc relative to 475 the three-o'clock position from the center of the rectangle. Angles are 476 specified in degrees with 0 degree angle corresponding to the positive 477 horizontal axis (3 o'clock) direction. 478 479 Independently of whether @a start is greater than or less than @a end, 480 the arc is drawn in the counter-clockwise direction. Also, if @a start 481 is equal to @e end, a complete ellipse is drawn. 482 483 Notice that unlike DrawArc(), this function does not draw the lines to 484 the arc ends, even when using non-transparent brush. 485 */ 486 void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height, 487 double start, double end); 488 489 /** 490 @overload 491 */ 492 void DrawEllipticArc(const wxPoint& pt, const wxSize& sz, 493 double sa, double ea); 494 495 /** 496 Draw an icon on the display (does nothing if the device context is 497 PostScript). This can be the simplest way of drawing bitmaps on a 498 window. 499 */ 500 void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); 501 502 /** 503 @overload 504 */ 505 void DrawIcon(const wxIcon& icon, const wxPoint& pt); 506 507 /** 508 Draw optional bitmap and the text into the given rectangle and aligns 509 it as specified by alignment parameter; it also will emphasize the 510 character with the given index if it is != -1 and return the bounding 511 rectangle if required. 512 */ 513 void DrawLabel(const wxString& text, const wxBitmap& bitmap, 514 const wxRect& rect, 515 int alignment = wxALIGN_LEFT | wxALIGN_TOP, 516 int indexAccel = -1, wxRect* rectBounding = NULL); 517 518 /** 519 @overload 520 */ 521 void DrawLabel(const wxString& text, const wxRect& rect, 522 int alignment = wxALIGN_LEFT | wxALIGN_TOP, 523 int indexAccel = -1); 524 525 /** 526 Draws a line from the first point to the second. The current pen is 527 used for drawing the line. Note that the point (@a x2, @a y2) is not 528 part of the line and is not drawn by this function (this is consistent 529 with the behaviour of many other toolkits). 530 */ 531 void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); 532 533 /** 534 @overload 535 */ 536 void DrawLine(const wxPoint& pt1, const wxPoint& pt2); 537 538 /** 539 Draws lines using an array of points of size @a n adding the optional 540 offset coordinate. The current pen is used for drawing the lines. 541 542 @beginWxPerlOnly 543 Not supported by wxPerl. 544 @endWxPerlOnly 545 */ 546 void DrawLines(int n, const wxPoint points[], wxCoord xoffset = 0, 547 wxCoord yoffset = 0); 548 /** 549 This method uses a list of wxPoints, adding the optional offset 550 coordinate. The programmer is responsible for deleting the list of 551 points. 552 553 @beginWxPerlOnly 554 The wxPerl version of this method accepts 555 as its first parameter a reference to an array 556 of wxPoint objects. 557 @endWxPerlOnly 558 */ 559 void DrawLines(const wxPointList* points, 560 wxCoord xoffset = 0, wxCoord yoffset = 0); 561 562 /** 563 Draws a point using the color of the current pen. Note that the other 564 properties of the pen are not used, such as width. 565 */ 566 void DrawPoint(wxCoord x, wxCoord y); 567 568 /** 569 @overload 570 */ 571 void DrawPoint(const wxPoint& pt); 572 573 /** 574 Draws a filled polygon using an array of points of size @a n, adding 575 the optional offset coordinate. The first and last points are 576 automatically closed. 577 578 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the 579 default) or @b wxWINDING_RULE. 580 581 The current pen is used for drawing the outline, and the current brush 582 for filling the shape. Using a transparent brush suppresses filling. 583 584 @beginWxPerlOnly 585 Not supported by wxPerl. 586 @endWxPerlOnly 587 */ 588 void DrawPolygon(int n, const wxPoint points[], wxCoord xoffset = 0, 589 wxCoord yoffset = 0, 590 wxPolygonFillMode fill_style = wxODDEVEN_RULE); 591 /** 592 This method draws a filled polygon using a list of wxPoints, adding the 593 optional offset coordinate. The first and last points are automatically 594 closed. 595 596 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the 597 default) or @b wxWINDING_RULE. 598 599 The current pen is used for drawing the outline, and the current brush 600 for filling the shape. Using a transparent brush suppresses filling. 601 602 The programmer is responsible for deleting the list of points. 603 604 @beginWxPerlOnly 605 The wxPerl version of this method accepts 606 as its first parameter a reference to an array 607 of wxPoint objects. 608 @endWxPerlOnly 609 */ 610 void DrawPolygon(const wxPointList* points, 611 wxCoord xoffset = 0, wxCoord yoffset = 0, 612 wxPolygonFillMode fill_style = wxODDEVEN_RULE); 613 614 /** 615 Draws two or more filled polygons using an array of @a points, adding 616 the optional offset coordinates. 617 618 Notice that for the platforms providing a native implementation of this 619 function (Windows and PostScript-based wxDC currently), this is more 620 efficient than using DrawPolygon() in a loop. 621 622 @a n specifies the number of polygons to draw, the array @e count of 623 size @a n specifies the number of points in each of the polygons in the 624 @a points array. 625 626 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the 627 default) or @b wxWINDING_RULE. 628 629 The current pen is used for drawing the outline, and the current brush 630 for filling the shape. Using a transparent brush suppresses filling. 631 632 The polygons maybe disjoint or overlapping. Each polygon specified in a 633 call to DrawPolyPolygon() must be closed. Unlike polygons created by 634 the DrawPolygon() member function, the polygons created by this 635 method are not closed automatically. 636 */ 637 void DrawPolyPolygon(int n, const int count[], const wxPoint points[], 638 wxCoord xoffset = 0, wxCoord yoffset = 0, 639 wxPolygonFillMode fill_style = wxODDEVEN_RULE); 640 641 /** 642 Draws a rectangle with the given corner coordinate and size. 643 644 Normally, @a x and @a y specify the top left corner coordinates and 645 both @a width and @a height are positive, however they are also allowed 646 to be negative, in which case the corresponding corner coordinate 647 refers to the right or bottom corner instead. 648 649 The current pen is used for the outline and the current brush 650 for filling the shape. 651 */ 652 void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); 653 654 /** 655 @overload 656 */ 657 void DrawRectangle(const wxPoint& pt, const wxSize& sz); 658 659 /** 660 @overload 661 */ 662 void DrawRectangle(const wxRect& rect); 663 664 /** 665 Draws the text rotated by @a angle degrees 666 (positive angles are counterclockwise; the full angle is 360 degrees). 667 668 Notice that, as with DrawText(), the @a text can contain multiple lines 669 separated by the new line (@c '\\n') characters. 670 671 @note Under MSW only TrueType fonts can be drawn by this function. In 672 particular, a font different from @c wxNORMAL_FONT should be used 673 as the latter is not a TrueType font. @c wxSWISS_FONT is an 674 example of a font which is. 675 676 @see DrawText() 677 */ 678 void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, 679 double angle); 680 681 /** 682 @overload 683 */ 684 void DrawRotatedText(const wxString& text, const wxPoint& point, 685 double angle); 686 687 /** 688 Draws a rectangle with the given top left corner, and with the given 689 size. The corners are quarter-circles using the given radius. The 690 current pen is used for the outline and the current brush for filling 691 the shape. 692 693 If @a radius is positive, the value is assumed to be the radius of the 694 rounded corner. If @a radius is negative, the absolute value is assumed 695 to be the @e proportion of the smallest dimension of the rectangle. 696 This means that the corner can be a sensible size relative to the size 697 of the rectangle, and also avoids the strange effects X produces when 698 the corners are too big for the rectangle. 699 */ 700 void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, 701 wxCoord height, double radius); 702 703 /** 704 @overload 705 */ 706 void DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz, 707 double radius); 708 709 /** 710 @overload 711 */ 712 void DrawRoundedRectangle(const wxRect& rect, double radius); 713 714 /** 715 Draws a spline between all given points using the current pen. 716 717 @beginWxPerlOnly 718 Not supported by wxPerl. 719 @endWxPerlOnly 720 */ 721 void DrawSpline(int n, const wxPoint points[]); 722 723 /** 724 @overload 725 726 727 @beginWxPerlOnly 728 The wxPerl version of this method accepts 729 as its first parameter a reference to an array 730 of wxPoint objects. 731 @endWxPerlOnly 732 */ 733 void DrawSpline(const wxPointList* points); 734 735 /** 736 @overload 737 738 739 @beginWxPerlOnly 740 Not supported by wxPerl. 741 @endWxPerlOnly 742 */ 743 void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, 744 wxCoord x3, wxCoord y3); 745 746 /** 747 Draws a text string at the specified point, using the current text 748 font, and the current text foreground and background colours. 749 750 The coordinates refer to the top-left corner of the rectangle bounding 751 the string. See GetTextExtent() for how to get the dimensions of a text 752 string, which can be used to position the text more precisely and 753 DrawLabel() if you need to align the string differently. 754 755 Starting from wxWidgets 2.9.2 @a text parameter can be a multi-line 756 string, i.e. contain new line characters, and will be rendered 757 correctly. 758 759 @note The current @ref GetLogicalFunction() "logical function" is 760 ignored by this function. 761 */ 762 void DrawText(const wxString& text, wxCoord x, wxCoord y); 763 764 /** 765 @overload 766 */ 767 void DrawText(const wxString& text, const wxPoint& pt); 768 769 /** 770 Fill the area specified by rect with a radial gradient, starting from 771 @a initialColour at the centre of the circle and fading to 772 @a destColour on the circle outside. 773 774 The circle is placed at the centre of @a rect. 775 776 @note Currently this function is very slow, don't use it for real-time 777 drawing. 778 */ 779 void GradientFillConcentric(const wxRect& rect, 780 const wxColour& initialColour, 781 const wxColour& destColour); 782 783 /** 784 Fill the area specified by rect with a radial gradient, starting from 785 @a initialColour at the centre of the circle and fading to 786 @a destColour on the circle outside. 787 788 @a circleCenter are the relative coordinates of centre of the circle in 789 the specified @a rect. 790 791 @note Currently this function is very slow, don't use it for real-time 792 drawing. 793 */ 794 void GradientFillConcentric(const wxRect& rect, 795 const wxColour& initialColour, 796 const wxColour& destColour, 797 const wxPoint& circleCenter); 798 799 /** 800 Fill the area specified by @a rect with a linear gradient, starting 801 from @a initialColour and eventually fading to @e destColour. 802 803 The @a nDirection specifies the direction of the colour change, default is 804 to use @a initialColour on the left part of the rectangle and 805 @a destColour on the right one. 806 */ 807 void GradientFillLinear(const wxRect& rect, const wxColour& initialColour, 808 const wxColour& destColour, 809 wxDirection nDirection = wxRIGHT); 810 811 /** 812 Flood fills the device context starting from the given point, using 813 the current brush colour, and using a style: 814 815 - wxFLOOD_SURFACE: The flooding occurs until a colour other than the 816 given colour is encountered. 817 - wxFLOOD_BORDER: The area to be flooded is bounded by the given 818 colour. 819 820 Currently this method is not implemented in wxOSX and does nothing 821 there. 822 823 @return @false if the operation failed. 824 825 @note The present implementation for non-Windows platforms may fail to 826 find colour borders if the pixels do not match the colour 827 exactly. However the function will still return @true. 828 829 @note This method shouldn't be used with wxPaintDC under non-Windows 830 platforms as it uses GetPixel() internally and this may give 831 wrong results, notably in wxGTK. If you need to flood fill 832 wxPaintDC, create a temporary wxMemoryDC, flood fill it and then 833 blit it to, or draw as a bitmap on, wxPaintDC. See the example of 834 doing this in the drawing sample and wxBufferedPaintDC class. 835 */ 836 bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, 837 wxFloodFillStyle style = wxFLOOD_SURFACE); 838 839 /** 840 @overload 841 */ 842 bool FloodFill(const wxPoint& pt, const wxColour& col, 843 wxFloodFillStyle style = wxFLOOD_SURFACE); 844 845 /** 846 Displays a cross hair using the current pen. This is a vertical and 847 horizontal line the height and width of the window, centred on the 848 given point. 849 */ 850 void CrossHair(wxCoord x, wxCoord y); 851 852 /** 853 @overload 854 */ 855 void CrossHair(const wxPoint& pt); 856 857 //@} 858 859 860 /** 861 @name Clipping region functions 862 */ 863 //@{ 864 865 /** 866 Destroys the current clipping region so that none of the DC is clipped. 867 868 @see SetClippingRegion() 869 */ 870 void DestroyClippingRegion(); 871 872 /** 873 Gets the rectangle surrounding the current clipping region. 874 If no clipping region is set this function returns the extent 875 of the device context. 876 877 @remarks 878 Clipping region is given in logical coordinates. 879 880 @param x If non-@NULL, filled in with the logical horizontal coordinate 881 of the top left corner of the clipping region if the function 882 returns true or 0 otherwise. 883 @param y If non-@NULL, filled in with the logical vertical coordinate 884 of the top left corner of the clipping region if the function 885 returns true or 0 otherwise. 886 @param width If non-@NULL, filled in with the width of the clipping 887 region if the function returns true or the device context width 888 otherwise. 889 @param height If non-@NULL, filled in with the height of the clipping 890 region if the function returns true or the device context height 891 otherwise. 892 @return @true if there is a clipping region or @false if there is no 893 active clipping region (note that this return value is available 894 only since wxWidgets 3.1.2, this function didn't return anything in 895 the previous versions). 896 */ 897 bool GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const; 898 899 /** 900 @overload 901 */ 902 bool GetClippingBox(wxRect& rect) const; 903 904 /** 905 Sets the clipping region for this device context to the intersection of 906 the given region described by the parameters of this method and the 907 previously set clipping region. 908 909 The clipping region is an area to which drawing is restricted. Possible 910 uses for the clipping region are for clipping text or for speeding up 911 window redraws when only a known area of the screen is damaged. 912 913 @remarks 914 - Clipping region should be given in logical coordinates. 915 916 - Calling this function can only make the clipping region smaller, 917 never larger. 918 919 - You need to call DestroyClippingRegion() first if you want to set 920 the clipping region exactly to the region specified. 921 922 - If resulting clipping region is empty, then all drawing on the DC is 923 clipped out (all changes made by drawing operations are masked out). 924 925 @see DestroyClippingRegion(), wxRegion 926 */ 927 void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); 928 929 /** 930 @overload 931 */ 932 void SetClippingRegion(const wxPoint& pt, const wxSize& sz); 933 934 /** 935 @overload 936 */ 937 void SetClippingRegion(const wxRect& rect); 938 939 /** 940 Sets the clipping region for this device context. 941 942 Unlike SetClippingRegion(), this function works with physical 943 coordinates and not with the logical ones. 944 */ 945 void SetDeviceClippingRegion(const wxRegion& region); 946 947 //@} 948 949 950 /** 951 @name Text/character extent functions 952 */ 953 //@{ 954 955 /** 956 Gets the character height of the currently set font. 957 */ 958 wxCoord GetCharHeight() const; 959 960 /** 961 Gets the average character width of the currently set font. 962 */ 963 wxCoord GetCharWidth() const; 964 965 /** 966 Returns the various font characteristics. 967 968 This method allows retrieving some of the font characteristics not 969 returned by GetTextExtent(), notably internal leading and average 970 character width. 971 972 Currently this method returns correct results only under wxMSW, in the 973 other ports the internal leading will always be 0 and the average 974 character width will be computed as the width of the character 'x'. 975 976 @since 2.9.2 977 */ 978 wxFontMetrics GetFontMetrics() const; 979 980 /** 981 Gets the dimensions of the string using the currently selected font. 982 @a string is the text string to measure, @e heightLine, if non @NULL, 983 is where to store the height of a single line. 984 985 The text extent is set in the given @a w and @a h pointers. 986 987 If the optional parameter @a font is specified and valid, then it is 988 used for the text extent calculation, otherwise the currently selected 989 font is used. 990 991 If @a string is empty, its horizontal extent is 0 but, for convenience 992 when using this function for allocating enough space for a possibly 993 multi-line string, its vertical extent is the same as the height of an 994 empty line of text. Please note that this behaviour differs from that 995 of GetTextExtent(). 996 997 @note This function works with both single-line and multi-line strings. 998 999 @beginWxPerlOnly 1000 In wxPerl this method is implemented as 1001 GetMultiLineTextExtent(string, font = undef) returning a 1002 3-element list (width, height, line_height) 1003 @endWxPerlOnly 1004 1005 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() 1006 */ 1007 void GetMultiLineTextExtent(const wxString& string, wxCoord* w, 1008 wxCoord* h, 1009 wxCoord* heightLine = NULL, 1010 const wxFont* font = NULL) const; 1011 /** 1012 Gets the dimensions of the string using the currently selected font. 1013 @a string is the text string to measure. 1014 1015 @return The text extent as a wxSize object. 1016 1017 @note This function works with both single-line and multi-line strings. 1018 1019 @beginWxPerlOnly 1020 Not supported by wxPerl. 1021 @endWxPerlOnly 1022 1023 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() 1024 */ 1025 wxSize GetMultiLineTextExtent(const wxString& string) const; 1026 1027 /** 1028 Fills the @a widths array with the widths from the beginning of @a text 1029 to the corresponding character of @a text. The generic version simply 1030 builds a running total of the widths of each character using 1031 GetTextExtent(), however if the various platforms have a native API 1032 function that is faster or more accurate than the generic 1033 implementation then it should be used instead. 1034 1035 @beginWxPerlOnly 1036 In wxPerl this method only takes the @a text parameter and 1037 returns the widths as a list of integers. 1038 @endWxPerlOnly 1039 1040 @see GetMultiLineTextExtent(), GetTextExtent() 1041 */ 1042 bool GetPartialTextExtents(const wxString& text, 1043 wxArrayInt& widths) const; 1044 1045 /** 1046 Gets the dimensions of the string using the currently selected font. 1047 @a string is the text string to measure, @a descent is the dimension 1048 from the baseline of the font to the bottom of the descender, and 1049 @a externalLeading is any extra vertical space added to the font by the 1050 font designer (usually is zero). 1051 1052 The text extent is returned in @a w and @a h pointers or as a wxSize 1053 object depending on which version of this function is used. 1054 1055 If the optional parameter @a font is specified and valid, then it is 1056 used for the text extent calculation. Otherwise the currently selected 1057 font is. 1058 1059 If @a string is empty, its extent is 0 in both directions, as expected. 1060 1061 @note This function only works with single-line strings. 1062 1063 @beginWxPerlOnly 1064 In wxPerl this method is implemented as GetTextExtent(string, 1065 font = undef) returning a 4-element list (width, height, 1066 descent, externalLeading) 1067 @endWxPerlOnly 1068 1069 @see wxFont, SetFont(), GetPartialTextExtents(), 1070 GetMultiLineTextExtent() 1071 */ 1072 void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h, 1073 wxCoord* descent = NULL, 1074 wxCoord* externalLeading = NULL, 1075 const wxFont* font = NULL) const; 1076 1077 /** 1078 @overload 1079 1080 1081 @beginWxPerlOnly 1082 Not supported by wxPerl. 1083 @endWxPerlOnly 1084 */ 1085 wxSize GetTextExtent(const wxString& string) const; 1086 1087 //@} 1088 1089 1090 /** 1091 @name Text properties functions 1092 */ 1093 //@{ 1094 1095 /** 1096 Returns the current background mode: @c wxBRUSHSTYLE_SOLID or @c wxBRUSHSTYLE_TRANSPARENT. 1097 1098 @see SetBackgroundMode() 1099 */ 1100 int GetBackgroundMode() const; 1101 1102 /** 1103 Gets the current font. 1104 1105 Notice that even although each device context object has some default font 1106 after creation, this method would return a ::wxNullFont initially and only 1107 after calling SetFont() a valid font is returned. 1108 */ 1109 const wxFont& GetFont() const; 1110 1111 /** 1112 Gets the current layout direction of the device context. On platforms 1113 where RTL layout is supported, the return value will either be 1114 @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is 1115 not supported, the return value will be @c wxLayout_Default. 1116 1117 @see SetLayoutDirection() 1118 */ 1119 wxLayoutDirection GetLayoutDirection() const; 1120 1121 /** 1122 Gets the current text background colour. 1123 1124 @see SetTextBackground() 1125 */ 1126 const wxColour& GetTextBackground() const; 1127 1128 /** 1129 Gets the current text foreground colour. 1130 1131 @see SetTextForeground() 1132 */ 1133 const wxColour& GetTextForeground() const; 1134 1135 /** 1136 Change the current background mode. 1137 1138 This setting determines whether text will be drawn with a background 1139 colour or not. 1140 1141 Default is @c wxBRUSHSTYLE_TRANSPARENT, i.e. text background is not 1142 drawn. 1143 1144 @param mode one of @c wxBRUSHSTYLE_SOLID and @c wxBRUSHSTYLE_TRANSPARENT. 1145 */ 1146 void SetBackgroundMode(int mode); 1147 1148 /** 1149 Sets the current font for the DC. 1150 1151 If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk), 1152 the current font is selected out of the device context (leaving wxDC without 1153 any valid font), allowing the current font to be destroyed safely. 1154 1155 @see wxFont 1156 */ 1157 void SetFont(const wxFont& font); 1158 1159 /** 1160 Sets the current text background colour for the DC. 1161 */ 1162 void SetTextBackground(const wxColour& colour); 1163 1164 /** 1165 Sets the current text foreground colour for the DC. 1166 1167 @see wxMemoryDC for the interpretation of colours when drawing into a 1168 monochrome bitmap. 1169 */ 1170 void SetTextForeground(const wxColour& colour); 1171 1172 /** 1173 Sets the current layout direction for the device context. 1174 1175 @param dir 1176 May be either @c wxLayout_Default, @c wxLayout_LeftToRight or 1177 @c wxLayout_RightToLeft. 1178 1179 @see GetLayoutDirection() 1180 */ 1181 void SetLayoutDirection(wxLayoutDirection dir); 1182 1183 //@} 1184 1185 1186 /** 1187 @name Bounding box functions 1188 */ 1189 //@{ 1190 1191 /** 1192 Adds the specified point to the bounding box which can be retrieved 1193 with MinX(), MaxX() and MinY(), MaxY() functions. 1194 1195 @see ResetBoundingBox() 1196 */ 1197 void CalcBoundingBox(wxCoord x, wxCoord y); 1198 1199 /** 1200 Gets the maximum horizontal extent used in drawing commands so far. 1201 */ 1202 wxCoord MaxX() const; 1203 1204 /** 1205 Gets the maximum vertical extent used in drawing commands so far. 1206 */ 1207 wxCoord MaxY() const; 1208 1209 /** 1210 Gets the minimum horizontal extent used in drawing commands so far. 1211 */ 1212 wxCoord MinX() const; 1213 1214 /** 1215 Gets the minimum vertical extent used in drawing commands so far. 1216 */ 1217 wxCoord MinY() const; 1218 1219 /** 1220 Resets the bounding box: after a call to this function, the bounding 1221 box doesn't contain anything. 1222 1223 @see CalcBoundingBox() 1224 */ 1225 void ResetBoundingBox(); 1226 1227 //@} 1228 1229 1230 /** 1231 @name Page and document start/end functions 1232 */ 1233 //@{ 1234 1235 /** 1236 Starts a document (only relevant when outputting to a printer). 1237 @a message is a message to show while printing. 1238 */ 1239 bool StartDoc(const wxString& message); 1240 1241 /** 1242 Starts a document page (only relevant when outputting to a printer). 1243 */ 1244 void StartPage(); 1245 1246 /** 1247 Ends a document (only relevant when outputting to a printer). 1248 */ 1249 void EndDoc(); 1250 1251 /** 1252 Ends a document page (only relevant when outputting to a printer). 1253 */ 1254 void EndPage(); 1255 1256 //@} 1257 1258 1259 /** 1260 @name Bit-Block Transfer operations (blit) 1261 */ 1262 //@{ 1263 1264 /** 1265 Copy from a source DC to this DC. 1266 1267 With this method you can specify the destination coordinates and the 1268 size of area to copy which will be the same for both the source and 1269 target DCs. If you need to apply scaling while copying, use 1270 StretchBlit(). 1271 1272 Notice that source DC coordinates @a xsrc and @a ysrc are interpreted 1273 using the current source DC coordinate system, i.e. the scale, origin 1274 position and axis directions are taken into account when transforming 1275 them to physical (pixel) coordinates. 1276 1277 @param xdest 1278 Destination device context x position. 1279 @param ydest 1280 Destination device context y position. 1281 @param width 1282 Width of source area to be copied. 1283 @param height 1284 Height of source area to be copied. 1285 @param source 1286 Source device context. 1287 @param xsrc 1288 Source device context x position. 1289 @param ysrc 1290 Source device context y position. 1291 @param logicalFunc 1292 Logical function to use, see SetLogicalFunction(). 1293 @param useMask 1294 If @true, Blit does a transparent blit using the mask that is 1295 associated with the bitmap selected into the source device context. 1296 The Windows implementation does the following if MaskBlt cannot be 1297 used: 1298 <ol> 1299 <li>Creates a temporary bitmap and copies the destination area into 1300 it.</li> 1301 <li>Copies the source area into the temporary bitmap using the 1302 specified logical function.</li> 1303 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing 1304 the mask bitmap with the temp bitmap with the foreground colour 1305 set to WHITE and the bg colour set to BLACK.</li> 1306 <li>Sets the unmasked area in the destination area to BLACK by 1307 ANDing the mask bitmap with the destination area with the 1308 foreground colour set to BLACK and the background colour set to 1309 WHITE.</li> 1310 <li>ORs the temporary bitmap with the destination area.</li> 1311 <li>Deletes the temporary bitmap.</li> 1312 </ol> 1313 This sequence of operations ensures that the source's transparent 1314 area need not be black, and logical functions are supported. 1315 @n @b Note: on Windows, blitting with masks can be speeded up 1316 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option 1317 enabled. You can also influence whether MaskBlt or the explicit 1318 mask blitting code above is used, by using wxSystemOptions and 1319 setting the @c no-maskblt option to 1. 1320 @param xsrcMask 1321 Source x position on the mask. If both xsrcMask and ysrcMask are 1322 @c -1, xsrc and ysrc will be assumed for the mask source position. 1323 Currently only implemented on Windows. 1324 @param ysrcMask 1325 Source y position on the mask. If both xsrcMask and ysrcMask are 1326 @c -1, xsrc and ysrc will be assumed for the mask source position. 1327 Currently only implemented on Windows. 1328 1329 @remarks There is partial support for Blit() in wxPostScriptDC, under X. 1330 1331 @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask 1332 */ 1333 bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, 1334 wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc, 1335 wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false, 1336 wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord); 1337 1338 /** 1339 Copy from a source DC to this DC possibly changing the scale. 1340 1341 Unlike Blit(), this method allows specifying different source and 1342 destination region sizes, meaning that it can stretch or shrink it 1343 while copying. The same can be achieved by changing the scale of the 1344 source or target DC but calling this method is simpler and can also be 1345 more efficient if the platform provides a native implementation of it. 1346 1347 The meaning of its other parameters is the same as with Blit(), in 1348 particular all source coordinates are interpreted using the source DC 1349 coordinate system, i.e. are affected by its scale, origin translation 1350 and axis direction. 1351 1352 @param xdest 1353 Destination device context x position. 1354 @param ydest 1355 Destination device context y position. 1356 @param dstWidth 1357 Width of destination area. 1358 @param dstHeight 1359 Height of destination area. 1360 @param source 1361 Source device context. 1362 @param xsrc 1363 Source device context x position. 1364 @param ysrc 1365 Source device context y position. 1366 @param srcWidth 1367 Width of source area to be copied. 1368 @param srcHeight 1369 Height of source area to be copied. 1370 @param logicalFunc 1371 Logical function to use, see SetLogicalFunction(). 1372 @param useMask 1373 If @true, Blit does a transparent blit using the mask that is 1374 associated with the bitmap selected into the source device context. 1375 The Windows implementation does the following if MaskBlt cannot be 1376 used: 1377 <ol> 1378 <li>Creates a temporary bitmap and copies the destination area into 1379 it.</li> 1380 <li>Copies the source area into the temporary bitmap using the 1381 specified logical function.</li> 1382 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing 1383 the mask bitmap with the temp bitmap with the foreground colour 1384 set to WHITE and the bg colour set to BLACK.</li> 1385 <li>Sets the unmasked area in the destination area to BLACK by 1386 ANDing the mask bitmap with the destination area with the 1387 foreground colour set to BLACK and the background colour set to 1388 WHITE.</li> 1389 <li>ORs the temporary bitmap with the destination area.</li> 1390 <li>Deletes the temporary bitmap.</li> 1391 </ol> 1392 This sequence of operations ensures that the source's transparent 1393 area need not be black, and logical functions are supported. 1394 @n @b Note: on Windows, blitting with masks can be speeded up 1395 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option 1396 enabled. You can also influence whether MaskBlt or the explicit 1397 mask blitting code above is used, by using wxSystemOptions and 1398 setting the @c no-maskblt option to 1. 1399 @param xsrcMask 1400 Source x position on the mask. If both xsrcMask and ysrcMask are 1401 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask 1402 source position. Currently only implemented on Windows. 1403 @param ysrcMask 1404 Source y position on the mask. If both xsrcMask and ysrcMask are 1405 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask 1406 source position. Currently only implemented on Windows. 1407 1408 There is partial support for Blit() in wxPostScriptDC, under X. 1409 1410 See wxMemoryDC for typical usage. 1411 1412 @since 2.9.0 1413 1414 @see Blit(), wxMemoryDC, wxBitmap, wxMask 1415 */ 1416 bool StretchBlit(wxCoord xdest, wxCoord ydest, 1417 wxCoord dstWidth, wxCoord dstHeight, 1418 wxDC* source, wxCoord xsrc, wxCoord ysrc, 1419 wxCoord srcWidth, wxCoord srcHeight, 1420 wxRasterOperationMode logicalFunc = wxCOPY, 1421 bool useMask = false, 1422 wxCoord xsrcMask = wxDefaultCoord, 1423 wxCoord ysrcMask = wxDefaultCoord); 1424 //@} 1425 1426 1427 /** 1428 @name Background/foreground brush and pen 1429 */ 1430 //@{ 1431 1432 /** 1433 Gets the brush used for painting the background. 1434 1435 @see wxDC::SetBackground() 1436 */ 1437 const wxBrush& GetBackground() const; 1438 1439 /** 1440 Gets the current brush. 1441 1442 @see wxDC::SetBrush() 1443 */ 1444 const wxBrush& GetBrush() const; 1445 1446 /** 1447 Gets the current pen. 1448 1449 @see SetPen() 1450 */ 1451 const wxPen& GetPen() const; 1452 1453 /** 1454 Sets the current background brush for the DC. 1455 */ 1456 void SetBackground(const wxBrush& brush); 1457 1458 /** 1459 Sets the current brush for the DC. 1460 1461 If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk), 1462 the current brush is selected out of the device context (leaving wxDC without 1463 any valid brush), allowing the current brush to be destroyed safely. 1464 1465 @see wxBrush, wxMemoryDC (for the interpretation of colours when 1466 drawing into a monochrome bitmap) 1467 */ 1468 void SetBrush(const wxBrush& brush); 1469 1470 /** 1471 Sets the current pen for the DC. 1472 1473 If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk), 1474 the current pen is selected out of the device context (leaving wxDC without any 1475 valid pen), allowing the current pen to be destroyed safely. 1476 1477 @see wxMemoryDC for the interpretation of colours when drawing into a 1478 monochrome bitmap. 1479 */ 1480 void SetPen(const wxPen& pen); 1481 1482 //@} 1483 1484 1485 /** 1486 Copy attributes from another DC. 1487 1488 The copied attributes currently are: 1489 - Font 1490 - Text foreground and background colours 1491 - Background brush 1492 - Layout direction 1493 1494 @param dc 1495 A valid (i.e. its IsOk() must return @true) source device context. 1496 */ 1497 void CopyAttributes(const wxDC& dc); 1498 1499 /** 1500 Returns the depth (number of bits/pixel) of this DC. 1501 1502 @see wxDisplayDepth() 1503 */ 1504 int GetDepth() const; 1505 1506 /** 1507 Returns the current device origin. 1508 1509 @see SetDeviceOrigin() 1510 */ 1511 wxPoint GetDeviceOrigin() const; 1512 1513 /** 1514 Gets the current logical function. 1515 1516 @see SetLogicalFunction() 1517 */ 1518 wxRasterOperationMode GetLogicalFunction() const; 1519 1520 /** 1521 Gets the current mapping mode for the device context. 1522 1523 @see SetMapMode() 1524 */ 1525 wxMappingMode GetMapMode() const; 1526 1527 /** 1528 Gets in @a colour the colour at the specified location. 1529 1530 This method isn't available for wxPostScriptDC or wxMetafileDC nor for 1531 any DC in wxOSX port and simply returns @false there. 1532 1533 @note Setting a pixel can be done using DrawPoint(). 1534 1535 @note This method shouldn't be used with wxPaintDC as accessing the DC 1536 while drawing can result in unexpected results, notably in wxGTK. 1537 */ 1538 bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const; 1539 1540 /** 1541 Returns the resolution of the device in pixels per inch. 1542 */ 1543 wxSize GetPPI() const; 1544 1545 /** 1546 Gets the horizontal and vertical extent of this device context in @e device units. 1547 It can be used to scale graphics to fit the page. 1548 1549 For example, if @e maxX and @e maxY represent the maximum horizontal 1550 and vertical 'pixel' values used in your application, the following 1551 code will scale the graphic to fit on the printer page: 1552 1553 @code 1554 wxCoord w, h; 1555 dc.GetSize(&w, &h); 1556 double scaleX = (double)(maxX / w); 1557 double scaleY = (double)(maxY / h); 1558 dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); 1559 @endcode 1560 1561 @beginWxPerlOnly 1562 In wxPerl there are two methods instead of a single overloaded 1563 method: 1564 - GetSize(): returns a Wx::Size object. 1565 - GetSizeWH(): returns a 2-element list (width, height). 1566 @endWxPerlOnly 1567 */ 1568 void GetSize(wxCoord* width, wxCoord* height) const; 1569 1570 /** 1571 @overload 1572 */ 1573 wxSize GetSize() const; 1574 1575 /** 1576 Returns the horizontal and vertical resolution in millimetres. 1577 */ 1578 void GetSizeMM(wxCoord* width, wxCoord* height) const; 1579 1580 /** 1581 @overload 1582 */ 1583 wxSize GetSizeMM() const; 1584 1585 /** 1586 Gets the current user scale factor. 1587 1588 @beginWxPerlOnly 1589 In wxPerl this method takes no arguments and return a two 1590 element array (x, y). 1591 @endWxPerlOnly 1592 1593 @see SetUserScale() 1594 */ 1595 void GetUserScale(double* x, double* y) const; 1596 1597 /** 1598 Returns @true if the DC is ok to use. 1599 */ 1600 bool IsOk() const; 1601 1602 /** 1603 Sets the x and y axis orientation (i.e.\ the direction from lowest to 1604 highest values on the axis). The default orientation is x axis from 1605 left to right and y axis from top down. 1606 1607 @param xLeftRight 1608 True to set the x axis orientation to the natural left to right 1609 orientation, @false to invert it. 1610 @param yBottomUp 1611 True to set the y axis orientation to the natural bottom up 1612 orientation, @false to invert it. 1613 */ 1614 void SetAxisOrientation(bool xLeftRight, bool yBottomUp); 1615 1616 /** 1617 Sets the device origin (i.e.\ the origin in pixels after scaling has 1618 been applied). This function may be useful in Windows printing 1619 operations for placing a graphic on a page. 1620 */ 1621 void SetDeviceOrigin(wxCoord x, wxCoord y); 1622 1623 /** 1624 Sets the current logical function for the device context. 1625 1626 @note This function is not fully supported in all ports, due to the 1627 limitations of the underlying drawing model. Notably, @c wxINVERT which 1628 was commonly used for drawing rubber bands or other moving outlines in 1629 the past, is not, and will not, be supported by wxGTK3 and wxMac. The 1630 suggested alternative is to draw temporarily objects normally and 1631 refresh the (affected part of the) window to remove them later. 1632 1633 It determines how a @e source pixel (from a pen or brush colour, or source 1634 device context if using Blit()) combines with a @e destination pixel in 1635 the current device context. 1636 Text drawing is not affected by this function. 1637 1638 See ::wxRasterOperationMode enumeration values for more info. 1639 1640 The default is @c wxCOPY, which simply draws with the current colour. 1641 The others combine the current colour and the background using a logical 1642 operation. 1643 */ 1644 void SetLogicalFunction(wxRasterOperationMode function); 1645 1646 /** 1647 The mapping mode of the device context defines the unit of measurement 1648 used to convert @e logical units to @e device units. 1649 1650 Note that in X, text drawing isn't handled consistently with the mapping mode; 1651 a font is always specified in point size. However, setting the user scale (see 1652 SetUserScale()) scales the text appropriately. In Windows, scalable 1653 TrueType fonts are always used; in X, results depend on availability of 1654 fonts, but usually a reasonable match is found. 1655 1656 The coordinate origin is always at the top left of the screen/printer. 1657 1658 Drawing to a Windows printer device context uses the current mapping 1659 mode, but mapping mode is currently ignored for PostScript output. 1660 */ 1661 void SetMapMode(wxMappingMode mode); 1662 1663 /** 1664 If this is a window DC or memory DC, assigns the given palette to the 1665 window or bitmap associated with the DC. If the argument is 1666 ::wxNullPalette, the current palette is selected out of the device 1667 context, and the original palette restored. 1668 1669 @see wxPalette 1670 */ 1671 void SetPalette(const wxPalette& palette); 1672 1673 /** 1674 Sets the user scaling factor, useful for applications which require 1675 'zooming'. 1676 */ 1677 void SetUserScale(double xScale, double yScale); 1678 1679 1680 /** 1681 @name Transformation matrix 1682 1683 See the notes about the availability of these functions in the class 1684 documentation. 1685 */ 1686 //@{ 1687 1688 /** 1689 Check if the use of transformation matrix is supported by the current 1690 system. 1691 1692 This function returns @true for MSW and GTK+ 3 platforms and since 1693 3.1.1 also for wxGCDC in all ports. 1694 1695 @since 2.9.2 1696 */ 1697 bool CanUseTransformMatrix() const; 1698 1699 /** 1700 Set the transformation matrix. 1701 1702 If transformation matrix is supported on the current system, the 1703 specified @a matrix will be used to transform between wxDC and physical 1704 coordinates. Otherwise the function returns @false and doesn't change 1705 the coordinate mapping. 1706 1707 @since 2.9.2 1708 */ 1709 bool SetTransformMatrix(const wxAffineMatrix2D& matrix); 1710 1711 /** 1712 Return the transformation matrix used by this device context. 1713 1714 By default the transformation matrix is the identity matrix. 1715 1716 @since 2.9.2 1717 */ 1718 wxAffineMatrix2D GetTransformMatrix() const; 1719 1720 /** 1721 Revert the transformation matrix to identity matrix. 1722 1723 @since 2.9.2 1724 */ 1725 void ResetTransformMatrix(); 1726 1727 //@} 1728 1729 1730 /** 1731 @name query capabilities 1732 */ 1733 //@{ 1734 1735 /** 1736 Does the DC support drawing bitmaps? 1737 */ 1738 bool CanDrawBitmap() const; 1739 1740 /** 1741 Does the DC support calculating the size required to draw text? 1742 */ 1743 bool CanGetTextExtent() const; 1744 1745 //@} 1746 1747 /** 1748 Returns a value that can be used as a handle to the native drawing 1749 context, if this wxDC has something that could be thought of in that 1750 way. (Not all of them do.) 1751 1752 For example, on Windows the return value is an HDC, on macOS it is a 1753 CGContextRef and on wxGTK it will be a GdkDrawable. If the DC is a 1754 wxGCDC then the return value will be the value returned from 1755 wxGraphicsContext::GetNativeContext. A value of NULL is returned if 1756 the DC does not have anything that fits the handle concept. 1757 1758 @since 2.9.5 1759 */ 1760 void* GetHandle() const; 1761 1762 1763 /** 1764 If supported by the platform and the type of DC, fetch the contents of the DC, or a subset of it, as a bitmap. 1765 */ 1766 wxBitmap GetAsBitmap(const wxRect *subrect = NULL) const; 1767 1768 1769 /** 1770 Set the scale to use for translating wxDC coordinates to the physical 1771 pixels. 1772 1773 The effect of calling this function is similar to that of calling 1774 SetUserScale(). 1775 */ 1776 void SetLogicalScale(double x, double y); 1777 1778 /** 1779 Return the scale set by the last call to SetLogicalScale(). 1780 */ 1781 void GetLogicalScale(double *x, double *y) const; 1782 1783 /** 1784 Change the offset used for translating wxDC coordinates. 1785 1786 @see SetLogicalOrigin(), SetDeviceOrigin() 1787 */ 1788 void SetLogicalOrigin(wxCoord x, wxCoord y); 1789 1790 //@{ 1791 /** 1792 Return the coordinates of the logical point (0, 0). 1793 1794 @see SetLogicalOrigin() 1795 */ 1796 void GetLogicalOrigin(wxCoord *x, wxCoord *y) const; 1797 wxPoint GetLogicalOrigin() const; 1798 //@} 1799 1800 /** 1801 If supported by the platform and the @a wxDC implementation, this method 1802 will return the @a wxGraphicsContext associated with the DC. Otherwise 1803 @NULL is returned. 1804 */ 1805 virtual wxGraphicsContext* GetGraphicsContext() const; 1806 1807 /** 1808 Associate a wxGraphicsContext with the DC. Ignored if not supported by 1809 the specific @a wxDC implementation. It is unlikely that this will need to 1810 be used in application code. 1811 */ 1812 virtual void SetGraphicsContext( wxGraphicsContext* ctx ); 1813 1814 }; 1815 1816 1817 1818 /** 1819 @class wxDCClipper 1820 1821 wxDCClipper is a helper class for setting a clipping region on a wxDC 1822 during its lifetime. 1823 1824 An object of wxDCClipper class is typically created on the stack so that it 1825 is automatically destroyed when the object goes out of scope. A typical 1826 usage example: 1827 1828 @code 1829 void MyFunction(wxDC& dc) 1830 { 1831 wxDCClipper clip(dc, rect); 1832 // ... drawing functions here are affected by clipping rect ... 1833 } 1834 1835 void OtherFunction() 1836 { 1837 wxDC dc; 1838 MyFunction(dc); 1839 // ... drawing functions here are not affected by clipping rect ... 1840 } 1841 @endcode 1842 1843 @note Since 3.1.1 wxDCClipper restores the previously active clipping 1844 region when it is destroyed. Previously it reset clipping on the 1845 associated wxDC and this has to be taken into account explicitly in 1846 previous wxWidgets versions. 1847 1848 @library{wxcore} 1849 @category{gdi} 1850 1851 @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, 1852 wxDCBrushChanger 1853 */ 1854 class wxDCClipper 1855 { 1856 public: 1857 //@{ 1858 /** 1859 Sets the clipping region to the specified region/coordinates. 1860 1861 The clipping region is automatically unset when this object is destroyed. 1862 */ 1863 wxDCClipper(wxDC& dc, const wxRegion& region); 1864 wxDCClipper(wxDC& dc, const wxRect& rect); 1865 wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h); 1866 //@} 1867 1868 /** 1869 Destroys the clipping region associated with the DC passed to the ctor. 1870 */ 1871 ~wxDCClipper(); 1872 }; 1873 1874 1875 /** 1876 @class wxDCBrushChanger 1877 1878 wxDCBrushChanger is a small helper class for setting a brush on a wxDC 1879 and unsetting it automatically in the destructor, restoring the previous one. 1880 1881 @library{wxcore} 1882 @category{gdi} 1883 1884 @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, 1885 wxDCClipper 1886 */ 1887 class wxDCBrushChanger 1888 { 1889 public: 1890 /** 1891 Sets @a brush on the given @a dc, storing the old one. 1892 1893 @param dc 1894 The DC where the brush must be temporary set. 1895 @param brush 1896 The brush to set. 1897 */ 1898 wxDCBrushChanger(wxDC& dc, const wxBrush& brush); 1899 1900 /** 1901 Restores the brush originally selected in the DC passed to the ctor. 1902 */ 1903 ~wxDCBrushChanger(); 1904 }; 1905 1906 1907 /** 1908 @class wxDCPenChanger 1909 1910 wxDCPenChanger is a small helper class for setting a pen on a wxDC 1911 and unsetting it automatically in the destructor, restoring the previous one. 1912 1913 @library{wxcore} 1914 @category{gdi} 1915 1916 @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger, 1917 wxDCClipper 1918 */ 1919 class wxDCPenChanger 1920 { 1921 public: 1922 /** 1923 Sets @a pen on the given @a dc, storing the old one. 1924 1925 @param dc 1926 The DC where the pen must be temporary set. 1927 @param pen 1928 The pen to set. 1929 */ 1930 wxDCPenChanger(wxDC& dc, const wxPen& pen); 1931 1932 /** 1933 Restores the pen originally selected in the DC passed to the ctor. 1934 */ 1935 ~wxDCPenChanger(); 1936 }; 1937 1938 1939 1940 /** 1941 @class wxDCTextColourChanger 1942 1943 wxDCTextColourChanger is a small helper class for setting a foreground 1944 text colour on a wxDC and unsetting it automatically in the destructor, 1945 restoring the previous one. 1946 1947 @library{wxcore} 1948 @category{gdi} 1949 1950 @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger, 1951 wxDCClipper, wxDCTextBgColourChanger, wxDCBgModeChanger 1952 */ 1953 class wxDCTextColourChanger 1954 { 1955 public: 1956 /** 1957 Trivial constructor not changing anything. 1958 1959 This constructor is useful if you don't know beforehand if the colour 1960 needs to be changed or not. It simply creates the object which won't do 1961 anything in its destructor unless Set() is called -- in which case it 1962 would reset the previous colour. 1963 */ 1964 wxDCTextColourChanger(wxDC& dc); 1965 1966 /** 1967 Sets @a col on the given @a dc, storing the old one. 1968 1969 @param dc 1970 The DC where the colour must be temporary set. 1971 @param col 1972 The colour to set. 1973 */ 1974 wxDCTextColourChanger(wxDC& dc, const wxColour& col); 1975 1976 /** 1977 Set the colour to use. 1978 1979 This method is meant to be called once only and only on the objects 1980 created with the constructor overload not taking wxColour argument and 1981 has the same effect as the other constructor, i.e. sets the colour to 1982 the given @a col and ensures that the old value is restored when this 1983 object is destroyed. 1984 */ 1985 void Set(const wxColour& col); 1986 1987 /** 1988 Restores the colour originally selected in the DC passed to the ctor. 1989 */ 1990 ~wxDCTextColourChanger(); 1991 }; 1992 1993 1994 /** 1995 @class wxDCTextBgColourChanger 1996 1997 wxDCTextBgColourChanger is a small helper class for setting a background 1998 text colour on a wxDC and unsetting it automatically in the destructor, 1999 restoring the previous one. 2000 2001 @library{wxcore} 2002 @category{gdi} 2003 2004 @see wxDC::SetTextBackground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger, 2005 wxDCClipper, wxDCTextColourChanger, wxDCBgModeChanger 2006 2007 @since 3.1.3 2008 */ 2009 class wxDCTextBgColourChanger 2010 { 2011 public: 2012 /** 2013 Trivial constructor not changing anything. 2014 2015 This constructor is useful if you don't know beforehand if the colour 2016 needs to be changed or not. It simply creates the object which won't do 2017 anything in its destructor unless Set() is called -- in which case it 2018 would reset the previous colour. 2019 */ 2020 wxDCTextBgColourChanger(wxDC& dc); 2021 2022 /** 2023 Sets @a col on the given @a dc, storing the old one. 2024 2025 @param dc 2026 The DC where the colour must be temporary set. 2027 @param col 2028 The text background colour to set. 2029 */ 2030 wxDCTextBgColourChanger(wxDC& dc, const wxColour& col); 2031 2032 /** 2033 Set the background colour to use. 2034 2035 This method is meant to be called once only and only on the objects 2036 created with the constructor overload not taking wxColour argument and 2037 has the same effect as the other constructor, i.e. sets the background colour to 2038 the given @a col and ensures that the old value is restored when this 2039 object is destroyed. 2040 */ 2041 void Set(const wxColour& col); 2042 2043 /** 2044 Restores the background colour originally selected in the DC passed to the ctor. 2045 */ 2046 ~wxDCTextBgColourChanger(); 2047 }; 2048 2049 2050 /** 2051 @class wxDCTextBgModeChanger 2052 2053 wxDCTextBgModeChanger is a small helper class for setting a background 2054 text mode on a wxDC and unsetting it automatically in the destructor, 2055 restoring the previous one. 2056 2057 @library{wxcore} 2058 @category{gdi} 2059 2060 @see wxDC::SetBackgroundMode(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger, 2061 wxDCClipper, wxDCTextColourChanger, wxDCTextBgColourChanger 2062 2063 @since 3.1.3 2064 */ 2065 class wxDCBgModeChanger 2066 { 2067 public: 2068 /** 2069 Trivial constructor not changing anything. 2070 2071 This constructor is useful if you don't know beforehand if the background mode 2072 needs to be changed or not. It simply creates the object which won't do 2073 anything in its destructor unless Set() is called -- in which case it 2074 would reset the previous mode. 2075 */ 2076 wxDCBgModeChanger(wxDC& dc); 2077 2078 /** 2079 Sets @a mode on the given @a dc, storing the old one. 2080 2081 @param dc 2082 The DC where the mode must be temporary set. 2083 @param mode 2084 The background mode to set, one of @c wxBRUSHSTYLE_SOLID or @c 2085 wxBRUSHSTYLE_TRANSPARENT. 2086 */ 2087 wxDCBgModeChanger(wxDC& dc, int mode); 2088 2089 /** 2090 Set the text background mode to use. 2091 2092 This method is meant to be called once only and only on the objects 2093 created with the constructor overload not taking mode argument and 2094 has the same effect as the other constructor, i.e. sets the background mode to 2095 the given @a one, and ensures that the old value is restored when this 2096 object is destroyed. 2097 */ 2098 void Set(int mode); 2099 2100 /** 2101 Restores the text background mode originally selected in the DC passed to the ctor. 2102 */ 2103 ~wxDCBgModeChanger(); 2104 }; 2105 2106 2107 /** 2108 @class wxDCFontChanger 2109 2110 wxDCFontChanger is a small helper class for setting a font on a wxDC and 2111 unsetting it automatically in the destructor, restoring the previous one. 2112 2113 @since 2.9.0 2114 2115 @library{wxcore} 2116 @category{gdi} 2117 2118 @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger, 2119 wxDCClipper 2120 */ 2121 class wxDCFontChanger 2122 { 2123 public: 2124 /** 2125 Trivial constructor not changing anything. 2126 2127 This constructor is useful if you don't know beforehand if the font 2128 needs to be changed or not. It simply creates the object which won't do 2129 anything in its destructor unless Set() is called -- in which case it 2130 would reset the previous font. 2131 2132 @since 2.9.1 2133 */ 2134 wxDCFontChanger(wxDC& dc); 2135 2136 /** 2137 Sets @a font on the given @a dc, storing the old one. 2138 2139 @param dc 2140 The DC where the font must be temporary set. 2141 @param font 2142 The font to set. 2143 */ 2144 wxDCFontChanger(wxDC& dc, const wxFont& font); 2145 2146 /** 2147 Set the font to use. 2148 2149 This method is meant to be called once only and only on the objects 2150 created with the constructor overload not taking wxFont argument and 2151 has the same effect as the other constructor, i.e. sets the font to 2152 the given @a font and ensures that the old value is restored when this 2153 object is destroyed. 2154 */ 2155 void Set(const wxFont& font); 2156 2157 /** 2158 Restores the font originally selected in the DC passed to the ctor. 2159 */ 2160 ~wxDCFontChanger(); 2161 }; 2162 2163