interface/dc.h

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