interface/dc.h

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