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