interface/dc.h

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