interface/wx/dc.h

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