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