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