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