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