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