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