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