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