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