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 license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDC
  11
  12     A wxDC is a @e "device context" onto which graphics and text can be drawn.
  13     It is intended to represent different output devices and offers a common
  14     abstract API for drawing on any of them.
  15
  16     wxWidgets offers an alternative drawing API based on the modern drawing
  17     backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer
  18     and related classes. There is also a wxGCDC linking the APIs by offering
  19     the wxDC API ontop of a wxGraphicsContext.
  20
  21     wxDC is an abstract base class and cannot be created directly.
  22     Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
  23     wxPrinterDC. Notice that device contexts which are associated with windows
  24     (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours
  25     by default (starting with wxWidgets 2.9.0) but the other device context
  26     classes use system-default values so you always must set the appropriate
  27     fonts and colours before using them.
  28
  29     In addition to the versions of the methods documented below, there
  30     are also versions which accept single wxPoint parameter instead
  31     of the two wxCoord ones or wxPoint and wxSize instead of the four
  32     wxCoord parameters.
  33
  34     Beginning with wxWidgets 2.9.0 the entire wxDC code has been
  35     reorganized. All platform dependent code (actually all drawing code)
  36     has been moved into backend classes which derive from a common
  37     wxDCImpl class. The user-visible classes such as wxClientDC and
  38     wxPaintDC merely forward all calls to the backend implementation.
  39
  40     On Mac OS X colours with alpha channel are supported. Instances wxPen
  41     or wxBrush that are built from wxColour use the colour's alpha values
  42     when stroking or filling.
  43
  44     @library{wxcore}
  45     @category{dc,gdi}
  46
  47     @see @ref overview_dc, wxGraphicsContext
  48
  49     @todo Precise definition of default/initial state.
  50     @todo Pixelwise definition of operations (e.g. last point of a line not
  51           drawn).
  52     @todo Coordinates: state clearly which type of coordinates are returned by
  53           the various Get*Point() or similar functions - often they are client
  54           coordinates but not always.
  55 */
  56 class wxDC : public wxObject
  57 {
  58 public:
  59     /**
  60         Copy from a source DC to this DC, specifying the destination
  61         coordinates, size of area to copy, source DC, source coordinates,
  62         logical function, whether to use a bitmap mask, and mask source
  63         position.
  64
  65         @param xdest
  66             Destination device context x position.
  67         @param ydest
  68             Destination device context y position.
  69         @param width
  70             Width of source area to be copied.
  71         @param height
  72             Height of source area to be copied.
  73         @param source
  74             Source device context.
  75         @param xsrc
  76             Source device context x position.
  77         @param ysrc
  78             Source device context y position.
  79         @param logicalFunc
  80             Logical function to use, see SetLogicalFunction().
  81         @param useMask
  82             If @true, Blit does a transparent blit using the mask that is
  83             associated with the bitmap selected into the source device context.
  84             The Windows implementation does the following if MaskBlt cannot be
  85             used:
  86             <ol>
  87             <li>Creates a temporary bitmap and copies the destination area into
  88                 it.</li>
  89             <li>Copies the source area into the temporary bitmap using the
  90                 specified logical function.</li>
  91             <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
  92                 the mask bitmap with the temp bitmap with the foreground colour
  93                 set to WHITE and the bg colour set to BLACK.</li>
  94             <li>Sets the unmasked area in the destination area to BLACK by
  95                 ANDing the mask bitmap with the destination area with the
  96                 foreground colour set to BLACK and the background colour set to
  97                 WHITE.</li>
  98             <li>ORs the temporary bitmap with the destination area.</li>
  99             <li>Deletes the temporary bitmap.</li>
 100             </ol>
 101             This sequence of operations ensures that the source's transparent
 102             area need not be black, and logical functions are supported.
 103             @n @b Note: on Windows, blitting with masks can be speeded up
 104             considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
 105             enabled. You can also influence whether MaskBlt or the explicit
 106             mask blitting code above is used, by using wxSystemOptions and
 107             setting the @c no-maskblt option to 1.
 108         @param xsrcMask
 109             Source x position on the mask. If both xsrcMask and ysrcMask are
 110             -1, xsrc and ysrc will be assumed for the mask source position.
 111             Currently only implemented on Windows.
 112         @param ysrcMask
 113             Source y position on the mask. If both xsrcMask and ysrcMask are
 114             -1, xsrc and ysrc will be assumed for the mask source position.
 115             Currently only implemented on Windows.
 116
 117         @remarks There is partial support for Blit() in wxPostScriptDC, under X.
 118
 119         @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
 120     */
 121     bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width,
 122               wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc,
 123               int logicalFunc = wxCOPY, bool useMask = false,
 124               wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord);
 125
 126     /**
 127         Adds the specified point to the bounding box which can be retrieved
 128         with MinX(), MaxX() and MinY(), MaxY() functions.
 129
 130         @see ResetBoundingBox()
 131     */
 132     void CalcBoundingBox(wxCoord x, wxCoord y);
 133
 134     /**
 135         Clears the device context using the current background brush.
 136     */
 137     void Clear();
 138
 139     /**
 140         Displays a cross hair using the current pen. This is a vertical and
 141         horizontal line the height and width of the window, centred on the
 142         given point.
 143     */
 144     void CrossHair(wxCoord x, wxCoord y);
 145
 146     /**
 147         Destroys the current clipping region so that none of the DC is clipped.
 148
 149         @see SetClippingRegion()
 150     */
 151     void DestroyClippingRegion();
 152
 153     /**
 154         Convert device X coordinate to logical coordinate, using the current
 155         mapping mode, user scale factor, device origin and axis orientation.
 156     */
 157     wxCoord DeviceToLogicalX(wxCoord x) const;
 158
 159     /**
 160         Convert device X coordinate to relative logical coordinate, using the
 161         current mapping mode and user scale factor but ignoring the
 162         axis orientation. Use this for converting a width, for example.
 163     */
 164     wxCoord DeviceToLogicalXRel(wxCoord x) const;
 165
 166     /**
 167         Converts device Y coordinate to logical coordinate, using the current
 168         mapping mode, user scale factor, device origin and axis orientation.
 169     */
 170     wxCoord DeviceToLogicalY(wxCoord y) const;
 171
 172     /**
 173         Convert device Y coordinate to relative logical coordinate, using the
 174         current mapping mode and user scale factor but ignoring the
 175         axis orientation. Use this for converting a height, for example.
 176     */
 177     wxCoord DeviceToLogicalYRel(wxCoord y) const;
 178
 179     /**
 180         Draws an arc of a circle, centred on (@a xc, @a yc), with starting
 181         point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is
 182         used for the outline and the current brush for filling the shape.
 183
 184         The arc is drawn in a counter-clockwise direction from the start point
 185         to the end point.
 186     */
 187     void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
 188                   wxCoord xc, wxCoord yc);
 189
 190     /**
 191         Draw a bitmap on the device context at the specified point. If
 192         @a transparent is @true and the bitmap has a transparency mask, the
 193         bitmap will be drawn transparently.
 194
 195         When drawing a mono-bitmap, the current text foreground colour will be
 196         used to draw the foreground of the bitmap (all bits set to 1), and the
 197         current text background colour to draw the background (all bits set to
 198         0).
 199
 200         @see SetTextForeground(), SetTextBackground(), wxMemoryDC
 201     */
 202     void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
 203                     bool useMask = false);
 204
 205     //@{
 206     /**
 207         Draws a check mark inside the given rectangle.
 208     */
 209     void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 210     void DrawCheckMark(const wxRect& rect);
 211     //@}
 212
 213     //@{
 214     /**
 215         Draws a circle with the given centre and radius.
 216
 217         @see DrawEllipse()
 218     */
 219     void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);
 220     void DrawCircle(const wxPoint& pt, wxCoord radius);
 221     //@}
 222
 223     //@{
 224     /**
 225         Draws an ellipse contained in the rectangle specified either with the
 226         given top left corner and the given size or directly. The current pen
 227         is used for the outline and the current brush for filling the shape.
 228
 229         @see DrawCircle()
 230     */
 231     void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 232     void DrawEllipse(const wxPoint& pt, const wxSize& size);
 233     void DrawEllipse(const wxRect& rect);
 234     //@}
 235
 236     /**
 237         Draws an arc of an ellipse. The current pen is used for drawing the arc
 238         and the current brush is used for drawing the pie.
 239
 240         @a x and @a y specify the x and y coordinates of the upper-left corner
 241         of the rectangle that contains the ellipse.
 242
 243         @a width and @a height specify the width and height of the rectangle
 244         that contains the ellipse.
 245
 246         @a start and @a end specify the start and end of the arc relative to
 247         the three-o'clock position from the center of the rectangle. Angles are
 248         specified in degrees (360 is a complete circle). Positive values mean
 249         counter-clockwise motion. If @a start is equal to @e end, a complete
 250         ellipse will be drawn.
 251     */
 252     void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height,
 253                           double start, double end);
 254
 255     /**
 256         Draw an icon on the display (does nothing if the device context is
 257         PostScript). This can be the simplest way of drawing bitmaps on a
 258         window.
 259     */
 260     void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
 261
 262     //@{
 263     /**
 264         Draw optional bitmap and the text into the given rectangle and aligns
 265         it as specified by alignment parameter; it also will emphasize the
 266         character with the given index if it is != -1 and return the bounding
 267         rectangle if required.
 268     */
 269     virtual void DrawLabel(const wxString& text, const wxBitmap& image,
 270                            const wxRect& rect,
 271                            int alignment = wxALIGN_LEFT | wxALIGN_TOP,
 272                            int indexAccel = -1, wxRect* rectBounding = NULL);
 273     void DrawLabel(const wxString& text, const wxRect& rect,
 274                    int alignment = wxALIGN_LEFT | wxALIGN_TOP,
 275                    int indexAccel = -1);
 276     //@}
 277
 278     /**
 279         Draws a line from the first point to the second. The current pen is
 280         used for drawing the line. Note that the point (@a x2, @a y2) is not
 281         part of the line and is not drawn by this function (this is consistent
 282         with the behaviour of many other toolkits).
 283     */
 284     void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
 285
 286     /**
 287         Draws lines using an array of points of size @a n adding the optional
 288         offset coordinate. The current pen is used for drawing the lines.
 289
 290         @beginWxPythonOnly
 291         The wxPython version of this method accepts a Python list of wxPoint
 292         objects.
 293         @endWxPythonOnly
 294     */
 295     void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
 296                    wxCoord yoffset = 0);
 297     /**
 298         This method uses a list of wxPoints, adding the optional offset
 299         coordinate. The programmer is responsible for deleting the list of
 300         points.
 301
 302         @beginWxPythonOnly
 303         The wxPython version of this method accepts a Python list of wxPoint
 304         objects.
 305         @endWxPythonOnly
 306     */
 307     void DrawLines(const wxPointList* points,
 308                    wxCoord xoffset = 0, wxCoord yoffset = 0);
 309
 310     /**
 311         Draws a point using the color of the current pen. Note that the other
 312         properties of the pen are not used, such as width.
 313     */
 314     void DrawPoint(wxCoord x, wxCoord y);
 315
 316     /**
 317         Draws a filled polygon using an array of points of size @a n, adding
 318         the optional offset coordinate. The first and last points are
 319         automatically closed.
 320
 321         The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
 322         default) or @b wxWINDING_RULE.
 323
 324         The current pen is used for drawing the outline, and the current brush
 325         for filling the shape. Using a transparent brush suppresses filling.
 326     */
 327     void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
 328                      wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE);
 329     /**
 330         This method draws a filled polygon using a list of wxPoints, adding the
 331         optional offset coordinate. The first and last points are automatically
 332         closed.
 333
 334         The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
 335         default) or @b wxWINDING_RULE.
 336
 337         The current pen is used for drawing the outline, and the current brush
 338         for filling the shape. Using a transparent brush suppresses filling.
 339
 340         The programmer is responsible for deleting the list of points.
 341
 342         @beginWxPythonOnly
 343         The wxPython version of this method accepts a Python list of wxPoint
 344         objects.
 345         @endWxPythonOnly
 346     */
 347     void DrawPolygon(const wxPointList* points,
 348                      wxCoord xoffset = 0, wxCoord yoffset = 0,
 349                      int fill_style = wxODDEVEN_RULE);
 350
 351     /**
 352         Draws two or more filled polygons using an array of @a points, adding
 353         the optional offset coordinates.
 354
 355         Notice that for the platforms providing a native implementation of this
 356         function (Windows and PostScript-based wxDC currently), this is more
 357         efficient than using DrawPolygon() in a loop.
 358
 359         @a n specifies the number of polygons to draw, the array @e count of
 360         size @a n specifies the number of points in each of the polygons in the
 361         @a points array.
 362
 363         The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
 364         default) or @b wxWINDING_RULE.
 365
 366         The current pen is used for drawing the outline, and the current brush
 367         for filling the shape. Using a transparent brush suppresses filling.
 368
 369         The polygons maybe disjoint or overlapping. Each polygon specified in a
 370         call to DrawPolyPolygon() must be closed. Unlike polygons created by
 371         the DrawPolygon() member function, the polygons created by this
 372         method are not closed automatically.
 373
 374         @beginWxPythonOnly
 375         Not implemented yet.
 376         @endWxPythonOnly
 377     */
 378     void DrawPolyPolygon(int n, int count[], wxPoint points[],
 379                          wxCoord xoffset = 0, wxCoord yoffset = 0,
 380                          int fill_style = wxODDEVEN_RULE);
 381
 382     /**
 383         Draws a rectangle with the given top left corner, and with the given
 384         size.  The current pen is used for the outline and the current brush
 385         for filling the shape.
 386     */
 387     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 388
 389     /**
 390         Draws the text rotated by @a angle degrees.
 391
 392         @note Under Win9x only TrueType fonts can be drawn by this function. In
 393               particular, a font different from @c wxNORMAL_FONT should be used
 394               as the latter is not a TrueType font. @c wxSWISS_FONT is an
 395               example of a font which is.
 396
 397         @see DrawText()
 398     */
 399     void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
 400                          double angle);
 401
 402     /**
 403         Draws a rectangle with the given top left corner, and with the given
 404         size. The corners are quarter-circles using the given radius. The
 405         current pen is used for the outline and the current brush for filling
 406         the shape.
 407
 408         If @a radius is positive, the value is assumed to be the radius of the
 409         rounded corner. If @a radius is negative, the absolute value is assumed
 410         to be the @e proportion of the smallest dimension of the rectangle.
 411         This means that the corner can be a sensible size relative to the size
 412         of the rectangle, and also avoids the strange effects X produces when
 413         the corners are too big for the rectangle.
 414     */
 415     void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
 416                               wxCoord height, double radius);
 417
 418     //@{
 419     /**
 420         Draws a spline between all given points using the current pen.
 421
 422         @beginWxPythonOnly
 423         The wxPython version of this method accepts a Python list of wxPoint
 424         objects.
 425         @endWxPythonOnly
 426     */
 427     void DrawSpline(int n, wxPoint points[]);
 428     void DrawSpline(const wxPointList* points);
 429     void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
 430                     wxCoord x3, wxCoord y3);
 431     //@}
 432
 433     /**
 434         Draws a text string at the specified point, using the current text
 435         font, and the current text foreground and background colours.
 436
 437         The coordinates refer to the top-left corner of the rectangle bounding
 438         the string. See GetTextExtent() for how to get the dimensions of a text
 439         string, which can be used to position the text more precisely.
 440
 441         @note The current @ref GetLogicalFunction() "logical function" is
 442               ignored by this function.
 443     */
 444     void DrawText(const wxString& text, wxCoord x, wxCoord y);
 445
 446     /**
 447         Ends a document (only relevant when outputting to a printer).
 448     */
 449     void EndDoc();
 450
 451     /**
 452         Ends a document page (only relevant when outputting to a printer).
 453     */
 454     void EndPage();
 455
 456     /**
 457         Flood fills the device context starting from the given point, using
 458         the current brush colour, and using a style:
 459
 460         - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
 461           given colour is encountered.
 462         - wxFLOOD_BORDER: The area to be flooded is bounded by the given
 463           colour.
 464
 465         @return @false if the operation failed.
 466
 467         @note The present implementation for non-Windows platforms may fail to
 468               find colour borders if the pixels do not match the colour
 469               exactly. However the function will still return @true.
 470     */
 471     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
 472                    int style = wxFLOOD_SURFACE);
 473
 474     /**
 475         Gets the brush used for painting the background.
 476
 477         @see wxDC::SetBackground()
 478     */
 479     const wxBrush& GetBackground() const;
 480
 481     /**
 482         Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
 483
 484         @see SetBackgroundMode()
 485     */
 486     int GetBackgroundMode() const;
 487
 488     /**
 489         Gets the current brush.
 490
 491         @see wxDC::SetBrush()
 492     */
 493     const wxBrush& GetBrush() const;
 494
 495     /**
 496         Gets the character height of the currently set font.
 497     */
 498     wxCoord GetCharHeight() const;
 499
 500     /**
 501         Gets the average character width of the currently set font.
 502     */
 503     wxCoord GetCharWidth() const;
 504
 505     /**
 506         Gets the rectangle surrounding the current clipping region.
 507
 508         @beginWxPythonOnly
 509         No arguments are required and the four values defining the rectangle
 510         are returned as a tuple.
 511         @endWxPythonOnly
 512     */
 513     void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const;
 514
 515     /**
 516         Returns the depth (number of bits/pixel) of this DC.
 517
 518         @see wxDisplayDepth()
 519     */
 520     int GetDepth() const;
 521
 522     /**
 523         Gets the current font. Notice that even although each device context
 524         object has some default font after creation, this method would return a
 525         wxNullFont initially and only after calling SetFont() a valid font is
 526         returned.
 527     */
 528     const wxFont& GetFont() const;
 529
 530     /**
 531         Gets the current layout direction of the device context. On platforms
 532         where RTL layout is supported, the return value will either be
 533         @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
 534         not supported, the return value will be @c wxLayout_Default.
 535
 536         @see SetLayoutDirection()
 537     */
 538     wxLayoutDirection GetLayoutDirection() const;
 539
 540     /**
 541         Gets the current logical function.
 542
 543         @see SetLogicalFunction()
 544     */
 545     int GetLogicalFunction() const;
 546
 547     /**
 548         Gets the mapping mode for the device context.
 549
 550         @see SetMapMode()
 551     */
 552     int GetMapMode() const;
 553
 554     /**
 555         Gets the dimensions of the string using the currently selected font.
 556         @a string is the text string to measure, @e heightLine, if non @NULL,
 557         is where to store the height of a single line.
 558
 559         The text extent is set in the given @a w and @a h pointers.
 560
 561         If the optional parameter @a font is specified and valid, then it is
 562         used for the text extent calculation, otherwise the currently selected
 563         font is used.
 564
 565         @note This function works with both single-line and multi-line strings.
 566
 567         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
 568     */
 569     void GetMultiLineTextExtent(const wxString& string, wxCoord* w,
 570                                 wxCoord* h,
 571                                 wxCoord* heightLine = NULL,
 572                                 const wxFont* font = NULL) const;
 573     /**
 574         Gets the dimensions of the string using the currently selected font.
 575         @a string is the text string to measure, @e heightLine, if non @NULL,
 576         is where to store the height of a single line.
 577
 578         @return The text extent as a wxSize object.
 579
 580         @note This function works with both single-line and multi-line strings.
 581
 582         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
 583     */
 584     wxSize GetMultiLineTextExtent(const wxString& string) const;
 585
 586     /**
 587         Fills the @a widths array with the widths from the beginning of @a text
 588         to the corresponding character of @a text. The generic version simply
 589         builds a running total of the widths of each character using
 590         GetTextExtent(), however if the various platforms have a native API
 591         function that is faster or more accurate than the generic
 592         implementation then it should be used instead.
 593
 594         @beginWxPythonOnly
 595         This method only takes the @a text parameter and returns a Python list
 596         of integers.
 597         @endWxPythonOnly
 598
 599         @see GetMultiLineTextExtent(), GetTextExtent()
 600     */
 601     bool GetPartialTextExtents(const wxString& text,
 602                                wxArrayInt& widths) const;
 603
 604     /**
 605         Gets the current pen.
 606
 607         @see SetPen()
 608     */
 609     const wxPen& GetPen() const;
 610
 611     /**
 612         Gets in @a colour the colour at the specified location. Not available
 613         for wxPostScriptDC or wxMetafileDC.
 614
 615         @note Setting a pixel can be done using DrawPoint().
 616
 617         @beginWxPythonOnly
 618         The wxColour value is returned and is not required as a parameter.
 619         @endWxPythonOnly
 620     */
 621     bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
 622
 623     /**
 624         Returns the resolution of the device in pixels per inch.
 625     */
 626     wxSize GetPPI() const;
 627
 628     //@{
 629     /**
 630         This gets the horizontal and vertical resolution in device units. It
 631         can be used to scale graphics to fit the page.
 632
 633         For example, if @e maxX and @e maxY represent the maximum horizontal
 634         and vertical 'pixel' values used in your application, the following
 635         code will scale the graphic to fit on the printer page:
 636
 637         @code
 638         wxCoord w, h;
 639         dc.GetSize(&w, &h);
 640         double scaleX = (double)(maxX / w);
 641         double scaleY = (double)(maxY / h);
 642         dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
 643         @endcode
 644
 645         @beginWxPythonOnly
 646         In place of a single overloaded method name, wxPython implements the
 647         following methods:
 648         - GetSize() - Returns a wxSize.
 649         - GetSizeWH() - Returns a 2-tuple (width, height).
 650         @endWxPythonOnly
 651     */
 652     void GetSize(wxCoord* width, wxCoord* height) const;
 653     const wxSize GetSize() const;
 654     //@}
 655
 656     //@{
 657     /**
 658         Returns the horizontal and vertical resolution in millimetres.
 659     */
 660     void GetSizeMM(wxCoord* width, wxCoord* height) const;
 661     const wxSize GetSizeMM() const;
 662     //@}
 663
 664     /**
 665         Gets the current text background colour.
 666
 667         @see SetTextBackground()
 668     */
 669     const wxColour& GetTextBackground() const;
 670
 671     //@{
 672     /**
 673         Gets the dimensions of the string using the currently selected font.
 674         @a string is the text string to measure, @a descent is the dimension
 675         from the baseline of the font to the bottom of the descender, and
 676         @a externalLeading is any extra vertical space added to the font by the
 677         font designer (usually is zero).
 678
 679         The text extent is returned in @a w and @a h pointers or as a wxSize
 680         object depending on which version of this function is used.
 681
 682         If the optional parameter @a font is specified and valid, then it is
 683         used for the text extent calculation. Otherwise the currently selected
 684         font is.
 685
 686         @note This function only works with single-line strings.
 687
 688         @beginWxPythonOnly
 689         The following methods are implemented in wxPython:
 690         - GetTextExtent(string) - Returns a 2-tuple, (width, height).
 691         - GetFullTextExtent(string, font=NULL) -
 692             Returns a 4-tuple, (width, height, descent, externalLeading).
 693         @endWxPythonOnly
 694
 695         @see wxFont, SetFont(), GetPartialTextExtents(),
 696              GetMultiLineTextExtent()
 697     */
 698     void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
 699                        wxCoord* descent = NULL,
 700                        wxCoord* externalLeading = NULL,
 701                        const wxFont* font = NULL) const;
 702     const wxSize  GetTextExtent(const wxString& string) const;
 703     //@}
 704
 705     /**
 706         Gets the current text foreground colour.
 707
 708         @see SetTextForeground()
 709     */
 710     const wxColour& GetTextForeground() const;
 711
 712     /**
 713         Gets the current user scale factor.
 714
 715         @see SetUserScale()
 716     */
 717     void GetUserScale(double* x, double* y) const;
 718
 719     //@{
 720     /**
 721         Fill the area specified by rect with a radial gradient, starting from
 722         @a initialColour at the centre of the circle and fading to
 723         @a destColour on the circle outside.
 724
 725         @a circleCenter are the relative coordinates of centre of the circle in
 726         the specified @e rect. If not specified, the circle is placed at the
 727         centre of rect.
 728
 729         @note Currently this function is very slow, don't use it for real-time
 730               drawing.
 731     */
 732     void GradientFillConcentric(const wxRect& rect,
 733                                 const wxColour& initialColour,
 734                                 const wxColour& destColour);
 735     void GradientFillConcentric(const wxRect& rect,
 736                                 const wxColour& initialColour,
 737                                 const wxColour& destColour,
 738                                 const wxPoint& circleCenter);
 739     //@}
 740
 741     /**
 742         Fill the area specified by @a rect with a linear gradient, starting
 743         from @a initialColour and eventually fading to @e destColour. The
 744         @a nDirection specifies the direction of the colour change, default is
 745         to use @a initialColour on the left part of the rectangle and
 746         @a destColour on the right one.
 747     */
 748     void GradientFillLinear(const wxRect& rect, const wxColour& initialColour,
 749                             const wxColour& destColour,
 750                             wxDirection nDirection = wxRIGHT);
 751
 752     /**
 753         Returns @true if the DC is ok to use.
 754     */
 755     bool IsOk() const;
 756
 757     /**
 758         Converts logical X coordinate to device coordinate, using the current
 759         mapping mode, user scale factor, device origin and axis orientation.
 760     */
 761     wxCoord LogicalToDeviceX(wxCoord x) const;
 762
 763     /**
 764         Converts logical X coordinate to relative device coordinate, using the
 765         current mapping mode and user scale factor but ignoring the
 766         axis orientation. Use this for converting a width, for example.
 767     */
 768     wxCoord LogicalToDeviceXRel(wxCoord x) const;
 769
 770     /**
 771         Converts logical Y coordinate to device coordinate, using the current
 772         mapping mode, user scale factor, device origin and axis orientation.
 773     */
 774     wxCoord LogicalToDeviceY(wxCoord y) const;
 775
 776     /**
 777         Converts logical Y coordinate to relative device coordinate, using the
 778         current mapping mode and user scale factor but ignoring the
 779         axis orientation. Use this for converting a height, for example.
 780     */
 781     wxCoord LogicalToDeviceYRel(wxCoord y) const;
 782
 783     /**
 784         Gets the maximum horizontal extent used in drawing commands so far.
 785     */
 786     wxCoord MaxX() const;
 787
 788     /**
 789         Gets the maximum vertical extent used in drawing commands so far.
 790     */
 791     wxCoord MaxY() const;
 792
 793     /**
 794         Gets the minimum horizontal extent used in drawing commands so far.
 795     */
 796     wxCoord MinX() const;
 797
 798     /**
 799         Gets the minimum vertical extent used in drawing commands so far.
 800     */
 801     wxCoord MinY() const;
 802
 803     /**
 804         Resets the bounding box: after a call to this function, the bounding
 805         box doesn't contain anything.
 806
 807         @see CalcBoundingBox()
 808     */
 809     void ResetBoundingBox();
 810
 811     /**
 812         Sets the x and y axis orientation (i.e., the direction from lowest to
 813         highest values on the axis). The default orientation is x axis from
 814         left to right and y axis from top down.
 815
 816         @param xLeftRight
 817             True to set the x axis orientation to the natural left to right
 818             orientation, @false to invert it.
 819         @param yBottomUp
 820             True to set the y axis orientation to the natural bottom up
 821             orientation, @false to invert it.
 822     */
 823     void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
 824
 825     /**
 826         Sets the current background brush for the DC.
 827     */
 828     void SetBackground(const wxBrush& brush);
 829
 830     /**
 831         @a mode may be one of wxSOLID and wxTRANSPARENT. This setting
 832         determines whether text will be drawn with a background colour or not.
 833     */
 834     void SetBackgroundMode(int mode);
 835
 836     /**
 837         Sets the current brush for the DC.
 838
 839         If the argument is wxNullBrush, the current brush is selected out of
 840         the device context (leaving wxDC without any valid brush), allowing the
 841         current brush to be destroyed safely.
 842
 843         @see wxBrush, wxMemoryDC (for the interpretation of colours when
 844              drawing into a monochrome bitmap)
 845     */
 846     void SetBrush(const wxBrush& brush);
 847
 848     //@{
 849     /**
 850         Sets the clipping region for this device context to the intersection of
 851         the given region described by the parameters of this method and the
 852         previously set clipping region. You should call DestroyClippingRegion()
 853         if you want to set the clipping region exactly to the region specified.
 854
 855         The clipping region is an area to which drawing is restricted. Possible
 856         uses for the clipping region are for clipping text or for speeding up
 857         window redraws when only a known area of the screen is damaged.
 858
 859         @see DestroyClippingRegion(), wxRegion
 860     */
 861     void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width,
 862                            wxCoord height);
 863     void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
 864     void SetClippingRegion(const wxRect& rect);
 865     //@}
 866
 867     /**
 868         Sets the clipping region for this device context.
 869
 870         Unlike SetClippingRegion(), this function works with physical
 871         coordinates and not with the logical ones.
 872      */
 873     void SetDeviceClippingRegion(const wxRegion& region);
 874
 875     /**
 876         Sets the device origin (i.e., the origin in pixels after scaling has
 877         been applied). This function may be useful in Windows printing
 878         operations for placing a graphic on a page.
 879     */
 880     void SetDeviceOrigin(wxCoord x, wxCoord y);
 881
 882     /**
 883         Sets the current font for the DC. It must be a valid font, in
 884         particular you should not pass wxNullFont to this method.
 885
 886         @see wxFont
 887     */
 888     void SetFont(const wxFont& font);
 889
 890     /**
 891         Sets the current layout direction for the device context. @a dir may be
 892         either @c wxLayout_Default, @c wxLayout_LeftToRight or
 893         @c wxLayout_RightToLeft.
 894
 895         @see GetLayoutDirection()
 896     */
 897     void SetLayoutDirection(wxLayoutDirection dir);
 898
 899     /**
 900         Sets the current logical function for the device context. This
 901         determines how a source pixel (from a pen or brush colour, or source
 902         device context if using Blit()) combines with a destination pixel in
 903         the current device context.
 904         Text drawing is not affected by this function.
 905
 906         The possible values and their meaning in terms of source and
 907         destination pixel values are as follows:
 908
 909         @verbatim
 910         wxAND           src AND dst
 911         wxAND_INVERT    (NOT src) AND dst
 912         wxAND_REVERSE   src AND (NOT dst)
 913         wxCLEAR         0
 914         wxCOPY          src
 915         wxEQUIV         (NOT src) XOR dst
 916         wxINVERT        NOT dst
 917         wxNAND          (NOT src) OR (NOT dst)
 918         wxNOR           (NOT src) AND (NOT dst)
 919         wxNO_OP         dst
 920         wxOR            src OR dst
 921         wxOR_INVERT     (NOT src) OR dst
 922         wxOR_REVERSE    src OR (NOT dst)
 923         wxSET           1
 924         wxSRC_INVERT    NOT src
 925         wxXOR           src XOR dst
 926         @endverbatim
 927
 928         The default is wxCOPY, which simply draws with the current colour. The
 929         others combine the current colour and the background using a logical
 930         operation. wxINVERT is commonly used for drawing rubber bands or moving
 931         outlines, since drawing twice reverts to the original colour.
 932     */
 933     void SetLogicalFunction(int function);
 934
 935     /**
 936         The mapping mode of the device context defines the unit of measurement
 937         used to convert logical units to device units. Note that in X, text
 938         drawing isn't handled consistently with the mapping mode; a font is
 939         always specified in point size. However, setting the user scale (see
 940         SetUserScale()) scales the text appropriately. In Windows, scalable
 941         TrueType fonts are always used; in X, results depend on availability of
 942         fonts, but usually a reasonable match is found.
 943
 944         The coordinate origin is always at the top left of the screen/printer.
 945
 946         Drawing to a Windows printer device context uses the current mapping
 947         mode, but mapping mode is currently ignored for PostScript output.
 948
 949         The mapping mode can be one of the following:
 950         - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an
 951           inch.
 952         - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch.
 953         - wxMM_METRIC: Each logical unit is 1 mm.
 954         - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm.
 955         - wxMM_TEXT: Each logical unit is 1 device pixel.
 956     */
 957     void SetMapMode(int mode);
 958
 959     /**
 960         If this is a window DC or memory DC, assigns the given palette to the
 961         window or bitmap associated with the DC. If the argument is
 962         wxNullPalette, the current palette is selected out of the device
 963         context, and the original palette restored.
 964
 965         @see wxPalette
 966     */
 967     void SetPalette(const wxPalette& palette);
 968
 969     /**
 970         Sets the current pen for the DC. If the argument is wxNullPen, the
 971         current pen is selected out of the device context (leaving wxDC without
 972         any valid pen), allowing the current brush to be destroyed safely.
 973
 974         @see wxMemoryDC for the interpretation of colours when drawing into a
 975              monochrome bitmap.
 976     */
 977     void SetPen(const wxPen& pen);
 978
 979     /**
 980         Sets the current text background colour for the DC.
 981     */
 982     void SetTextBackground(const wxColour& colour);
 983
 984     /**
 985         Sets the current text foreground colour for the DC.
 986
 987         @see wxMemoryDC for the interpretation of colours when drawing into a
 988              monochrome bitmap.
 989     */
 990     void SetTextForeground(const wxColour& colour);
 991
 992     /**
 993         Sets the user scaling factor, useful for applications which require
 994         'zooming'.
 995     */
 996     void SetUserScale(double xScale, double yScale);
 997
 998     /**
 999         Starts a document (only relevant when outputting to a printer).
1000         @a message is a message to show while printing.
1001     */
1002     bool StartDoc(const wxString& message);
1003
1004     /**
1005         Starts a document page (only relevant when outputting to a printer).
1006     */
1007     void StartPage();
1008
1009     /**
1010         Copy from a source DC to this DC, specifying the destination
1011         coordinates, destination size, source DC, source coordinates, size of
1012         source area to copy, logical function, whether to use a bitmap mask,
1013         and mask source position.
1014
1015         @param xdest
1016             Destination device context x position.
1017         @param ydest
1018             Destination device context y position.
1019         @param dstWidth
1020             Width of destination area.
1021         @param dstHeight
1022             Height of destination area.
1023         @param source
1024             Source device context.
1025         @param xsrc
1026             Source device context x position.
1027         @param ysrc
1028             Source device context y position.
1029         @param srcWidth
1030             Width of source area to be copied.
1031         @param srcHeight
1032             Height of source area to be copied.
1033         @param logicalFunc
1034             Logical function to use, see SetLogicalFunction().
1035         @param useMask
1036             If @true, Blit does a transparent blit using the mask that is
1037             associated with the bitmap selected into the source device context.
1038             The Windows implementation does the following if MaskBlt cannot be
1039             used:
1040             <ol>
1041             <li>Creates a temporary bitmap and copies the destination area into
1042                 it.</li>
1043             <li>Copies the source area into the temporary bitmap using the
1044                 specified logical function.</li>
1045             <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1046                 the mask bitmap with the temp bitmap with the foreground colour
1047                 set to WHITE and the bg colour set to BLACK.</li>
1048             <li>Sets the unmasked area in the destination area to BLACK by
1049                 ANDing the mask bitmap with the destination area with the
1050                 foreground colour set to BLACK and the background colour set to
1051                 WHITE.</li>
1052             <li>ORs the temporary bitmap with the destination area.</li>
1053             <li>Deletes the temporary bitmap.</li>
1054             </ol>
1055             This sequence of operations ensures that the source's transparent
1056             area need not be black, and logical functions are supported.
1057             @n @b Note: on Windows, blitting with masks can be speeded up
1058             considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
1059             enabled. You can also influence whether MaskBlt or the explicit
1060             mask blitting code above is used, by using wxSystemOptions and
1061             setting the @c no-maskblt option to 1.
1062         @param xsrcMask
1063             Source x position on the mask. If both xsrcMask and ysrcMask are
1064             wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1065             source position. Currently only implemented on Windows.
1066         @param ysrcMask
1067             Source y position on the mask. If both xsrcMask and ysrcMask are
1068             wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1069             source position. Currently only implemented on Windows.
1070
1071         There is partial support for Blit() in wxPostScriptDC, under X.
1072
1073         StretchBlit() is only implemented under wxMAC and wxMSW.
1074
1075         See wxMemoryDC for typical usage.
1076
1077         @since 2.9.0
1078
1079         @see Blit(), wxMemoryDC, wxBitmap, wxMask
1080     */
1081     bool StretchBlit(wxCoord xdest, wxCoord ydest,
1082                      wxCoord dstWidth, wxCoord dstHeight,
1083                      wxDC* source, wxCoord xsrc, wxCoord ysrc,
1084                      wxCoord srcWidth, wxCoord srcHeight,
1085                      int logicalFunc = wxCOPY,
1086                      bool useMask = false,
1087                      wxCoord xsrcMask = wxDefaultCoord,
1088                      wxCoord ysrcMask = wxDefaultCoord);
1089 };
1090
1091
1092
1093 /**
1094     @class wxDCClipper
1095
1096     wxDCClipper is a small helper class for setting a clipping region on a wxDC
1097     and unsetting it automatically. An object of wxDCClipper class is typically
1098     created on the stack so that it is automatically destroyed when the object
1099     goes out of scope. A typical usage example:
1100
1101     @code
1102     void MyFunction(wxDC& dc)
1103     {
1104         wxDCClipper clip(dc, rect);
1105         // ... drawing functions here are affected by clipping rect ...
1106     }
1107
1108     void OtherFunction()
1109     {
1110         wxDC dc;
1111         MyFunction(dc);
1112         // ... drawing functions here are not affected by clipping rect ...
1113     }
1114     @endcode
1115
1116     @library{wxcore}
1117     @category{gdi}
1118
1119     @see wxDC::SetClippingRegion()
1120 */
1121 class wxDCClipper
1122 {
1123 public:
1124     //@{
1125     /**
1126         Sets the clipping region to the specified region/coordinates.
1127
1128         The clipping region is automatically unset when this object is destroyed.
1129     */
1130     wxDCClipper(wxDC& dc, const wxRegion& r);
1131     wxDCClipper(wxDC& dc, const wxRect& rect);
1132     wxDCClipper(wxDC& dc, int x, int y, int w, int h);
1133     //@}
1134 };
1135