interface/wx/dc.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dc.h
   3 // Purpose:     interface of wxDC
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     Logical raster operations which can be used with wxDC::SetLogicalFunction
  12     and some other wxDC functions (e.g. wxDC::Blit and wxDC::StretchBlit).
  13
  14     The description of the values below refer to how a generic @e src source pixel
  15     and the corresponding @e dst destination pixel gets combined together to produce
  16     the final pixel. E.g. @c wxCLEAR and @c wxSET completely ignore the source
  17     and the destination pixel and always put zeroes or ones in the final surface.
  18 */
  19 enum wxRasterOperationMode
  20 {
  21     wxCLEAR,       //!< 0
  22     wxXOR,         //!< @e src XOR @e dst
  23     wxINVERT,      //!< NOT @e dst
  24     wxOR_REVERSE,  //!< @e src OR (NOT @e dst)
  25     wxAND_REVERSE, //!< @e src AND (NOT @e dst)
  26     wxCOPY,        //!< @e src
  27     wxAND,         //!< @e src AND @e dst
  28     wxAND_INVERT,  //!< (NOT @e src) AND @e dst
  29     wxNO_OP,       //!< @e dst
  30     wxNOR,         //!< (NOT @e src) AND (NOT @e dst)
  31     wxEQUIV,       //!< (NOT @e src) XOR @e dst
  32     wxSRC_INVERT,  //!< (NOT @e src)
  33     wxOR_INVERT,   //!< (NOT @e src) OR @e dst
  34     wxNAND,        //!< (NOT @e src) OR (NOT @e dst)
  35     wxOR,          //!< @e src OR @e dst
  36     wxSET          //!< 1
  37 };
  38
  39 /**
  40     Flood styles used by wxDC::FloodFill.
  41 */
  42 enum wxFloodFillStyle
  43 {
  44     /** The flooding occurs until a colour other than the given colour is encountered. */
  45     wxFLOOD_SURFACE = 1,
  46
  47     /** The area to be flooded is bounded by the given colour. */
  48     wxFLOOD_BORDER
  49 };
  50
  51 /**
  52     The mapping used to transform @e logical units to @e device units.
  53     See wxDC::SetMapMode.
  54 */
  55 enum wxMappingMode
  56 {
  57     /**
  58         Each logical unit is 1 device pixel.
  59         This is the default mapping mode for all wxDC-derived classes.
  60     */
  61     wxMM_TEXT = 1,
  62
  63     /** Each logical unit is 1 millimeter. */
  64     wxMM_METRIC,
  65
  66     /** Each logical unit is 1/10 of a millimeter. */
  67     wxMM_LOMETRIC,
  68
  69     /**
  70         Each logical unit is 1/20 of a @e "printer point", or 1/1440 of an inch
  71         (also known as "twip"). Equivalent to about 17.64 micrometers.
  72     */
  73     wxMM_TWIPS,
  74
  75     /**
  76         Each logical unit is a @e "printer point" i.e. 1/72 of an inch.
  77         Equivalent to about 353 micrometers.
  78     */
  79     wxMM_POINTS
  80 };
  81
  82
  83
  84 /**
  85     @class wxDC
  86
  87     A wxDC is a @e "device context" onto which graphics and text can be drawn.
  88     It is intended to represent different output devices and offers a common
  89     abstract API for drawing on any of them.
  90
  91     wxWidgets offers an alternative drawing API based on the modern drawing
  92     backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer
  93     and related classes. There is also a wxGCDC linking the APIs by offering
  94     the wxDC API ontop of a wxGraphicsContext.
  95
  96     wxDC is an abstract base class and cannot be created directly.
  97     Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
  98     wxPrinterDC. Notice that device contexts which are associated with windows
  99     (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours
 100     by default (starting with wxWidgets 2.9.0) but the other device context
 101     classes use system-default values so you always must set the appropriate
 102     fonts and colours before using them.
 103
 104     In addition to the versions of the methods documented below, there
 105     are also versions which accept single wxPoint parameter instead
 106     of the two wxCoord ones or wxPoint and wxSize instead of the four
 107     wxCoord parameters.
 108
 109     Beginning with wxWidgets 2.9.0 the entire wxDC code has been
 110     reorganized. All platform dependent code (actually all drawing code)
 111     has been moved into backend classes which derive from a common
 112     wxDCImpl class. The user-visible classes such as wxClientDC and
 113     wxPaintDC merely forward all calls to the backend implementation.
 114
 115
 116     @section dc_units Device and logical units
 117
 118     In the wxDC context there is a distinction between @e logical units and @e device units.
 119
 120     @b Device units are the units native to the particular device; e.g. for a screen,
 121     a device unit is a @e pixel. For a printer, the device unit is defined by the
 122     resolution of the printer (usually given in @c DPI: dot-per-inch).
 123
 124     All wxDC functions use instead @b logical units, unless where explicitely
 125     stated. Logical units are arbitrary units mapped to device units using
 126     the current mapping mode (see wxDC::SetMapMode).
 127
 128     This mechanism allows to reuse the same code which prints on e.g. a window
 129     on the screen to print on e.g. a paper.
 130
 131
 132     @section dc_alpha_support Support for Transparency / Alpha Channel
 133
 134     On Mac OS X colours with alpha channel are supported. Instances of wxPen
 135     or wxBrush that are built from wxColour use the colour's alpha values
 136     when stroking or filling.
 137
 138
 139     @library{wxcore}
 140     @category{dc,gdi}
 141
 142     @see @ref overview_dc, wxGraphicsContext, wxDCFontChanger, wxDCTextColourChanger,
 143          wxDCPenChanger, wxDCBrushChanger, wxDCClipper
 144
 145     @todo Precise definition of default/initial state.
 146     @todo Pixelwise definition of operations (e.g. last point of a line not
 147           drawn).
 148 */
 149 class wxDC : public wxObject
 150 {
 151 public:
 152     /**
 153         @name Coordinate conversion functions
 154     */
 155     //@{
 156
 157     /**
 158         Convert @e device X coordinate to logical coordinate, using the current
 159         mapping mode, user scale factor, device origin and axis orientation.
 160     */
 161     wxCoord DeviceToLogicalX(wxCoord x) const;
 162
 163     /**
 164         Convert @e device X coordinate to relative logical coordinate, using the
 165         current mapping mode and user scale factor but ignoring the
 166         axis orientation. Use this for converting a width, for example.
 167     */
 168     wxCoord DeviceToLogicalXRel(wxCoord x) const;
 169
 170     /**
 171         Converts @e device Y coordinate to logical coordinate, using the current
 172         mapping mode, user scale factor, device origin and axis orientation.
 173     */
 174     wxCoord DeviceToLogicalY(wxCoord y) const;
 175
 176     /**
 177         Convert @e device Y coordinate to relative logical coordinate, using the
 178         current mapping mode and user scale factor but ignoring the
 179         axis orientation. Use this for converting a height, for example.
 180     */
 181     wxCoord DeviceToLogicalYRel(wxCoord y) const;
 182
 183     /**
 184         Converts logical X coordinate to device coordinate, using the current
 185         mapping mode, user scale factor, device origin and axis orientation.
 186     */
 187     wxCoord LogicalToDeviceX(wxCoord x) const;
 188
 189     /**
 190         Converts logical X coordinate to relative device coordinate, using the
 191         current mapping mode and user scale factor but ignoring the
 192         axis orientation. Use this for converting a width, for example.
 193     */
 194     wxCoord LogicalToDeviceXRel(wxCoord x) const;
 195
 196     /**
 197         Converts logical Y coordinate to device coordinate, using the current
 198         mapping mode, user scale factor, device origin and axis orientation.
 199     */
 200     wxCoord LogicalToDeviceY(wxCoord y) const;
 201
 202     /**
 203         Converts logical Y coordinate to relative device coordinate, using the
 204         current mapping mode and user scale factor but ignoring the
 205         axis orientation. Use this for converting a height, for example.
 206     */
 207     wxCoord LogicalToDeviceYRel(wxCoord y) const;
 208
 209     //@}
 210
 211
 212
 213     /**
 214         @name Drawing functions
 215     */
 216     //@{
 217
 218     /**
 219         Clears the device context using the current background brush.
 220     */
 221     void Clear();
 222
 223     /**
 224         Draws an arc of a circle, centred on (@a xc, @a yc), with starting
 225         point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is
 226         used for the outline and the current brush for filling the shape.
 227
 228         The arc is drawn in a counter-clockwise direction from the start point
 229         to the end point.
 230     */
 231     void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
 232                  wxCoord xc, wxCoord yc);
 233
 234     /**
 235         Draw a bitmap on the device context at the specified point. If
 236         @a transparent is @true and the bitmap has a transparency mask, the
 237         bitmap will be drawn transparently.
 238
 239         When drawing a mono-bitmap, the current text foreground colour will be
 240         used to draw the foreground of the bitmap (all bits set to 1), and the
 241         current text background colour to draw the background (all bits set to
 242         0).
 243
 244         @see SetTextForeground(), SetTextBackground(), wxMemoryDC
 245     */
 246     void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
 247                     bool useMask = false);
 248
 249     /**
 250         Draws a check mark inside the given rectangle.
 251     */
 252     void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 253
 254     /**
 255         @overload
 256     */
 257     void DrawCheckMark(const wxRect& rect);
 258
 259     /**
 260         Draws a circle with the given centre and radius.
 261
 262         @see DrawEllipse()
 263     */
 264     void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);
 265
 266     /**
 267         @overload
 268     */
 269     void DrawCircle(const wxPoint& pt, wxCoord radius);
 270
 271     /**
 272         Draws an ellipse contained in the rectangle specified either with the
 273         given top left corner and the given size or directly. The current pen
 274         is used for the outline and the current brush for filling the shape.
 275
 276         @see DrawCircle()
 277     */
 278     void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 279
 280     /**
 281         @overload
 282     */
 283     void DrawEllipse(const wxPoint& pt, const wxSize& size);
 284
 285     /**
 286         @overload
 287     */
 288     void DrawEllipse(const wxRect& rect);
 289
 290     /**
 291         Draws an arc of an ellipse. The current pen is used for drawing the arc
 292         and the current brush is used for drawing the pie.
 293
 294         @a x and @a y specify the x and y coordinates of the upper-left corner
 295         of the rectangle that contains the ellipse.
 296
 297         @a width and @a height specify the width and height of the rectangle
 298         that contains the ellipse.
 299
 300         @a start and @a end specify the start and end of the arc relative to
 301         the three-o'clock position from the center of the rectangle. Angles are
 302         specified in degrees (360 is a complete circle). Positive values mean
 303         counter-clockwise motion. If @a start is equal to @e end, a complete
 304         ellipse will be drawn.
 305     */
 306     void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height,
 307                           double start, double end);
 308
 309     /**
 310         Draw an icon on the display (does nothing if the device context is
 311         PostScript). This can be the simplest way of drawing bitmaps on a
 312         window.
 313     */
 314     void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
 315
 316     /**
 317         Draw optional bitmap and the text into the given rectangle and aligns
 318         it as specified by alignment parameter; it also will emphasize the
 319         character with the given index if it is != -1 and return the bounding
 320         rectangle if required.
 321     */
 322     void DrawLabel(const wxString& text, const wxBitmap& image,
 323                    const wxRect& rect,
 324                    int alignment = wxALIGN_LEFT | wxALIGN_TOP,
 325                    int indexAccel = -1, wxRect* rectBounding = NULL);
 326
 327     /**
 328         @overload
 329     */
 330     void DrawLabel(const wxString& text, const wxRect& rect,
 331                    int alignment = wxALIGN_LEFT | wxALIGN_TOP,
 332                    int indexAccel = -1);
 333
 334     /**
 335         Draws a line from the first point to the second. The current pen is
 336         used for drawing the line. Note that the point (@a x2, @a y2) is not
 337         part of the line and is not drawn by this function (this is consistent
 338         with the behaviour of many other toolkits).
 339     */
 340     void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
 341
 342     /**
 343         Draws lines using an array of points of size @a n adding the optional
 344         offset coordinate. The current pen is used for drawing the lines.
 345
 346         @beginWxPythonOnly
 347         The wxPython version of this method accepts a Python list of wxPoint
 348         objects.
 349         @endWxPythonOnly
 350
 351         @beginWxPerlOnly
 352         Not supported by wxPerl.
 353         @endWxPerlOnly
 354     */
 355     void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
 356                    wxCoord yoffset = 0);
 357     /**
 358         This method uses a list of wxPoints, adding the optional offset
 359         coordinate. The programmer is responsible for deleting the list of
 360         points.
 361
 362         @beginWxPythonOnly
 363         The wxPython version of this method accepts a Python list of wxPoint
 364         objects.
 365         @endWxPythonOnly
 366
 367         @beginWxPerlOnly
 368         The wxPerl version of this method accepts
 369         as its first parameter a reference to an array
 370         of wxPoint objects.
 371         @endWxPerlOnly
 372     */
 373     void DrawLines(const wxPointList* points,
 374                    wxCoord xoffset = 0, wxCoord yoffset = 0);
 375
 376     /**
 377         Draws a point using the color of the current pen. Note that the other
 378         properties of the pen are not used, such as width.
 379     */
 380     void DrawPoint(wxCoord x, wxCoord y);
 381
 382     /**
 383         Draws a filled polygon using an array of points of size @a n, adding
 384         the optional offset coordinate. The first and last points are
 385         automatically closed.
 386
 387         The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
 388         default) or @b wxWINDING_RULE.
 389
 390         The current pen is used for drawing the outline, and the current brush
 391         for filling the shape. Using a transparent brush suppresses filling.
 392
 393         @beginWxPerlOnly
 394         Not supported by wxPerl.
 395         @endWxPerlOnly
 396     */
 397     void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
 398                      wxCoord yoffset = 0,
 399                      wxPolygonFillMode fill_style = wxODDEVEN_RULE);
 400     /**
 401         This method draws a filled polygon using a list of wxPoints, adding the
 402         optional offset coordinate. The first and last points are automatically
 403         closed.
 404
 405         The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
 406         default) or @b wxWINDING_RULE.
 407
 408         The current pen is used for drawing the outline, and the current brush
 409         for filling the shape. Using a transparent brush suppresses filling.
 410
 411         The programmer is responsible for deleting the list of points.
 412
 413         @beginWxPythonOnly
 414         The wxPython version of this method accepts a Python list of wxPoint
 415         objects.
 416         @endWxPythonOnly
 417
 418         @beginWxPerlOnly
 419         The wxPerl version of this method accepts
 420         as its first parameter a reference to an array
 421         of wxPoint objects.
 422         @endWxPerlOnly
 423     */
 424     void DrawPolygon(const wxPointList* points,
 425                      wxCoord xoffset = 0, wxCoord yoffset = 0,
 426                      wxPolygonFillMode fill_style = wxODDEVEN_RULE);
 427
 428     /**
 429         Draws two or more filled polygons using an array of @a points, adding
 430         the optional offset coordinates.
 431
 432         Notice that for the platforms providing a native implementation of this
 433         function (Windows and PostScript-based wxDC currently), this is more
 434         efficient than using DrawPolygon() in a loop.
 435
 436         @a n specifies the number of polygons to draw, the array @e count of
 437         size @a n specifies the number of points in each of the polygons in the
 438         @a points array.
 439
 440         The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
 441         default) or @b wxWINDING_RULE.
 442
 443         The current pen is used for drawing the outline, and the current brush
 444         for filling the shape. Using a transparent brush suppresses filling.
 445
 446         The polygons maybe disjoint or overlapping. Each polygon specified in a
 447         call to DrawPolyPolygon() must be closed. Unlike polygons created by
 448         the DrawPolygon() member function, the polygons created by this
 449         method are not closed automatically.
 450
 451         @beginWxPythonOnly
 452         Not implemented yet.
 453         @endWxPythonOnly
 454     */
 455     void DrawPolyPolygon(int n, int count[], wxPoint points[],
 456                          wxCoord xoffset = 0, wxCoord yoffset = 0,
 457                          wxPolygonFillMode fill_style = wxODDEVEN_RULE);
 458
 459     /**
 460         Draws a rectangle with the given top left corner, and with the given
 461         size.  The current pen is used for the outline and the current brush
 462         for filling the shape.
 463     */
 464     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 465
 466     /**
 467         Draws the text rotated by @a angle degrees
 468         (positive angles are counterclockwise; the full angle is 360 degrees).
 469
 470         @note Under Win9x only TrueType fonts can be drawn by this function. In
 471               particular, a font different from @c wxNORMAL_FONT should be used
 472               as the latter is not a TrueType font. @c wxSWISS_FONT is an
 473               example of a font which is.
 474
 475         @see DrawText()
 476     */
 477     void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
 478                          double angle);
 479
 480     /**
 481         Draws a rectangle with the given top left corner, and with the given
 482         size. The corners are quarter-circles using the given radius. The
 483         current pen is used for the outline and the current brush for filling
 484         the shape.
 485
 486         If @a radius is positive, the value is assumed to be the radius of the
 487         rounded corner. If @a radius is negative, the absolute value is assumed
 488         to be the @e proportion of the smallest dimension of the rectangle.
 489         This means that the corner can be a sensible size relative to the size
 490         of the rectangle, and also avoids the strange effects X produces when
 491         the corners are too big for the rectangle.
 492     */
 493     void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
 494                               wxCoord height, double radius);
 495
 496     /**
 497         Draws a spline between all given points using the current pen.
 498
 499         @beginWxPythonOnly
 500         The wxPython version of this method accepts a Python list of wxPoint
 501         objects.
 502         @endWxPythonOnly
 503
 504         @beginWxPerlOnly
 505         Not supported by wxPerl.
 506         @endWxPerlOnly
 507     */
 508     void DrawSpline(int n, wxPoint points[]);
 509
 510     /**
 511         @overload
 512
 513
 514         @beginWxPerlOnly
 515         The wxPerl version of this method accepts
 516         as its first parameter a reference to an array
 517         of wxPoint objects.
 518         @endWxPerlOnly
 519     */
 520     void DrawSpline(const wxPointList* points);
 521
 522     /**
 523         @overload
 524
 525
 526         @beginWxPerlOnly
 527         Not supported by wxPerl.
 528         @endWxPerlOnly
 529     */
 530     void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
 531                     wxCoord x3, wxCoord y3);
 532
 533     /**
 534         Draws a text string at the specified point, using the current text
 535         font, and the current text foreground and background colours.
 536
 537         The coordinates refer to the top-left corner of the rectangle bounding
 538         the string. See GetTextExtent() for how to get the dimensions of a text
 539         string, which can be used to position the text more precisely.
 540
 541         @note The current @ref GetLogicalFunction() "logical function" is
 542               ignored by this function.
 543     */
 544     void DrawText(const wxString& text, wxCoord x, wxCoord y);
 545
 546     /**
 547         Fill the area specified by rect with a radial gradient, starting from
 548         @a initialColour at the centre of the circle and fading to
 549         @a destColour on the circle outside.
 550
 551         The circle is placed at the centre of @a rect.
 552
 553         @note Currently this function is very slow, don't use it for real-time
 554               drawing.
 555     */
 556     void GradientFillConcentric(const wxRect& rect,
 557                                 const wxColour& initialColour,
 558                                 const wxColour& destColour);
 559
 560     /**
 561         Fill the area specified by rect with a radial gradient, starting from
 562         @a initialColour at the centre of the circle and fading to
 563         @a destColour on the circle outside.
 564
 565         @a circleCenter are the relative coordinates of centre of the circle in
 566         the specified @a rect.
 567
 568         @note Currently this function is very slow, don't use it for real-time
 569               drawing.
 570     */
 571     void GradientFillConcentric(const wxRect& rect,
 572                                 const wxColour& initialColour,
 573                                 const wxColour& destColour,
 574                                 const wxPoint& circleCenter);
 575
 576     /**
 577         Fill the area specified by @a rect with a linear gradient, starting
 578         from @a initialColour and eventually fading to @e destColour.
 579
 580         The @a nDirection specifies the direction of the colour change, default is
 581         to use @a initialColour on the left part of the rectangle and
 582         @a destColour on the right one.
 583     */
 584     void GradientFillLinear(const wxRect& rect, const wxColour& initialColour,
 585                             const wxColour& destColour,
 586                             wxDirection nDirection = wxRIGHT);
 587
 588     /**
 589         Flood fills the device context starting from the given point, using
 590         the current brush colour, and using a style:
 591
 592         - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
 593           given colour is encountered.
 594         - wxFLOOD_BORDER: The area to be flooded is bounded by the given
 595           colour.
 596
 597         @return @false if the operation failed.
 598
 599         @note The present implementation for non-Windows platforms may fail to
 600               find colour borders if the pixels do not match the colour
 601               exactly. However the function will still return @true.
 602     */
 603     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
 604                    wxFloodFillStyle style = wxFLOOD_SURFACE);
 605
 606     /**
 607         Displays a cross hair using the current pen. This is a vertical and
 608         horizontal line the height and width of the window, centred on the
 609         given point.
 610     */
 611     void CrossHair(wxCoord x, wxCoord y);
 612
 613     //@}
 614
 615
 616     /**
 617         @name Clipping region functions
 618     */
 619     //@{
 620
 621     /**
 622         Destroys the current clipping region so that none of the DC is clipped.
 623
 624         @see SetClippingRegion()
 625     */
 626     void DestroyClippingRegion();
 627
 628     /**
 629         Gets the rectangle surrounding the current clipping region.
 630
 631         @beginWxPythonOnly
 632         No arguments are required and the four values defining the rectangle
 633         are returned as a tuple.
 634         @endWxPythonOnly
 635     */
 636     void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const;
 637
 638     /**
 639         Sets the clipping region for this device context to the intersection of
 640         the given region described by the parameters of this method and the
 641         previously set clipping region.
 642
 643         The clipping region is an area to which drawing is restricted. Possible
 644         uses for the clipping region are for clipping text or for speeding up
 645         window redraws when only a known area of the screen is damaged.
 646
 647         Notice that you need to call DestroyClippingRegion() if you want to set
 648         the clipping region exactly to the region specified.
 649
 650         Also note that if the clipping region is empty, any previously set
 651         clipping region is destroyed, i.e. it is equivalent to calling
 652         DestroyClippingRegion(), and not to clipping out all drawing on the DC
 653         as might be expected.
 654
 655         @see DestroyClippingRegion(), wxRegion
 656     */
 657     void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 658
 659     /**
 660         @overload
 661     */
 662     void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
 663
 664     /**
 665         @overload
 666     */
 667     void SetClippingRegion(const wxRect& rect);
 668
 669     /**
 670         Sets the clipping region for this device context.
 671
 672         Unlike SetClippingRegion(), this function works with physical
 673         coordinates and not with the logical ones.
 674      */
 675     void SetDeviceClippingRegion(const wxRegion& region);
 676
 677     //@}
 678
 679
 680     /**
 681         @name Text/character extent functions
 682     */
 683     //@{
 684
 685     /**
 686         Gets the character height of the currently set font.
 687     */
 688     wxCoord GetCharHeight() const;
 689
 690     /**
 691         Gets the average character width of the currently set font.
 692     */
 693     wxCoord GetCharWidth() const;
 694
 695     /**
 696         Gets the dimensions of the string using the currently selected font.
 697         @a string is the text string to measure, @e heightLine, if non @NULL,
 698         is where to store the height of a single line.
 699
 700         The text extent is set in the given @a w and @a h pointers.
 701
 702         If the optional parameter @a font is specified and valid, then it is
 703         used for the text extent calculation, otherwise the currently selected
 704         font is used.
 705
 706         @note This function works with both single-line and multi-line strings.
 707
 708         @beginWxPerlOnly
 709         In wxPerl this method is implemented as
 710         GetMultiLineTextExtent(string, font = undef) returning a
 711         3-element list (width, height, line_height)
 712         @endWxPerlOnly
 713
 714         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
 715     */
 716     void GetMultiLineTextExtent(const wxString& string, wxCoord* w,
 717                                 wxCoord* h,
 718                                 wxCoord* heightLine = NULL,
 719                                 const wxFont* font = NULL) const;
 720     /**
 721         Gets the dimensions of the string using the currently selected font.
 722         @a string is the text string to measure, @e heightLine, if non @NULL,
 723         is where to store the height of a single line.
 724
 725         @return The text extent as a wxSize object.
 726
 727         @note This function works with both single-line and multi-line strings.
 728
 729         @beginWxPerlOnly
 730         Not supported by wxPerl.
 731         @endWxPerlOnly
 732
 733         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
 734     */
 735     wxSize GetMultiLineTextExtent(const wxString& string) const;
 736
 737     /**
 738         Fills the @a widths array with the widths from the beginning of @a text
 739         to the corresponding character of @a text. The generic version simply
 740         builds a running total of the widths of each character using
 741         GetTextExtent(), however if the various platforms have a native API
 742         function that is faster or more accurate than the generic
 743         implementation then it should be used instead.
 744
 745         @beginWxPythonOnly
 746         This method only takes the @a text parameter and returns a Python list
 747         of integers.
 748         @endWxPythonOnly
 749
 750         @beginWxPerlOnly
 751         In wxPerl this method only takes the @a text parameter and
 752         returns the widths as a list of integers.
 753         @endWxPerlOnly
 754
 755         @see GetMultiLineTextExtent(), GetTextExtent()
 756     */
 757     bool GetPartialTextExtents(const wxString& text,
 758                                wxArrayInt& widths) const;
 759
 760     /**
 761         Gets the dimensions of the string using the currently selected font.
 762         @a string is the text string to measure, @a descent is the dimension
 763         from the baseline of the font to the bottom of the descender, and
 764         @a externalLeading is any extra vertical space added to the font by the
 765         font designer (usually is zero).
 766
 767         The text extent is returned in @a w and @a h pointers or as a wxSize
 768         object depending on which version of this function is used.
 769
 770         If the optional parameter @a font is specified and valid, then it is
 771         used for the text extent calculation. Otherwise the currently selected
 772         font is.
 773
 774         @note This function only works with single-line strings.
 775
 776         @beginWxPythonOnly
 777         The following methods are implemented in wxPython:
 778         - GetTextExtent(string) - Returns a 2-tuple, (width, height).
 779         - GetFullTextExtent(string, font=NULL) -
 780             Returns a 4-tuple, (width, height, descent, externalLeading).
 781         @endWxPythonOnly
 782
 783         @beginWxPerlOnly
 784         In wxPerl this method is implemented as GetTextExtent(string,
 785         font = undef) returning a 4-element list (width, height,
 786         descent, externalLeading)
 787         @endWxPerlOnly
 788
 789         @see wxFont, SetFont(), GetPartialTextExtents(),
 790              GetMultiLineTextExtent()
 791     */
 792     void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
 793                        wxCoord* descent = NULL,
 794                        wxCoord* externalLeading = NULL,
 795                        const wxFont* font = NULL) const;
 796
 797     /**
 798         @overload
 799
 800
 801         @beginWxPerlOnly
 802         Not supported by wxPerl.
 803         @endWxPerlOnly
 804     */
 805     wxSize GetTextExtent(const wxString& string) const;
 806
 807     //@}
 808
 809
 810     /**
 811         @name Text properties functions
 812     */
 813     //@{
 814
 815     /**
 816         Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
 817
 818         @see SetBackgroundMode()
 819     */
 820     int GetBackgroundMode() const;
 821
 822     /**
 823         Gets the current font.
 824
 825         Notice that even although each device context object has some default font
 826         after creation, this method would return a ::wxNullFont initially and only
 827         after calling SetFont() a valid font is returned.
 828     */
 829     const wxFont& GetFont() const;
 830
 831     /**
 832         Gets the current layout direction of the device context. On platforms
 833         where RTL layout is supported, the return value will either be
 834         @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
 835         not supported, the return value will be @c wxLayout_Default.
 836
 837         @see SetLayoutDirection()
 838     */
 839     wxLayoutDirection GetLayoutDirection() const;
 840
 841     /**
 842         Gets the current text background colour.
 843
 844         @see SetTextBackground()
 845     */
 846     const wxColour& GetTextBackground() const;
 847
 848     /**
 849         Gets the current text foreground colour.
 850
 851         @see SetTextForeground()
 852     */
 853     const wxColour& GetTextForeground() const;
 854
 855     /**
 856         @a mode may be one of @c wxSOLID and @c wxTRANSPARENT.
 857
 858         This setting determines whether text will be drawn with a background
 859         colour or not.
 860     */
 861     void SetBackgroundMode(int mode);
 862
 863     /**
 864         Sets the current font for the DC.
 865
 866         If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk),
 867         the current font is selected out of the device context (leaving wxDC without
 868         any valid font), allowing the current font to be destroyed safely.
 869
 870         @see wxFont
 871     */
 872     void SetFont(const wxFont& font);
 873
 874     /**
 875         Sets the current text background colour for the DC.
 876     */
 877     void SetTextBackground(const wxColour& colour);
 878
 879     /**
 880         Sets the current text foreground colour for the DC.
 881
 882         @see wxMemoryDC for the interpretation of colours when drawing into a
 883              monochrome bitmap.
 884     */
 885     void SetTextForeground(const wxColour& colour);
 886
 887     /**
 888         Sets the current layout direction for the device context.
 889
 890         @param dir
 891            May be either @c wxLayout_Default, @c wxLayout_LeftToRight or
 892            @c wxLayout_RightToLeft.
 893
 894         @see GetLayoutDirection()
 895     */
 896     void SetLayoutDirection(wxLayoutDirection dir);
 897
 898     //@}
 899
 900
 901     /**
 902         @name Bounding box functions
 903     */
 904     //@{
 905
 906     /**
 907         Adds the specified point to the bounding box which can be retrieved
 908         with MinX(), MaxX() and MinY(), MaxY() functions.
 909
 910         @see ResetBoundingBox()
 911     */
 912     void CalcBoundingBox(wxCoord x, wxCoord y);
 913
 914     /**
 915         Gets the maximum horizontal extent used in drawing commands so far.
 916     */
 917     wxCoord MaxX() const;
 918
 919     /**
 920         Gets the maximum vertical extent used in drawing commands so far.
 921     */
 922     wxCoord MaxY() const;
 923
 924     /**
 925         Gets the minimum horizontal extent used in drawing commands so far.
 926     */
 927     wxCoord MinX() const;
 928
 929     /**
 930         Gets the minimum vertical extent used in drawing commands so far.
 931     */
 932     wxCoord MinY() const;
 933
 934     /**
 935         Resets the bounding box: after a call to this function, the bounding
 936         box doesn't contain anything.
 937
 938         @see CalcBoundingBox()
 939     */
 940     void ResetBoundingBox();
 941
 942     //@}
 943
 944
 945     /**
 946         @name Page and document start/end functions
 947     */
 948     //@{
 949
 950     /**
 951         Starts a document (only relevant when outputting to a printer).
 952         @a message is a message to show while printing.
 953     */
 954     bool StartDoc(const wxString& message);
 955
 956     /**
 957         Starts a document page (only relevant when outputting to a printer).
 958     */
 959     void StartPage();
 960
 961     /**
 962         Ends a document (only relevant when outputting to a printer).
 963     */
 964     void EndDoc();
 965
 966     /**
 967         Ends a document page (only relevant when outputting to a printer).
 968     */
 969     void EndPage();
 970
 971     //@}
 972
 973
 974     /**
 975         @name Bit-Block Transfer operations (blit)
 976     */
 977     //@{
 978
 979     /**
 980         Copy from a source DC to this DC, specifying the destination
 981         coordinates, size of area to copy, source DC, source coordinates,
 982         logical function, whether to use a bitmap mask, and mask source
 983         position.
 984
 985         @param xdest
 986             Destination device context x position.
 987         @param ydest
 988             Destination device context y position.
 989         @param width
 990             Width of source area to be copied.
 991         @param height
 992             Height of source area to be copied.
 993         @param source
 994             Source device context.
 995         @param xsrc
 996             Source device context x position.
 997         @param ysrc
 998             Source device context y position.
 999         @param logicalFunc
1000             Logical function to use, see SetLogicalFunction().
1001         @param useMask
1002             If @true, Blit does a transparent blit using the mask that is
1003             associated with the bitmap selected into the source device context.
1004             The Windows implementation does the following if MaskBlt cannot be
1005             used:
1006             <ol>
1007             <li>Creates a temporary bitmap and copies the destination area into
1008                 it.</li>
1009             <li>Copies the source area into the temporary bitmap using the
1010                 specified logical function.</li>
1011             <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1012                 the mask bitmap with the temp bitmap with the foreground colour
1013                 set to WHITE and the bg colour set to BLACK.</li>
1014             <li>Sets the unmasked area in the destination area to BLACK by
1015                 ANDing the mask bitmap with the destination area with the
1016                 foreground colour set to BLACK and the background colour set to
1017                 WHITE.</li>
1018             <li>ORs the temporary bitmap with the destination area.</li>
1019             <li>Deletes the temporary bitmap.</li>
1020             </ol>
1021             This sequence of operations ensures that the source's transparent
1022             area need not be black, and logical functions are supported.
1023             @n @b Note: on Windows, blitting with masks can be speeded up
1024             considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
1025             enabled. You can also influence whether MaskBlt or the explicit
1026             mask blitting code above is used, by using wxSystemOptions and
1027             setting the @c no-maskblt option to 1.
1028         @param xsrcMask
1029             Source x position on the mask. If both xsrcMask and ysrcMask are
1030             @c -1, xsrc and ysrc will be assumed for the mask source position.
1031             Currently only implemented on Windows.
1032         @param ysrcMask
1033             Source y position on the mask. If both xsrcMask and ysrcMask are
1034             @c -1, xsrc and ysrc will be assumed for the mask source position.
1035             Currently only implemented on Windows.
1036
1037         @remarks There is partial support for Blit() in wxPostScriptDC, under X.
1038
1039         @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
1040     */
1041     bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width,
1042               wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc,
1043               wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false,
1044               wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord);
1045
1046     /**
1047         Copy from a source DC to this DC, specifying the destination
1048         coordinates, destination size, source DC, source coordinates, size of
1049         source area to copy, logical function, whether to use a bitmap mask,
1050         and mask source position.
1051
1052         @param xdest
1053             Destination device context x position.
1054         @param ydest
1055             Destination device context y position.
1056         @param dstWidth
1057             Width of destination area.
1058         @param dstHeight
1059             Height of destination area.
1060         @param source
1061             Source device context.
1062         @param xsrc
1063             Source device context x position.
1064         @param ysrc
1065             Source device context y position.
1066         @param srcWidth
1067             Width of source area to be copied.
1068         @param srcHeight
1069             Height of source area to be copied.
1070         @param logicalFunc
1071             Logical function to use, see SetLogicalFunction().
1072         @param useMask
1073             If @true, Blit does a transparent blit using the mask that is
1074             associated with the bitmap selected into the source device context.
1075             The Windows implementation does the following if MaskBlt cannot be
1076             used:
1077             <ol>
1078             <li>Creates a temporary bitmap and copies the destination area into
1079                 it.</li>
1080             <li>Copies the source area into the temporary bitmap using the
1081                 specified logical function.</li>
1082             <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1083                 the mask bitmap with the temp bitmap with the foreground colour
1084                 set to WHITE and the bg colour set to BLACK.</li>
1085             <li>Sets the unmasked area in the destination area to BLACK by
1086                 ANDing the mask bitmap with the destination area with the
1087                 foreground colour set to BLACK and the background colour set to
1088                 WHITE.</li>
1089             <li>ORs the temporary bitmap with the destination area.</li>
1090             <li>Deletes the temporary bitmap.</li>
1091             </ol>
1092             This sequence of operations ensures that the source's transparent
1093             area need not be black, and logical functions are supported.
1094             @n @b Note: on Windows, blitting with masks can be speeded up
1095             considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
1096             enabled. You can also influence whether MaskBlt or the explicit
1097             mask blitting code above is used, by using wxSystemOptions and
1098             setting the @c no-maskblt option to 1.
1099         @param xsrcMask
1100             Source x position on the mask. If both xsrcMask and ysrcMask are
1101             wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1102             source position. Currently only implemented on Windows.
1103         @param ysrcMask
1104             Source y position on the mask. If both xsrcMask and ysrcMask are
1105             wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1106             source position. Currently only implemented on Windows.
1107
1108         There is partial support for Blit() in wxPostScriptDC, under X.
1109
1110         StretchBlit() is only implemented under wxMAC and wxMSW.
1111
1112         See wxMemoryDC for typical usage.
1113
1114         @since 2.9.0
1115
1116         @see Blit(), wxMemoryDC, wxBitmap, wxMask
1117     */
1118     bool StretchBlit(wxCoord xdest, wxCoord ydest,
1119                      wxCoord dstWidth, wxCoord dstHeight,
1120                      wxDC* source, wxCoord xsrc, wxCoord ysrc,
1121                      wxCoord srcWidth, wxCoord srcHeight,
1122                      wxRasterOperationMode logicalFunc = wxCOPY,
1123                      bool useMask = false,
1124                      wxCoord xsrcMask = wxDefaultCoord,
1125                      wxCoord ysrcMask = wxDefaultCoord);
1126     //@}
1127
1128
1129     /**
1130         @name Background/foreground brush and pen
1131     */
1132     //@{
1133
1134     /**
1135         Gets the brush used for painting the background.
1136
1137         @see wxDC::SetBackground()
1138     */
1139     const wxBrush& GetBackground() const;
1140
1141     /**
1142         Gets the current brush.
1143
1144         @see wxDC::SetBrush()
1145     */
1146     const wxBrush& GetBrush() const;
1147
1148     /**
1149         Gets the current pen.
1150
1151         @see SetPen()
1152     */
1153     const wxPen& GetPen() const;
1154
1155     /**
1156         Sets the current background brush for the DC.
1157     */
1158     void SetBackground(const wxBrush& brush);
1159
1160     /**
1161         Sets the current brush for the DC.
1162
1163         If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk),
1164         the current brush is selected out of the device context (leaving wxDC without
1165         any valid brush), allowing the current brush to be destroyed safely.
1166
1167         @see wxBrush, wxMemoryDC (for the interpretation of colours when
1168              drawing into a monochrome bitmap)
1169     */
1170     void SetBrush(const wxBrush& brush);
1171
1172     /**
1173         Sets the current pen for the DC.
1174
1175         If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk),
1176         the current pen is selected out of the device context (leaving wxDC without any
1177         valid pen), allowing the current pen to be destroyed safely.
1178
1179         @see wxMemoryDC for the interpretation of colours when drawing into a
1180              monochrome bitmap.
1181     */
1182     void SetPen(const wxPen& pen);
1183
1184     //@}
1185
1186
1187     /**
1188         Copy attributes from another DC.
1189
1190         The copied attributes currently are:
1191             - Font
1192             - Text foreground and background colours
1193             - Background brush
1194             - Layout direction
1195
1196         @param dc
1197             A valid (i.e. its IsOk() must return @true) source device context.
1198      */
1199     void CopyAttributes(const wxDC& dc);
1200
1201     /**
1202         Returns the depth (number of bits/pixel) of this DC.
1203
1204         @see wxDisplayDepth()
1205     */
1206     int GetDepth() const;
1207
1208     /**
1209         Returns the current device origin.
1210
1211         @see SetDeviceOrigin()
1212     */
1213     wxPoint GetDeviceOrigin() const;
1214
1215     /**
1216         Gets the current logical function.
1217
1218         @see SetLogicalFunction()
1219     */
1220     wxRasterOperationMode GetLogicalFunction() const;
1221
1222     /**
1223         Gets the current mapping mode for the device context.
1224
1225         @see SetMapMode()
1226     */
1227     wxMappingMode GetMapMode() const;
1228
1229     /**
1230         Gets in @a colour the colour at the specified location. Not available
1231         for wxPostScriptDC or wxMetafileDC.
1232
1233         @note Setting a pixel can be done using DrawPoint().
1234
1235         @beginWxPythonOnly
1236         The wxColour value is returned and is not required as a parameter.
1237         @endWxPythonOnly
1238     */
1239     bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
1240
1241     /**
1242         Returns the resolution of the device in pixels per inch.
1243     */
1244     wxSize GetPPI() const;
1245
1246     /**
1247         Gets the horizontal and vertical extent of this device context in @e device units.
1248         It can be used to scale graphics to fit the page.
1249
1250         For example, if @e maxX and @e maxY represent the maximum horizontal
1251         and vertical 'pixel' values used in your application, the following
1252         code will scale the graphic to fit on the printer page:
1253
1254         @code
1255         wxCoord w, h;
1256         dc.GetSize(&w, &h);
1257         double scaleX = (double)(maxX / w);
1258         double scaleY = (double)(maxY / h);
1259         dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
1260         @endcode
1261
1262         @beginWxPythonOnly
1263         In place of a single overloaded method name, wxPython implements the
1264         following methods:
1265         - GetSize() - Returns a wxSize.
1266         - GetSizeWH() - Returns a 2-tuple (width, height).
1267         @endWxPythonOnly
1268
1269         @beginWxPerlOnly
1270         In wxPerl there are two methods instead of a single overloaded
1271         method:
1272         - GetSize(): returns a Wx::Size object.
1273         - GetSizeWH(): returns a 2-element list (width, height).
1274         @endWxPerlOnly
1275     */
1276     void GetSize(wxCoord* width, wxCoord* height) const;
1277
1278     /**
1279         @overload
1280     */
1281     wxSize GetSize() const;
1282
1283     /**
1284         Returns the horizontal and vertical resolution in millimetres.
1285     */
1286     void GetSizeMM(wxCoord* width, wxCoord* height) const;
1287
1288     /**
1289         @overload
1290     */
1291     wxSize GetSizeMM() const;
1292
1293     /**
1294         Gets the current user scale factor.
1295
1296         @beginWxPerlOnly
1297         In wxPerl this method takes no arguments and return a two
1298         element array (x, y).
1299         @endWxPerlOnly
1300
1301         @see SetUserScale()
1302     */
1303     void GetUserScale(double* x, double* y) const;
1304
1305     /**
1306         Returns @true if the DC is ok to use.
1307     */
1308     bool IsOk() const;
1309
1310     /**
1311         Sets the x and y axis orientation (i.e., the direction from lowest to
1312         highest values on the axis). The default orientation is x axis from
1313         left to right and y axis from top down.
1314
1315         @param xLeftRight
1316             True to set the x axis orientation to the natural left to right
1317             orientation, @false to invert it.
1318         @param yBottomUp
1319             True to set the y axis orientation to the natural bottom up
1320             orientation, @false to invert it.
1321     */
1322     void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
1323
1324     /**
1325         Sets the device origin (i.e., the origin in pixels after scaling has
1326         been applied). This function may be useful in Windows printing
1327         operations for placing a graphic on a page.
1328     */
1329     void SetDeviceOrigin(wxCoord x, wxCoord y);
1330
1331     /**
1332         Sets the current logical function for the device context.
1333         It determines how a @e source pixel (from a pen or brush colour, or source
1334         device context if using Blit()) combines with a @e destination pixel in
1335         the current device context.
1336         Text drawing is not affected by this function.
1337
1338         See ::wxRasterOperationMode enumeration values for more info.
1339
1340         The default is @c wxCOPY, which simply draws with the current colour.
1341         The others combine the current colour and the background using a logical
1342         operation. @c wxINVERT is commonly used for drawing rubber bands or moving
1343         outlines, since drawing twice reverts to the original colour.
1344     */
1345     void SetLogicalFunction(wxRasterOperationMode function);
1346
1347     /**
1348         The mapping mode of the device context defines the unit of measurement
1349         used to convert @e logical units to @e device units.
1350
1351         Note that in X, text drawing isn't handled consistently with the mapping mode;
1352         a font is always specified in point size. However, setting the user scale (see
1353         SetUserScale()) scales the text appropriately. In Windows, scalable
1354         TrueType fonts are always used; in X, results depend on availability of
1355         fonts, but usually a reasonable match is found.
1356
1357         The coordinate origin is always at the top left of the screen/printer.
1358
1359         Drawing to a Windows printer device context uses the current mapping
1360         mode, but mapping mode is currently ignored for PostScript output.
1361     */
1362     void SetMapMode(wxMappingMode mode);
1363
1364     /**
1365         If this is a window DC or memory DC, assigns the given palette to the
1366         window or bitmap associated with the DC. If the argument is
1367         ::wxNullPalette, the current palette is selected out of the device
1368         context, and the original palette restored.
1369
1370         @see wxPalette
1371     */
1372     void SetPalette(const wxPalette& palette);
1373
1374     /**
1375         Sets the user scaling factor, useful for applications which require
1376         'zooming'.
1377     */
1378     void SetUserScale(double xScale, double yScale);
1379 };
1380
1381
1382
1383 /**
1384     @class wxDCClipper
1385
1386     wxDCClipper is a small helper class for setting a clipping region on a wxDC
1387     and unsetting it automatically. An object of wxDCClipper class is typically
1388     created on the stack so that it is automatically destroyed when the object
1389     goes out of scope. A typical usage example:
1390
1391     @code
1392     void MyFunction(wxDC& dc)
1393     {
1394         wxDCClipper clip(dc, rect);
1395         // ... drawing functions here are affected by clipping rect ...
1396     }
1397
1398     void OtherFunction()
1399     {
1400         wxDC dc;
1401         MyFunction(dc);
1402         // ... drawing functions here are not affected by clipping rect ...
1403     }
1404     @endcode
1405
1406     @library{wxcore}
1407     @category{gdi}
1408
1409     @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1410          wxDCBrushChanger
1411 */
1412 class wxDCClipper
1413 {
1414 public:
1415     //@{
1416     /**
1417         Sets the clipping region to the specified region/coordinates.
1418
1419         The clipping region is automatically unset when this object is destroyed.
1420     */
1421     wxDCClipper(wxDC& dc, const wxRegion& r);
1422     wxDCClipper(wxDC& dc, const wxRect& rect);
1423     wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h);
1424     //@}
1425
1426     /**
1427         Destroys the clipping region associated with the DC passed to the ctor.
1428     */
1429     ~wxDCClipper();
1430 };
1431
1432
1433 /**
1434     @class wxDCBrushChanger
1435
1436     wxDCBrushChanger is a small helper class for setting a brush on a wxDC
1437     and unsetting it automatically in the destructor, restoring the previous one.
1438
1439     @library{wxcore}
1440     @category{gdi}
1441
1442     @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1443          wxDCClipper
1444 */
1445 class wxDCBrushChanger
1446 {
1447 public:
1448     /**
1449         Sets @a brush on the given @a dc, storing the old one.
1450
1451         @param dc
1452             The DC where the brush must be temporary set.
1453         @param brush
1454             The brush to set.
1455     */
1456     wxDCBrushChanger(wxDC& dc, const wxBrush& brush);
1457
1458     /**
1459         Restores the brush originally selected in the DC passed to the ctor.
1460     */
1461     ~wxDCBrushChanger();
1462 };
1463
1464
1465 /**
1466     @class wxDCPenChanger
1467
1468     wxDCPenChanger is a small helper class for setting a pen on a wxDC
1469     and unsetting it automatically in the destructor, restoring the previous one.
1470
1471     @library{wxcore}
1472     @category{gdi}
1473
1474     @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger,
1475          wxDCClipper
1476 */
1477 class wxDCPenChanger
1478 {
1479 public:
1480     /**
1481         Sets @a pen on the given @a dc, storing the old one.
1482
1483         @param dc
1484             The DC where the pen must be temporary set.
1485         @param pen
1486             The pen to set.
1487     */
1488     wxDCPenChanger(wxDC& dc, const wxPen& pen);
1489
1490     /**
1491         Restores the pen originally selected in the DC passed to the ctor.
1492     */
1493     ~wxDCPenChanger();
1494 };
1495
1496
1497
1498 /**
1499     @class wxDCTextColourChanger
1500
1501     wxDCTextColourChanger is a small helper class for setting a foreground
1502     text colour on a wxDC and unsetting it automatically in the destructor,
1503     restoring the previous one.
1504
1505     @library{wxcore}
1506     @category{gdi}
1507
1508     @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger,
1509          wxDCClipper
1510 */
1511 class wxDCTextColourChanger
1512 {
1513 public:
1514     /**
1515         Trivial constructor not changing anything.
1516
1517         This constructor is useful if you don't know beforehand if the colour
1518         needs to be changed or not. It simply creates the object which won't do
1519         anything in its destructor unless Set() is called -- in which case it
1520         would reset the previous colour.
1521      */
1522     wxDCTextColourChanger(wxDC& dc);
1523
1524     /**
1525         Sets @a col on the given @a dc, storing the old one.
1526
1527         @param dc
1528             The DC where the colour must be temporary set.
1529         @param col
1530             The colour to set.
1531     */
1532     wxDCTextColourChanger(wxDC& dc, const wxColour& col);
1533
1534     /**
1535         Set the colour to use.
1536
1537         This method is meant to be called once only and only on the objects
1538         created with the constructor overload not taking wxColour argument and
1539         has the same effect as the other constructor, i.e. sets the colour to
1540         the given @a col and ensures that the old value is restored when this
1541         object is destroyed.
1542      */
1543     void Set(const wxColour& col);
1544
1545     /**
1546         Restores the colour originally selected in the DC passed to the ctor.
1547     */
1548     ~wxDCTextColourChanger();
1549 };
1550
1551
1552
1553 /**
1554     @class wxDCFontChanger
1555
1556     wxDCFontChanger is a small helper class for setting a font on a wxDC and
1557     unsetting it automatically in the destructor, restoring the previous one.
1558
1559     @since 2.9.0
1560
1561     @library{wxcore}
1562     @category{gdi}
1563
1564     @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger,
1565          wxDCClipper
1566 */
1567 class wxDCFontChanger
1568 {
1569 public:
1570     /**
1571         Trivial constructor not changing anything.
1572
1573         This constructor is useful if you don't know beforehand if the font
1574         needs to be changed or not. It simply creates the object which won't do
1575         anything in its destructor unless Set() is called -- in which case it
1576         would reset the previous font.
1577
1578         @since 2.9.1
1579      */
1580     wxDCFontChanger(wxDC& dc);
1581
1582     /**
1583         Sets @a font on the given @a dc, storing the old one.
1584
1585         @param dc
1586             The DC where the font must be temporary set.
1587         @param font
1588             The font to set.
1589     */
1590     wxDCFontChanger(wxDC& dc, const wxFont& font);
1591
1592     /**
1593         Set the font to use.
1594
1595         This method is meant to be called once only and only on the objects
1596         created with the constructor overload not taking wxColour argument and
1597         has the same effect as the other constructor, i.e. sets the font to
1598         the given @a font and ensures that the old value is restored when this
1599         object is destroyed.
1600      */
1601     void Set(const wxFont& font);
1602
1603     /**
1604         Restores the font originally selected in the DC passed to the ctor.
1605     */
1606     ~wxDCFontChanger();
1607 };
1608