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     void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
 352                    wxCoord yoffset = 0);
 353     /**
 354         This method uses a list of wxPoints, adding the optional offset
 355         coordinate. The programmer is responsible for deleting the list of
 356         points.
 357
 358         @beginWxPythonOnly
 359         The wxPython version of this method accepts a Python list of wxPoint
 360         objects.
 361         @endWxPythonOnly
 362     */
 363     void DrawLines(const wxPointList* points,
 364                    wxCoord xoffset = 0, wxCoord yoffset = 0);
 365
 366     /**
 367         Draws a point using the color of the current pen. Note that the other
 368         properties of the pen are not used, such as width.
 369     */
 370     void DrawPoint(wxCoord x, wxCoord y);
 371
 372     /**
 373         Draws a filled polygon using an array of points of size @a n, adding
 374         the optional offset coordinate. The first and last points are
 375         automatically closed.
 376
 377         The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
 378         default) or @b wxWINDING_RULE.
 379
 380         The current pen is used for drawing the outline, and the current brush
 381         for filling the shape. Using a transparent brush suppresses filling.
 382     */
 383     void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
 384                      wxCoord yoffset = 0,
 385                      wxPolygonFillMode fill_style = wxODDEVEN_RULE);
 386     /**
 387         This method draws a filled polygon using a list of wxPoints, adding the
 388         optional offset coordinate. The first and last points are automatically
 389         closed.
 390
 391         The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
 392         default) or @b wxWINDING_RULE.
 393
 394         The current pen is used for drawing the outline, and the current brush
 395         for filling the shape. Using a transparent brush suppresses filling.
 396
 397         The programmer is responsible for deleting the list of points.
 398
 399         @beginWxPythonOnly
 400         The wxPython version of this method accepts a Python list of wxPoint
 401         objects.
 402         @endWxPythonOnly
 403     */
 404     void DrawPolygon(const wxPointList* points,
 405                      wxCoord xoffset = 0, wxCoord yoffset = 0,
 406                      wxPolygonFillMode fill_style = wxODDEVEN_RULE);
 407
 408     /**
 409         Draws two or more filled polygons using an array of @a points, adding
 410         the optional offset coordinates.
 411
 412         Notice that for the platforms providing a native implementation of this
 413         function (Windows and PostScript-based wxDC currently), this is more
 414         efficient than using DrawPolygon() in a loop.
 415
 416         @a n specifies the number of polygons to draw, the array @e count of
 417         size @a n specifies the number of points in each of the polygons in the
 418         @a points array.
 419
 420         The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
 421         default) or @b wxWINDING_RULE.
 422
 423         The current pen is used for drawing the outline, and the current brush
 424         for filling the shape. Using a transparent brush suppresses filling.
 425
 426         The polygons maybe disjoint or overlapping. Each polygon specified in a
 427         call to DrawPolyPolygon() must be closed. Unlike polygons created by
 428         the DrawPolygon() member function, the polygons created by this
 429         method are not closed automatically.
 430
 431         @beginWxPythonOnly
 432         Not implemented yet.
 433         @endWxPythonOnly
 434     */
 435     void DrawPolyPolygon(int n, int count[], wxPoint points[],
 436                          wxCoord xoffset = 0, wxCoord yoffset = 0,
 437                          wxPolygonFillMode fill_style = wxODDEVEN_RULE);
 438
 439     /**
 440         Draws a rectangle with the given top left corner, and with the given
 441         size.  The current pen is used for the outline and the current brush
 442         for filling the shape.
 443     */
 444     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 445
 446     /**
 447         Draws the text rotated by @a angle degrees
 448         (positive angles are counterclockwise; the full angle is 360 degrees).
 449
 450         @note Under Win9x only TrueType fonts can be drawn by this function. In
 451               particular, a font different from @c wxNORMAL_FONT should be used
 452               as the latter is not a TrueType font. @c wxSWISS_FONT is an
 453               example of a font which is.
 454
 455         @see DrawText()
 456     */
 457     void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
 458                          double angle);
 459
 460     /**
 461         Draws a rectangle with the given top left corner, and with the given
 462         size. The corners are quarter-circles using the given radius. The
 463         current pen is used for the outline and the current brush for filling
 464         the shape.
 465
 466         If @a radius is positive, the value is assumed to be the radius of the
 467         rounded corner. If @a radius is negative, the absolute value is assumed
 468         to be the @e proportion of the smallest dimension of the rectangle.
 469         This means that the corner can be a sensible size relative to the size
 470         of the rectangle, and also avoids the strange effects X produces when
 471         the corners are too big for the rectangle.
 472     */
 473     void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
 474                               wxCoord height, double radius);
 475
 476     /**
 477         Draws a spline between all given points using the current pen.
 478
 479         @beginWxPythonOnly
 480         The wxPython version of this method accepts a Python list of wxPoint
 481         objects.
 482         @endWxPythonOnly
 483     */
 484     void DrawSpline(int n, wxPoint points[]);
 485
 486     /**
 487         @overload
 488     */
 489     void DrawSpline(const wxPointList* points);
 490
 491     /**
 492         @overload
 493     */
 494     void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
 495                     wxCoord x3, wxCoord y3);
 496
 497     /**
 498         Draws a text string at the specified point, using the current text
 499         font, and the current text foreground and background colours.
 500
 501         The coordinates refer to the top-left corner of the rectangle bounding
 502         the string. See GetTextExtent() for how to get the dimensions of a text
 503         string, which can be used to position the text more precisely.
 504
 505         @note The current @ref GetLogicalFunction() "logical function" is
 506               ignored by this function.
 507     */
 508     void DrawText(const wxString& text, wxCoord x, wxCoord y);
 509
 510     /**
 511         Fill the area specified by rect with a radial gradient, starting from
 512         @a initialColour at the centre of the circle and fading to
 513         @a destColour on the circle outside.
 514
 515         The circle is placed at the centre of @a rect.
 516
 517         @note Currently this function is very slow, don't use it for real-time
 518               drawing.
 519     */
 520     void GradientFillConcentric(const wxRect& rect,
 521                                 const wxColour& initialColour,
 522                                 const wxColour& destColour);
 523
 524     /**
 525         Fill the area specified by rect with a radial gradient, starting from
 526         @a initialColour at the centre of the circle and fading to
 527         @a destColour on the circle outside.
 528
 529         @a circleCenter are the relative coordinates of centre of the circle in
 530         the specified @a rect.
 531
 532         @note Currently this function is very slow, don't use it for real-time
 533               drawing.
 534     */
 535     void GradientFillConcentric(const wxRect& rect,
 536                                 const wxColour& initialColour,
 537                                 const wxColour& destColour,
 538                                 const wxPoint& circleCenter);
 539
 540     /**
 541         Fill the area specified by @a rect with a linear gradient, starting
 542         from @a initialColour and eventually fading to @e destColour.
 543
 544         The @a nDirection specifies the direction of the colour change, default is
 545         to use @a initialColour on the left part of the rectangle and
 546         @a destColour on the right one.
 547     */
 548     void GradientFillLinear(const wxRect& rect, const wxColour& initialColour,
 549                             const wxColour& destColour,
 550                             wxDirection nDirection = wxRIGHT);
 551
 552     /**
 553         Flood fills the device context starting from the given point, using
 554         the current brush colour, and using a style:
 555
 556         - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
 557           given colour is encountered.
 558         - wxFLOOD_BORDER: The area to be flooded is bounded by the given
 559           colour.
 560
 561         @return @false if the operation failed.
 562
 563         @note The present implementation for non-Windows platforms may fail to
 564               find colour borders if the pixels do not match the colour
 565               exactly. However the function will still return @true.
 566     */
 567     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
 568                    wxFloodFillStyle style = wxFLOOD_SURFACE);
 569
 570     /**
 571         Displays a cross hair using the current pen. This is a vertical and
 572         horizontal line the height and width of the window, centred on the
 573         given point.
 574     */
 575     void CrossHair(wxCoord x, wxCoord y);
 576
 577     //@}
 578
 579
 580     /**
 581         @name Clipping region functions
 582     */
 583     //@{
 584
 585     /**
 586         Destroys the current clipping region so that none of the DC is clipped.
 587
 588         @see SetClippingRegion()
 589     */
 590     void DestroyClippingRegion();
 591
 592     /**
 593         Gets the rectangle surrounding the current clipping region.
 594
 595         @beginWxPythonOnly
 596         No arguments are required and the four values defining the rectangle
 597         are returned as a tuple.
 598         @endWxPythonOnly
 599     */
 600     void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const;
 601
 602     /**
 603         Sets the clipping region for this device context to the intersection of
 604         the given region described by the parameters of this method and the
 605         previously set clipping region.
 606
 607         The clipping region is an area to which drawing is restricted. Possible
 608         uses for the clipping region are for clipping text or for speeding up
 609         window redraws when only a known area of the screen is damaged.
 610
 611         Notice that you need to call DestroyClippingRegion() if you want to set
 612         the clipping region exactly to the region specified.
 613
 614         Also note that if the clipping region is empty, any previously set
 615         clipping region is destroyed, i.e. it is equivalent to calling
 616         DestroyClippingRegion(), and not to clipping out all drawing on the DC
 617         as might be expected.
 618
 619         @see DestroyClippingRegion(), wxRegion
 620     */
 621     void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 622
 623     /**
 624         @overload
 625     */
 626     void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
 627
 628     /**
 629         @overload
 630     */
 631     void SetClippingRegion(const wxRect& rect);
 632
 633     /**
 634         Sets the clipping region for this device context.
 635
 636         Unlike SetClippingRegion(), this function works with physical
 637         coordinates and not with the logical ones.
 638      */
 639     void SetDeviceClippingRegion(const wxRegion& region);
 640
 641     //@}
 642
 643
 644     /**
 645         @name Text/character extent functions
 646     */
 647     //@{
 648
 649     /**
 650         Gets the character height of the currently set font.
 651     */
 652     wxCoord GetCharHeight() const;
 653
 654     /**
 655         Gets the average character width of the currently set font.
 656     */
 657     wxCoord GetCharWidth() const;
 658
 659     /**
 660         Gets the dimensions of the string using the currently selected font.
 661         @a string is the text string to measure, @e heightLine, if non @NULL,
 662         is where to store the height of a single line.
 663
 664         The text extent is set in the given @a w and @a h pointers.
 665
 666         If the optional parameter @a font is specified and valid, then it is
 667         used for the text extent calculation, otherwise the currently selected
 668         font is used.
 669
 670         @note This function works with both single-line and multi-line strings.
 671
 672         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
 673     */
 674     void GetMultiLineTextExtent(const wxString& string, wxCoord* w,
 675                                 wxCoord* h,
 676                                 wxCoord* heightLine = NULL,
 677                                 const wxFont* font = NULL) const;
 678     /**
 679         Gets the dimensions of the string using the currently selected font.
 680         @a string is the text string to measure, @e heightLine, if non @NULL,
 681         is where to store the height of a single line.
 682
 683         @return The text extent as a wxSize object.
 684
 685         @note This function works with both single-line and multi-line strings.
 686
 687         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
 688     */
 689     wxSize GetMultiLineTextExtent(const wxString& string) const;
 690
 691     /**
 692         Fills the @a widths array with the widths from the beginning of @a text
 693         to the corresponding character of @a text. The generic version simply
 694         builds a running total of the widths of each character using
 695         GetTextExtent(), however if the various platforms have a native API
 696         function that is faster or more accurate than the generic
 697         implementation then it should be used instead.
 698
 699         @beginWxPythonOnly
 700         This method only takes the @a text parameter and returns a Python list
 701         of integers.
 702         @endWxPythonOnly
 703
 704         @see GetMultiLineTextExtent(), GetTextExtent()
 705     */
 706     bool GetPartialTextExtents(const wxString& text,
 707                                wxArrayInt& widths) const;
 708
 709     /**
 710         Gets the dimensions of the string using the currently selected font.
 711         @a string is the text string to measure, @a descent is the dimension
 712         from the baseline of the font to the bottom of the descender, and
 713         @a externalLeading is any extra vertical space added to the font by the
 714         font designer (usually is zero).
 715
 716         The text extent is returned in @a w and @a h pointers or as a wxSize
 717         object depending on which version of this function is used.
 718
 719         If the optional parameter @a font is specified and valid, then it is
 720         used for the text extent calculation. Otherwise the currently selected
 721         font is.
 722
 723         @note This function only works with single-line strings.
 724
 725         @beginWxPythonOnly
 726         The following methods are implemented in wxPython:
 727         - GetTextExtent(string) - Returns a 2-tuple, (width, height).
 728         - GetFullTextExtent(string, font=NULL) -
 729             Returns a 4-tuple, (width, height, descent, externalLeading).
 730         @endWxPythonOnly
 731
 732         @see wxFont, SetFont(), GetPartialTextExtents(),
 733              GetMultiLineTextExtent()
 734     */
 735     void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
 736                        wxCoord* descent = NULL,
 737                        wxCoord* externalLeading = NULL,
 738                        const wxFont* font = NULL) const;
 739
 740     /**
 741         @overload
 742     */
 743     wxSize GetTextExtent(const wxString& string) const;
 744
 745     //@}
 746
 747
 748     /**
 749         @name Text properties functions
 750     */
 751     //@{
 752
 753     /**
 754         Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
 755
 756         @see SetBackgroundMode()
 757     */
 758     int GetBackgroundMode() const;
 759
 760     /**
 761         Gets the current font.
 762
 763         Notice that even although each device context object has some default font
 764         after creation, this method would return a ::wxNullFont initially and only
 765         after calling SetFont() a valid font is returned.
 766     */
 767     const wxFont& GetFont() const;
 768
 769     /**
 770         Gets the current layout direction of the device context. On platforms
 771         where RTL layout is supported, the return value will either be
 772         @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
 773         not supported, the return value will be @c wxLayout_Default.
 774
 775         @see SetLayoutDirection()
 776     */
 777     wxLayoutDirection GetLayoutDirection() const;
 778
 779     /**
 780         Gets the current text background colour.
 781
 782         @see SetTextBackground()
 783     */
 784     const wxColour& GetTextBackground() const;
 785
 786     /**
 787         Gets the current text foreground colour.
 788
 789         @see SetTextForeground()
 790     */
 791     const wxColour& GetTextForeground() const;
 792
 793     /**
 794         @a mode may be one of @c wxSOLID and @c wxTRANSPARENT.
 795
 796         This setting determines whether text will be drawn with a background
 797         colour or not.
 798     */
 799     void SetBackgroundMode(int mode);
 800
 801     /**
 802         Sets the current font for the DC.
 803
 804         If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk),
 805         the current font is selected out of the device context (leaving wxDC without
 806         any valid font), allowing the current font to be destroyed safely.
 807
 808         @see wxFont
 809     */
 810     void SetFont(const wxFont& font);
 811
 812     /**
 813         Sets the current text background colour for the DC.
 814     */
 815     void SetTextBackground(const wxColour& colour);
 816
 817     /**
 818         Sets the current text foreground colour for the DC.
 819
 820         @see wxMemoryDC for the interpretation of colours when drawing into a
 821              monochrome bitmap.
 822     */
 823     void SetTextForeground(const wxColour& colour);
 824
 825     /**
 826         Sets the current layout direction for the device context.
 827
 828         @param dir
 829            May be either @c wxLayout_Default, @c wxLayout_LeftToRight or
 830            @c wxLayout_RightToLeft.
 831
 832         @see GetLayoutDirection()
 833     */
 834     void SetLayoutDirection(wxLayoutDirection dir);
 835
 836     //@}
 837
 838
 839     /**
 840         @name Bounding box functions
 841     */
 842     //@{
 843
 844     /**
 845         Adds the specified point to the bounding box which can be retrieved
 846         with MinX(), MaxX() and MinY(), MaxY() functions.
 847
 848         @see ResetBoundingBox()
 849     */
 850     void CalcBoundingBox(wxCoord x, wxCoord y);
 851
 852     /**
 853         Gets the maximum horizontal extent used in drawing commands so far.
 854     */
 855     wxCoord MaxX() const;
 856
 857     /**
 858         Gets the maximum vertical extent used in drawing commands so far.
 859     */
 860     wxCoord MaxY() const;
 861
 862     /**
 863         Gets the minimum horizontal extent used in drawing commands so far.
 864     */
 865     wxCoord MinX() const;
 866
 867     /**
 868         Gets the minimum vertical extent used in drawing commands so far.
 869     */
 870     wxCoord MinY() const;
 871
 872     /**
 873         Resets the bounding box: after a call to this function, the bounding
 874         box doesn't contain anything.
 875
 876         @see CalcBoundingBox()
 877     */
 878     void ResetBoundingBox();
 879
 880     //@}
 881
 882
 883     /**
 884         @name Page and document start/end functions
 885     */
 886     //@{
 887
 888     /**
 889         Starts a document (only relevant when outputting to a printer).
 890         @a message is a message to show while printing.
 891     */
 892     bool StartDoc(const wxString& message);
 893
 894     /**
 895         Starts a document page (only relevant when outputting to a printer).
 896     */
 897     void StartPage();
 898
 899     /**
 900         Ends a document (only relevant when outputting to a printer).
 901     */
 902     void EndDoc();
 903
 904     /**
 905         Ends a document page (only relevant when outputting to a printer).
 906     */
 907     void EndPage();
 908
 909     //@}
 910
 911
 912     /**
 913         @name Bit-Block Transfer operations (blit)
 914     */
 915     //@{
 916
 917     /**
 918         Copy from a source DC to this DC, specifying the destination
 919         coordinates, size of area to copy, source DC, source coordinates,
 920         logical function, whether to use a bitmap mask, and mask source
 921         position.
 922
 923         @param xdest
 924             Destination device context x position.
 925         @param ydest
 926             Destination device context y position.
 927         @param width
 928             Width of source area to be copied.
 929         @param height
 930             Height of source area to be copied.
 931         @param source
 932             Source device context.
 933         @param xsrc
 934             Source device context x position.
 935         @param ysrc
 936             Source device context y position.
 937         @param logicalFunc
 938             Logical function to use, see SetLogicalFunction().
 939         @param useMask
 940             If @true, Blit does a transparent blit using the mask that is
 941             associated with the bitmap selected into the source device context.
 942             The Windows implementation does the following if MaskBlt cannot be
 943             used:
 944             <ol>
 945             <li>Creates a temporary bitmap and copies the destination area into
 946                 it.</li>
 947             <li>Copies the source area into the temporary bitmap using the
 948                 specified logical function.</li>
 949             <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
 950                 the mask bitmap with the temp bitmap with the foreground colour
 951                 set to WHITE and the bg colour set to BLACK.</li>
 952             <li>Sets the unmasked area in the destination area to BLACK by
 953                 ANDing the mask bitmap with the destination area with the
 954                 foreground colour set to BLACK and the background colour set to
 955                 WHITE.</li>
 956             <li>ORs the temporary bitmap with the destination area.</li>
 957             <li>Deletes the temporary bitmap.</li>
 958             </ol>
 959             This sequence of operations ensures that the source's transparent
 960             area need not be black, and logical functions are supported.
 961             @n @b Note: on Windows, blitting with masks can be speeded up
 962             considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
 963             enabled. You can also influence whether MaskBlt or the explicit
 964             mask blitting code above is used, by using wxSystemOptions and
 965             setting the @c no-maskblt option to 1.
 966         @param xsrcMask
 967             Source x position on the mask. If both xsrcMask and ysrcMask are
 968             @c -1, xsrc and ysrc will be assumed for the mask source position.
 969             Currently only implemented on Windows.
 970         @param ysrcMask
 971             Source y position on the mask. If both xsrcMask and ysrcMask are
 972             @c -1, xsrc and ysrc will be assumed for the mask source position.
 973             Currently only implemented on Windows.
 974
 975         @remarks There is partial support for Blit() in wxPostScriptDC, under X.
 976
 977         @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
 978     */
 979     bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width,
 980               wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc,
 981               wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false,
 982               wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord);
 983
 984     /**
 985         Copy from a source DC to this DC, specifying the destination
 986         coordinates, destination size, source DC, source coordinates, size of
 987         source area to copy, logical function, whether to use a bitmap mask,
 988         and mask source position.
 989
 990         @param xdest
 991             Destination device context x position.
 992         @param ydest
 993             Destination device context y position.
 994         @param dstWidth
 995             Width of destination area.
 996         @param dstHeight
 997             Height of destination area.
 998         @param source
 999             Source device context.
1000         @param xsrc
1001             Source device context x position.
1002         @param ysrc
1003             Source device context y position.
1004         @param srcWidth
1005             Width of source area to be copied.
1006         @param srcHeight
1007             Height of source area to be copied.
1008         @param logicalFunc
1009             Logical function to use, see SetLogicalFunction().
1010         @param useMask
1011             If @true, Blit does a transparent blit using the mask that is
1012             associated with the bitmap selected into the source device context.
1013             The Windows implementation does the following if MaskBlt cannot be
1014             used:
1015             <ol>
1016             <li>Creates a temporary bitmap and copies the destination area into
1017                 it.</li>
1018             <li>Copies the source area into the temporary bitmap using the
1019                 specified logical function.</li>
1020             <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1021                 the mask bitmap with the temp bitmap with the foreground colour
1022                 set to WHITE and the bg colour set to BLACK.</li>
1023             <li>Sets the unmasked area in the destination area to BLACK by
1024                 ANDing the mask bitmap with the destination area with the
1025                 foreground colour set to BLACK and the background colour set to
1026                 WHITE.</li>
1027             <li>ORs the temporary bitmap with the destination area.</li>
1028             <li>Deletes the temporary bitmap.</li>
1029             </ol>
1030             This sequence of operations ensures that the source's transparent
1031             area need not be black, and logical functions are supported.
1032             @n @b Note: on Windows, blitting with masks can be speeded up
1033             considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
1034             enabled. You can also influence whether MaskBlt or the explicit
1035             mask blitting code above is used, by using wxSystemOptions and
1036             setting the @c no-maskblt option to 1.
1037         @param xsrcMask
1038             Source x position on the mask. If both xsrcMask and ysrcMask are
1039             wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1040             source position. Currently only implemented on Windows.
1041         @param ysrcMask
1042             Source y position on the mask. If both xsrcMask and ysrcMask are
1043             wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1044             source position. Currently only implemented on Windows.
1045
1046         There is partial support for Blit() in wxPostScriptDC, under X.
1047
1048         StretchBlit() is only implemented under wxMAC and wxMSW.
1049
1050         See wxMemoryDC for typical usage.
1051
1052         @since 2.9.0
1053
1054         @see Blit(), wxMemoryDC, wxBitmap, wxMask
1055     */
1056     bool StretchBlit(wxCoord xdest, wxCoord ydest,
1057                      wxCoord dstWidth, wxCoord dstHeight,
1058                      wxDC* source, wxCoord xsrc, wxCoord ysrc,
1059                      wxCoord srcWidth, wxCoord srcHeight,
1060                      wxRasterOperationMode logicalFunc = wxCOPY,
1061                      bool useMask = false,
1062                      wxCoord xsrcMask = wxDefaultCoord,
1063                      wxCoord ysrcMask = wxDefaultCoord);
1064     //@}
1065
1066
1067     /**
1068         @name Background/foreground brush and pen
1069     */
1070     //@{
1071
1072     /**
1073         Gets the brush used for painting the background.
1074
1075         @see wxDC::SetBackground()
1076     */
1077     const wxBrush& GetBackground() const;
1078
1079     /**
1080         Gets the current brush.
1081
1082         @see wxDC::SetBrush()
1083     */
1084     const wxBrush& GetBrush() const;
1085
1086     /**
1087         Gets the current pen.
1088
1089         @see SetPen()
1090     */
1091     const wxPen& GetPen() const;
1092
1093     /**
1094         Sets the current background brush for the DC.
1095     */
1096     void SetBackground(const wxBrush& brush);
1097
1098     /**
1099         Sets the current brush for the DC.
1100
1101         If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk),
1102         the current brush is selected out of the device context (leaving wxDC without
1103         any valid brush), allowing the current brush to be destroyed safely.
1104
1105         @see wxBrush, wxMemoryDC (for the interpretation of colours when
1106              drawing into a monochrome bitmap)
1107     */
1108     void SetBrush(const wxBrush& brush);
1109
1110     /**
1111         Sets the current pen for the DC.
1112
1113         If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk),
1114         the current pen is selected out of the device context (leaving wxDC without any
1115         valid pen), allowing the current pen to be destroyed safely.
1116
1117         @see wxMemoryDC for the interpretation of colours when drawing into a
1118              monochrome bitmap.
1119     */
1120     void SetPen(const wxPen& pen);
1121
1122     //@}
1123
1124
1125     /**
1126         Copy attributes from another DC.
1127
1128         The copied attributes currently are:
1129             - Font
1130             - Text foreground and background colours
1131             - Background brush
1132             - Layout direction
1133
1134         @param dc
1135             A valid (i.e. its IsOk() must return @true) source device context.
1136      */
1137     void CopyAttributes(const wxDC& dc);
1138
1139     /**
1140         Returns the depth (number of bits/pixel) of this DC.
1141
1142         @see wxDisplayDepth()
1143     */
1144     int GetDepth() const;
1145
1146     /**
1147         Returns the current device origin.
1148
1149         @see SetDeviceOrigin()
1150     */
1151     wxPoint GetDeviceOrigin() const;
1152
1153     /**
1154         Gets the current logical function.
1155
1156         @see SetLogicalFunction()
1157     */
1158     wxRasterOperationMode GetLogicalFunction() const;
1159
1160     /**
1161         Gets the current mapping mode for the device context.
1162
1163         @see SetMapMode()
1164     */
1165     wxMappingMode GetMapMode() const;
1166
1167     /**
1168         Gets in @a colour the colour at the specified location. Not available
1169         for wxPostScriptDC or wxMetafileDC.
1170
1171         @note Setting a pixel can be done using DrawPoint().
1172
1173         @beginWxPythonOnly
1174         The wxColour value is returned and is not required as a parameter.
1175         @endWxPythonOnly
1176     */
1177     bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
1178
1179     /**
1180         Returns the resolution of the device in pixels per inch.
1181     */
1182     wxSize GetPPI() const;
1183
1184     /**
1185         Gets the horizontal and vertical extent of this device context in @e device units.
1186         It can be used to scale graphics to fit the page.
1187
1188         For example, if @e maxX and @e maxY represent the maximum horizontal
1189         and vertical 'pixel' values used in your application, the following
1190         code will scale the graphic to fit on the printer page:
1191
1192         @code
1193         wxCoord w, h;
1194         dc.GetSize(&w, &h);
1195         double scaleX = (double)(maxX / w);
1196         double scaleY = (double)(maxY / h);
1197         dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
1198         @endcode
1199
1200         @beginWxPythonOnly
1201         In place of a single overloaded method name, wxPython implements the
1202         following methods:
1203         - GetSize() - Returns a wxSize.
1204         - GetSizeWH() - Returns a 2-tuple (width, height).
1205         @endWxPythonOnly
1206     */
1207     void GetSize(wxCoord* width, wxCoord* height) const;
1208
1209     /**
1210         @overload
1211     */
1212     wxSize GetSize() const;
1213
1214     /**
1215         Returns the horizontal and vertical resolution in millimetres.
1216     */
1217     void GetSizeMM(wxCoord* width, wxCoord* height) const;
1218
1219     /**
1220         @overload
1221     */
1222     wxSize GetSizeMM() const;
1223
1224     /**
1225         Gets the current user scale factor.
1226
1227         @see SetUserScale()
1228     */
1229     void GetUserScale(double* x, double* y) const;
1230
1231     /**
1232         Returns @true if the DC is ok to use.
1233     */
1234     bool IsOk() const;
1235
1236     /**
1237         Sets the x and y axis orientation (i.e., the direction from lowest to
1238         highest values on the axis). The default orientation is x axis from
1239         left to right and y axis from top down.
1240
1241         @param xLeftRight
1242             True to set the x axis orientation to the natural left to right
1243             orientation, @false to invert it.
1244         @param yBottomUp
1245             True to set the y axis orientation to the natural bottom up
1246             orientation, @false to invert it.
1247     */
1248     void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
1249
1250     /**
1251         Sets the device origin (i.e., the origin in pixels after scaling has
1252         been applied). This function may be useful in Windows printing
1253         operations for placing a graphic on a page.
1254     */
1255     void SetDeviceOrigin(wxCoord x, wxCoord y);
1256
1257     /**
1258         Sets the current logical function for the device context.
1259         It determines how a @e source pixel (from a pen or brush colour, or source
1260         device context if using Blit()) combines with a @e destination pixel in
1261         the current device context.
1262         Text drawing is not affected by this function.
1263
1264         See ::wxRasterOperationMode enumeration values for more info.
1265
1266         The default is @c wxCOPY, which simply draws with the current colour.
1267         The others combine the current colour and the background using a logical
1268         operation. @c wxINVERT is commonly used for drawing rubber bands or moving
1269         outlines, since drawing twice reverts to the original colour.
1270     */
1271     void SetLogicalFunction(wxRasterOperationMode function);
1272
1273     /**
1274         The mapping mode of the device context defines the unit of measurement
1275         used to convert @e logical units to @e device units.
1276
1277         Note that in X, text drawing isn't handled consistently with the mapping mode;
1278         a font is always specified in point size. However, setting the user scale (see
1279         SetUserScale()) scales the text appropriately. In Windows, scalable
1280         TrueType fonts are always used; in X, results depend on availability of
1281         fonts, but usually a reasonable match is found.
1282
1283         The coordinate origin is always at the top left of the screen/printer.
1284
1285         Drawing to a Windows printer device context uses the current mapping
1286         mode, but mapping mode is currently ignored for PostScript output.
1287     */
1288     void SetMapMode(wxMappingMode mode);
1289
1290     /**
1291         If this is a window DC or memory DC, assigns the given palette to the
1292         window or bitmap associated with the DC. If the argument is
1293         ::wxNullPalette, the current palette is selected out of the device
1294         context, and the original palette restored.
1295
1296         @see wxPalette
1297     */
1298     void SetPalette(const wxPalette& palette);
1299
1300     /**
1301         Sets the user scaling factor, useful for applications which require
1302         'zooming'.
1303     */
1304     void SetUserScale(double xScale, double yScale);
1305 };
1306
1307
1308
1309 /**
1310     @class wxDCClipper
1311
1312     wxDCClipper is a small helper class for setting a clipping region on a wxDC
1313     and unsetting it automatically. An object of wxDCClipper class is typically
1314     created on the stack so that it is automatically destroyed when the object
1315     goes out of scope. A typical usage example:
1316
1317     @code
1318     void MyFunction(wxDC& dc)
1319     {
1320         wxDCClipper clip(dc, rect);
1321         // ... drawing functions here are affected by clipping rect ...
1322     }
1323
1324     void OtherFunction()
1325     {
1326         wxDC dc;
1327         MyFunction(dc);
1328         // ... drawing functions here are not affected by clipping rect ...
1329     }
1330     @endcode
1331
1332     @library{wxcore}
1333     @category{gdi}
1334
1335     @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1336          wxDCBrushChanger
1337 */
1338 class wxDCClipper
1339 {
1340 public:
1341     //@{
1342     /**
1343         Sets the clipping region to the specified region/coordinates.
1344
1345         The clipping region is automatically unset when this object is destroyed.
1346     */
1347     wxDCClipper(wxDC& dc, const wxRegion& r);
1348     wxDCClipper(wxDC& dc, const wxRect& rect);
1349     wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h);
1350     //@}
1351
1352     /**
1353         Destroys the clipping region associated with the DC passed to the ctor.
1354     */
1355     ~wxDCClipper();
1356 };
1357
1358
1359 /**
1360     @class wxDCBrushChanger
1361
1362     wxDCBrushChanger is a small helper class for setting a brush on a wxDC
1363     and unsetting it automatically in the destructor, restoring the previous one.
1364
1365     @library{wxcore}
1366     @category{gdi}
1367
1368     @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1369          wxDCClipper
1370 */
1371 class wxDCBrushChanger
1372 {
1373 public:
1374     /**
1375         Sets @a brush on the given @a dc, storing the old one.
1376
1377         @param dc
1378             The DC where the brush must be temporary set.
1379         @param brush
1380             The brush to set.
1381     */
1382     wxDCBrushChanger(wxDC& dc, const wxBrush& brush);
1383
1384     /**
1385         Restores the brush originally selected in the DC passed to the ctor.
1386     */
1387     ~wxDCBrushChanger();
1388 };
1389
1390
1391 /**
1392     @class wxDCPenChanger
1393
1394     wxDCPenChanger is a small helper class for setting a pen on a wxDC
1395     and unsetting it automatically in the destructor, restoring the previous one.
1396
1397     @library{wxcore}
1398     @category{gdi}
1399
1400     @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger,
1401          wxDCClipper
1402 */
1403 class wxDCPenChanger
1404 {
1405 public:
1406     /**
1407         Sets @a pen on the given @a dc, storing the old one.
1408
1409         @param dc
1410             The DC where the pen must be temporary set.
1411         @param pen
1412             The pen to set.
1413     */
1414     wxDCPenChanger(wxDC& dc, const wxPen& pen);
1415
1416     /**
1417         Restores the pen originally selected in the DC passed to the ctor.
1418     */
1419     ~wxDCPenChanger();
1420 };
1421
1422
1423
1424 /**
1425     @class wxDCTextColourChanger
1426
1427     wxDCTextColourChanger is a small helper class for setting a foreground
1428     text colour on a wxDC and unsetting it automatically in the destructor,
1429     restoring the previous one.
1430
1431     @library{wxcore}
1432     @category{gdi}
1433
1434     @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger,
1435          wxDCClipper
1436 */
1437 class wxDCTextColourChanger
1438 {
1439 public:
1440     /**
1441         Trivial constructor not changing anything.
1442
1443         This constructor is useful if you don't know beforehand if the colour
1444         needs to be changed or not. It simply creates the object which won't do
1445         anything in its destructor unless Set() is called -- in which case it
1446         would reset the previous colour.
1447      */
1448     wxDCTextColourChanger(wxDC& dc);
1449
1450     /**
1451         Sets @a col on the given @a dc, storing the old one.
1452
1453         @param dc
1454             The DC where the colour must be temporary set.
1455         @param col
1456             The colour to set.
1457     */
1458     wxDCTextColourChanger(wxDC& dc, const wxColour& col);
1459
1460     /**
1461         Set the colour to use.
1462
1463         This method is meant to be called once only and only on the objects
1464         created with the constructor overload not taking wxColour argument and
1465         has the same effect as the other constructor, i.e. sets the colour to
1466         the given @a col and ensures that the old value is restored when this
1467         object is destroyed.
1468      */
1469     void Set(const wxColour& col);
1470
1471     /**
1472         Restores the colour originally selected in the DC passed to the ctor.
1473     */
1474     ~wxDCTextColourChanger();
1475 };
1476
1477
1478
1479 /**
1480     @class wxDCFontChanger
1481
1482     wxDCFontChanger is a small helper class for setting a font on a wxDC and
1483     unsetting it automatically in the destructor, restoring the previous one.
1484
1485     @since 2.9.0
1486
1487     @library{wxcore}
1488     @category{gdi}
1489
1490     @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger,
1491          wxDCClipper
1492 */
1493 class wxDCFontChanger
1494 {
1495 public:
1496     /**
1497         Sets @a font on the given @a dc, storing the old one.
1498
1499         @param dc
1500             The DC where the font must be temporary set.
1501         @param font
1502             The font to set.
1503     */
1504     wxDCFontChanger(wxDC& dc, const wxFont& font);
1505
1506     /**
1507         Restores the colour originally selected in the DC passed to the ctor.
1508     */
1509     ~wxDCFontChanger();
1510 };
1511