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