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