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