interface/wx/dc.h

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