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