interface/wx/dcsvg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dcsvg.h
   3 // Purpose:     interface of wxSVGFileDC
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxSVGFileDC
  11
  12     A wxSVGFileDC is a device context onto which graphics and text can be
  13     drawn, and the output produced as a vector file, in SVG format (see the W3C
  14     SVG Specifications <http://www.w3.org/TR/2001/REC-SVG-20010904/>). This
  15     format can be read by a range of programs, including a Netscape plugin
  16     (Adobe), full details are given in the SVG Implementation and Resource
  17     Directory <http://www.svgi.org/>. Vector formats may often be smaller than
  18     raster formats.
  19
  20     The intention behind wxSVGFileDC is that it can be used to produce a file
  21     corresponding to the screen display context, wxSVGFileDC, by passing the
  22     wxSVGFileDC as a parameter instead of a wxSVGFileDC. Thus the wxSVGFileDC
  23     is a write-only class.
  24
  25     As the wxSVGFileDC is a vector format, raster operations like GetPixel()
  26     are unlikely to be supported. However, the SVG specification allows for PNG
  27     format raster files to be embedded in the SVG, and so bitmaps, icons and
  28     blit operations in wxSVGFileDC are supported.
  29
  30     A more substantial SVG library (for reading and writing) is available at
  31     the wxArt2D website <http://wxart2d.sourceforge.net/>.
  32
  33     @library{wxcore}
  34     @category{dc}
  35 */
  36 class wxSVGFileDC : public wxDC
  37 {
  38 public:
  39     /**
  40         Initializes a wxSVGFileDC with the given @a f filename with the given
  41         @a Width and @a Height at @a dpi resolution.
  42     */
  43     wxSVGFileDC(const wxString& filename, int width = 320, int height = 240, double dpi = 72);
  44
  45     /**
  46         Destructor.
  47     */
  48     virtual ~wxSVGFileDC();
  49
  50     /**
  51         Copies from a source DC to this DC, specifying the destination
  52         coordinates, size of area to copy, source DC, source coordinates,
  53         logical function, whether to use a bitmap mask, and mask source
  54         position.
  55
  56         @see wxDC::Blit()
  57     */
  58     bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height,
  59               wxDC* source, wxCoord xsrc, wxCoord ysrc, wxRasterOperationMode rop = wxCOPY,
  60               bool useMask = false, wxCoord xsrcMask = wxDefaultCoord,
  61               wxCoord ysrcMask = wxDefaultCoord);
  62
  63     /**
  64         Adds the specified point to the bounding box which can be retrieved
  65         with wxDC::MinX(), wxDC::MaxX() and wxDC::MinY(), wxDC::MaxY()
  66         functions.
  67     */
  68     void CalcBoundingBox(wxCoord x, wxCoord y);
  69
  70     /**
  71         This makes no sense in wxSVGFileDC and does nothing.
  72     */
  73     void Clear();
  74
  75     /**
  76         Not Implemented.
  77     */
  78     void CrossHair(wxCoord x, wxCoord y);
  79
  80     /**
  81         Not Implemented.
  82     */
  83     void DestroyClippingRegion();
  84
  85     /**
  86         Convert device X coordinate to logical coordinate, using the current
  87         mapping mode.
  88     */
  89     wxCoord DeviceToLogicalX(wxCoord x) const;
  90
  91     /**
  92         Convert device X coordinate to relative logical coordinate, using the
  93         current mapping mode but ignoring the x axis orientation. Use this
  94         function for converting a width, for example.
  95     */
  96     wxCoord DeviceToLogicalXRel(wxCoord x) const;
  97
  98     /**
  99         Converts device Y coordinate to logical coordinate, using the current
 100         mapping mode.
 101     */
 102     wxCoord DeviceToLogicalY(wxCoord y) const;
 103
 104     /**
 105         Convert device Y coordinate to relative logical coordinate, using the
 106         current mapping mode but ignoring the y axis orientation. Use this
 107         function for converting a height, for example.
 108     */
 109     wxCoord DeviceToLogicalYRel(wxCoord y) const;
 110
 111     /**
 112         Draws an arc of a circle, centred on (@a xc, @a yc), with starting
 113         point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is
 114         used for the outline and the current brush for filling the shape.
 115
 116         The arc is drawn in a counter-clockwise direction from the start point
 117         to the end point.
 118     */
 119     void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
 120                  wxCoord xc, wxCoord yc);
 121
 122     /**
 123         Draw a bitmap on the device context at the specified point. If
 124         @a useMask is @true and the bitmap has a transparency mask, the
 125         bitmap will be drawn transparently.
 126
 127         When drawing a mono-bitmap, the current text foreground colour will be
 128         used to draw the foreground of the bitmap (all bits set to 1), and the
 129         current text background colour to draw the background (all bits set to
 130         0).
 131
 132         @see wxDC::SetTextForeground(), wxDC::SetTextBackground(), wxMemoryDC
 133     */
 134     void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
 135                     bool useMask = false);
 136
 137     //@{
 138     /**
 139         Draws a check mark inside the given rectangle.
 140     */
 141     void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 142     void DrawCheckMark(const wxRect& rect);
 143     //@}
 144
 145     //@{
 146     /**
 147         Draws a circle with the given centre and radius.
 148
 149         @see wxDC::DrawEllipse()
 150     */
 151     void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);
 152     void DrawCircle(const wxPoint& pt, wxCoord radius);
 153     //@}
 154
 155     //@{
 156     /**
 157         Draws an ellipse contained in the rectangle specified either with the
 158         given top left corner and the given size or directly. The current pen
 159         is used for the outline and the current brush for filling the shape.
 160
 161         @see wxDC::DrawCircle()
 162     */
 163     void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 164     void DrawEllipse(const wxPoint& pt, const wxSize& size);
 165     void DrawEllipse(const wxRect& rect);
 166     //@}
 167
 168     /**
 169         Draws an arc of an ellipse. The current pen is used for drawing the arc
 170         and the current brush is used for drawing the pie.
 171
 172         @a x and @a y specify the x and y coordinates of the upper-left corner
 173         of the rectangle that contains the ellipse.
 174
 175         @a width and @a height specify the width and height of the rectangle
 176         that contains the ellipse.
 177
 178         @a start and @a end specify the start and end of the arc relative to
 179         the three-o'clock position from the center of the rectangle. Angles are
 180         specified in degrees (360 is a complete circle). Positive values mean
 181         counter-clockwise motion. If @a start is equal to @a end, a complete
 182         ellipse will be drawn.
 183     */
 184     void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height,
 185                          double start, double end);
 186
 187     /**
 188         Draw an icon on the display (does nothing if the device context is
 189         PostScript). This can be the simplest way of drawing bitmaps on a
 190         window.
 191     */
 192     void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
 193
 194     /**
 195         Draws a line from the first point to the second. The current pen is
 196         used for drawing the line.
 197     */
 198     void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
 199
 200     //@{
 201     /**
 202         Draws lines using an array of @a points of size @a n, or list of
 203         pointers to points, adding the optional offset coordinate. The current
 204         pen is used for drawing the lines. The programmer is responsible for
 205         deleting the list of points.
 206     */
 207     void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
 208                    wxCoord yoffset = 0);
 209     void DrawLines(wxList* points, wxCoord xoffset = 0,
 210                    wxCoord yoffset = 0);
 211     //@}
 212
 213     /**
 214         Draws a point using the current pen.
 215     */
 216     void DrawPoint(wxCoord x, wxCoord y);
 217
 218     //@{
 219     /**
 220         Draws a filled polygon using an array of @a points of size @a n,
 221         or list of pointers to points, adding the optional offset coordinate.
 222         wxWidgets automatically closes the first and last points.
 223
 224         The last argument specifies the fill rule: @c wxODDEVEN_RULE (the
 225         default) or @c wxWINDING_RULE.
 226
 227         The current pen is used for drawing the outline, and the current brush
 228         for filling the shape. Using a transparent brush suppresses filling.
 229
 230         The programmer is responsible for deleting the list of points.
 231     */
 232     void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
 233                      wxCoord yoffset = 0,
 234                      wxPolygonFillMode fill_style = wxODDEVEN_RULE);
 235     void DrawPolygon(wxList* points, wxCoord xoffset = 0,
 236                      wxCoord yoffset = 0,
 237                      wxPolygonFillMode fill_style = wxODDEVEN_RULE);
 238     //@}
 239
 240     /**
 241         Draws a rectangle with the given top left corner, and with the given
 242         size.  The current pen is used for the outline and the current brush
 243         for filling the shape.
 244     */
 245     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 246
 247     /**
 248         Draws the text rotated by @a angle degrees.
 249
 250         The wxMSW wxDC and wxSVGFileDC rotate the text around slightly
 251         different points, depending on the size of the font.
 252     */
 253     void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
 254                          double angle);
 255
 256     /**
 257         Draws a rectangle with the given top left corner, and with the given
 258         size.  The corners are quarter-circles using the given radius. The
 259         current pen is used for the outline and the current brush for filling
 260         the shape.
 261
 262         If @a radius is positive, the value is assumed to be the radius of the
 263         rounded corner. If @a radius is negative, the absolute value is assumed
 264         to be the @e proportion of the smallest dimension of the rectangle.
 265         This means that the corner can be a sensible size relative to the size
 266         of the rectangle, and also avoids the strange effects X produces when
 267         the corners are too big for the rectangle.
 268     */
 269     void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
 270                               wxCoord height, double radius = 20);
 271
 272     /**
 273         Draws a spline between all given control points, using the current pen.
 274         The programmer is responsible for deleting the list of points.
 275         The spline is drawn using a series of lines, using an algorithm taken from
 276         the X drawing program "XFIG".
 277     */
 278     void DrawSpline(const wxPointList* points);
 279
 280     /**
 281         Draws a three-point spline using the current pen.
 282     */
 283     void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
 284                     wxCoord x3, wxCoord y3);
 285
 286     /**
 287         Draws a text string at the specified point, using the current text
 288         font, and the current text foreground and background colours.
 289
 290         The coordinates refer to the top-left corner of the rectangle bounding
 291         the string. See wxDC::GetTextExtent() for how to get the dimensions of
 292         a text string, which can be used to position the text more precisely.
 293     */
 294     void DrawText(const wxString& text, wxCoord x, wxCoord y);
 295
 296     /**
 297         Does nothing.
 298     */
 299     void EndDoc();
 300
 301     /**
 302         Does nothing.
 303     */
 304     void EndDrawing();
 305
 306     /**
 307         Does nothing.
 308     */
 309     void EndPage();
 310
 311     /**
 312         Not implemented.
 313     */
 314     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
 315                    wxFloodFillStyle style = wxFLOOD_SURFACE);
 316
 317     //@{
 318     /**
 319         Gets the brush used for painting the background.
 320
 321         @see SetBackground()
 322     */
 323     wxBrush GetBackground() const;
 324     const wxBrush GetBackground() const;
 325     //@}
 326
 327     /**
 328         Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
 329
 330         @see SetBackgroundMode()
 331     */
 332     int GetBackgroundMode() const;
 333
 334     //@{
 335     /**
 336         Gets the current brush.
 337
 338         @see SetBrush()
 339     */
 340     wxBrush GetBrush() const;
 341     const wxBrush GetBrush() const;
 342     //@}
 343
 344     /**
 345         Gets the character height of the currently set font.
 346     */
 347     wxCoord GetCharHeight() const;
 348
 349     /**
 350         Gets the average character width of the currently set font.
 351     */
 352     wxCoord GetCharWidth() const;
 353
 354     /**
 355         Not implemented.
 356     */
 357     void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const;
 358
 359     //@{
 360     /**
 361         Gets the current font.
 362
 363         @see SetFont()
 364     */
 365     wxFont GetFont() const;
 366     const wxFont GetFont() const;
 367     //@}
 368
 369     /**
 370         Gets the current logical function.
 371
 372         @see SetLogicalFunction()
 373     */
 374     wxRasterOperationMode GetLogicalFunction() const;
 375
 376     /**
 377         Gets the mapping mode for the device context.
 378
 379         @see SetMapMode()
 380     */
 381     int GetMapMode() const;
 382
 383     //@{
 384     /**
 385         Gets the current pen.
 386
 387         @see SetPen()
 388     */
 389     wxPen GetPen() const;
 390     const wxPen GetPen() const;
 391     //@}
 392
 393     /**
 394         Not implemented.
 395     */
 396     bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
 397
 398     /**
 399         For a Windows printer device context, this gets the horizontal and
 400         vertical resolution.
 401     */
 402     void GetSize(wxCoord* width, wxCoord* height);
 403
 404     //@{
 405     /**
 406         Gets the current text background colour.
 407
 408         @see SetTextBackground()
 409     */
 410     wxColour GetTextBackground() const;
 411     const wxColour& GetTextBackground() const;
 412     //@}
 413
 414     /**
 415         Gets the dimensions of the string using the currently selected font.
 416
 417         @param string
 418             The text string to measure.
 419         @param w
 420             This value will be set to the width after this call.
 421         @param h
 422             This value will be set to the height after this call.
 423         @param descent
 424             The dimension from the baseline of the font to the bottom of the
 425             descender.
 426         @param externalLeading
 427             Any extra vertical space added to the font by the font designer
 428             (usually is zero).
 429         @param font
 430             Specifies an alternative to the currently selected font: but note
 431             that this does not yet work under Windows, so you need to set a
 432             font for the device context first.
 433
 434         @see wxFont, SetFont()
 435     */
 436     void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
 437                        wxCoord* descent = NULL,
 438                        wxCoord* externalLeading = NULL,
 439                        const wxFont* font = NULL) const;
 440
 441     //@{
 442     /**
 443         Gets the current text foreground colour.
 444
 445         @see SetTextForeground()
 446     */
 447     wxColour GetTextForeground() const;
 448     const wxColour GetTextForeground() const;
 449     //@}
 450
 451     /**
 452         Gets the current user scale factor.
 453
 454         @see SetUserScale()
 455     */
 456     void GetUserScale(double* x, double* y) const;
 457
 458     /**
 459         Converts logical X coordinate to device coordinate, using the current
 460         mapping mode.
 461     */
 462     wxCoord LogicalToDeviceX(wxCoord x) const;
 463
 464     /**
 465         Converts logical X coordinate to relative device coordinate, using the
 466         current mapping mode but ignoring the x axis orientation. Use this for
 467         converting a width, for example.
 468     */
 469     wxCoord LogicalToDeviceXRel(wxCoord x) const;
 470
 471     /**
 472         Converts logical Y coordinate to device coordinate, using the current
 473         mapping mode.
 474     */
 475     wxCoord LogicalToDeviceY(wxCoord y) const;
 476
 477     /**
 478         Converts logical Y coordinate to relative device coordinate, using the
 479         current mapping mode but ignoring the y axis orientation. Use this for
 480         converting a height, for example.
 481     */
 482     wxCoord LogicalToDeviceYRel(wxCoord y) const;
 483
 484     /**
 485         Gets the maximum horizontal extent used in drawing commands so far.
 486     */
 487     wxCoord MaxX() const;
 488
 489     /**
 490         Gets the maximum vertical extent used in drawing commands so far.
 491     */
 492     wxCoord MaxY() const;
 493
 494     /**
 495         Gets the minimum horizontal extent used in drawing commands so far.
 496     */
 497     wxCoord MinX() const;
 498
 499     /**
 500         Gets the minimum vertical extent used in drawing commands so far.
 501     */
 502     wxCoord MinY() const;
 503
 504     /**
 505         Returns @true if the DC is ok to use. @false values arise from being
 506         unable to write the file.
 507     */
 508     bool Ok();
 509
 510     /**
 511         Resets the bounding box. After a call to this function, the bounding
 512         box doesn't contain anything.
 513
 514         @see CalcBoundingBox()
 515     */
 516     void ResetBoundingBox();
 517
 518     /**
 519         Sets the x and y axis orientation (i.e., the direction from lowest to
 520         highest values on the axis). The default orientation is the natural
 521         orientation, e.g. x axis from left to right and y axis from bottom up.
 522
 523         @param xLeftRight
 524             @true to set the x axis orientation to the natural left to right
 525             orientation, @false to invert it.
 526         @param yBottomUp
 527             @true to set the y axis orientation to the natural bottom up
 528             orientation, @false to invert it.
 529     */
 530     void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
 531
 532     /**
 533         Sets the current background brush for the DC.
 534     */
 535     void SetBackground(const wxBrush& brush);
 536
 537     /**
 538         @a mode may be one of wxSOLID and wxTRANSPARENT. This setting determines
 539         whether text will be drawn with a background colour or not.
 540     */
 541     void SetBackgroundMode(int mode);
 542
 543     /**
 544         Sets the current brush for the DC. If the argument is wxNullBrush, the
 545         current brush is selected out of the device context, and the original
 546         brush restored, allowing the current brush to be destroyed safely.
 547
 548         @see wxBrush, wxMemoryDC (for the interpretation of colours
 549              when drawing into a monochrome bitmap).
 550     */
 551     void SetBrush(const wxBrush& brush);
 552
 553     //@{
 554     /**
 555         Not implemented.
 556     */
 557     void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width,
 558                            wxCoord height);
 559     void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
 560     void SetClippingRegion(const wxRect& rect);
 561     void SetClippingRegion(const wxRegion& region);
 562     //@}
 563
 564     /**
 565         Sets the device origin (i.e., the origin in pixels after scaling has
 566         been applied). This function may be useful in Windows printing
 567         operations for placing a graphic on a page.
 568     */
 569     void SetDeviceOrigin(wxCoord x, wxCoord y);
 570
 571     /**
 572         Sets the current font for the DC. It must be a valid font, in
 573         particular you should not pass @c wxNullFont to this method.
 574
 575         @see wxFont
 576     */
 577     void SetFont(const wxFont& font);
 578
 579     /**
 580         Does the same as wxDC::SetLogicalFunction(), except that only wxCOPY is
 581         available. Trying to set one of the other values will fail.
 582     */
 583     void SetLogicalFunction(wxRasterOperationMode function);
 584
 585     /**
 586         The mapping mode of the device context defines the unit of measurement
 587         used to convert logical units to device units. Note that in X, text
 588         drawing isn't handled consistently with the mapping mode; a font is
 589         always specified in point size. However, setting the user scale scales
 590         the text appropriately. In Windows, scalable TrueType fonts are always
 591         used; in X, results depend on availability of fonts, but usually a
 592         reasonable match is found.
 593
 594         Note that the coordinate origin should ideally be selectable, but for
 595         now is always at the top left of the screen/printer.
 596
 597         Drawing to a Windows printer device context under UNIX uses the current
 598         mapping mode, but mapping mode is currently ignored for PostScript
 599         output.
 600
 601         The mapping mode can be one of the following:
 602         - wxMM_TWIPS    - Each logical unit is 1/20 of a point, or 1/1440 of an
 603                           inch.
 604         - wxMM_POINTS   - Each logical unit is a point, or 1/72 of an inch.
 605         - wxMM_METRIC   - Each logical unit is 1 mm.
 606         - wxMM_LOMETRIC - Each logical unit is 1/10 of a mm.
 607         - wxMM_TEXT     - Each logical unit is 1 pixel.
 608     */
 609     void SetMapMode(int mode);
 610
 611     /**
 612         Not implemented.
 613     */
 614     void SetPalette(const wxPalette& palette);
 615
 616     /**
 617         Sets the current pen for the DC. If the argument is wxNullPen, the
 618         current pen is selected out of the device context, and the original pen
 619         restored.
 620
 621         @see wxMemoryDC (for the interpretation of colours when drawing into a
 622              monochrome bitmap)
 623     */
 624     void SetPen(const wxPen& pen);
 625
 626     /**
 627         Sets the current text background colour for the DC.
 628     */
 629     void SetTextBackground(const wxColour& colour);
 630
 631     /**
 632         Sets the current text foreground colour for the DC.
 633
 634         @see wxMemoryDC (for the interpretation of colours when drawing into a
 635              monochrome bitmap)
 636     */
 637     void SetTextForeground(const wxColour& colour);
 638
 639     /**
 640         Sets the user scaling factor, useful for applications which require
 641         "zooming".
 642     */
 643     void SetUserScale(double xScale, double yScale);
 644
 645     /**
 646         Does nothing.
 647     */
 648     bool StartDoc(const wxString& message);
 649 };
 650