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