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