interface/dc.h

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