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 EndPage();
 305
 306     /**
 307         Not implemented.
 308     */
 309     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
 310                    wxFloodFillStyle style = wxFLOOD_SURFACE);
 311
 312     //@{
 313     /**
 314         Gets the brush used for painting the background.
 315
 316         @see SetBackground()
 317     */
 318     wxBrush GetBackground() const;
 319     const wxBrush GetBackground() const;
 320     //@}
 321
 322     /**
 323         Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
 324
 325         @see SetBackgroundMode()
 326     */
 327     int GetBackgroundMode() const;
 328
 329     //@{
 330     /**
 331         Gets the current brush.
 332
 333         @see SetBrush()
 334     */
 335     wxBrush GetBrush() const;
 336     const wxBrush GetBrush() const;
 337     //@}
 338
 339     /**
 340         Gets the character height of the currently set font.
 341     */
 342     wxCoord GetCharHeight() const;
 343
 344     /**
 345         Gets the average character width of the currently set font.
 346     */
 347     wxCoord GetCharWidth() const;
 348
 349     /**
 350         Not implemented.
 351     */
 352     void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const;
 353
 354     //@{
 355     /**
 356         Gets the current font.
 357
 358         @see SetFont()
 359     */
 360     wxFont GetFont() const;
 361     const wxFont GetFont() const;
 362     //@}
 363
 364     /**
 365         Gets the current logical function.
 366
 367         @see SetLogicalFunction()
 368     */
 369     wxRasterOperationMode GetLogicalFunction() const;
 370
 371     /**
 372         Gets the mapping mode for the device context.
 373
 374         @see SetMapMode()
 375     */
 376     wxMappingMode GetMapMode() const;
 377
 378     //@{
 379     /**
 380         Gets the current pen.
 381
 382         @see SetPen()
 383     */
 384     wxPen GetPen() const;
 385     const wxPen GetPen() const;
 386     //@}
 387
 388     /**
 389         Not implemented.
 390     */
 391     bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
 392
 393     /**
 394         For a Windows printer device context, this gets the horizontal and
 395         vertical resolution.
 396     */
 397     void GetSize(wxCoord* width, wxCoord* height);
 398
 399     //@{
 400     /**
 401         Gets the current text background colour.
 402
 403         @see SetTextBackground()
 404     */
 405     wxColour GetTextBackground() const;
 406     const wxColour& GetTextBackground() const;
 407     //@}
 408
 409     /**
 410         Gets the dimensions of the string using the currently selected font.
 411
 412         @param string
 413             The text string to measure.
 414         @param w
 415             This value will be set to the width after this call.
 416         @param h
 417             This value will be set to the height after this call.
 418         @param descent
 419             The dimension from the baseline of the font to the bottom of the
 420             descender.
 421         @param externalLeading
 422             Any extra vertical space added to the font by the font designer
 423             (usually is zero).
 424         @param font
 425             Specifies an alternative to the currently selected font: but note
 426             that this does not yet work under Windows, so you need to set a
 427             font for the device context first.
 428
 429         @see wxFont, SetFont()
 430     */
 431     void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
 432                        wxCoord* descent = NULL,
 433                        wxCoord* externalLeading = NULL,
 434                        const wxFont* font = NULL) const;
 435
 436     //@{
 437     /**
 438         Gets the current text foreground colour.
 439
 440         @see SetTextForeground()
 441     */
 442     wxColour GetTextForeground() const;
 443     const wxColour GetTextForeground() const;
 444     //@}
 445
 446     /**
 447         Gets the current user scale factor.
 448
 449         @see SetUserScale()
 450     */
 451     void GetUserScale(double* x, double* y) const;
 452
 453     /**
 454         Converts logical X coordinate to device coordinate, using the current
 455         mapping mode.
 456     */
 457     wxCoord LogicalToDeviceX(wxCoord x) const;
 458
 459     /**
 460         Converts logical X coordinate to relative device coordinate, using the
 461         current mapping mode but ignoring the x axis orientation. Use this for
 462         converting a width, for example.
 463     */
 464     wxCoord LogicalToDeviceXRel(wxCoord x) const;
 465
 466     /**
 467         Converts logical Y coordinate to device coordinate, using the current
 468         mapping mode.
 469     */
 470     wxCoord LogicalToDeviceY(wxCoord y) const;
 471
 472     /**
 473         Converts logical Y coordinate to relative device coordinate, using the
 474         current mapping mode but ignoring the y axis orientation. Use this for
 475         converting a height, for example.
 476     */
 477     wxCoord LogicalToDeviceYRel(wxCoord y) const;
 478
 479     /**
 480         Gets the maximum horizontal extent used in drawing commands so far.
 481     */
 482     wxCoord MaxX() const;
 483
 484     /**
 485         Gets the maximum vertical extent used in drawing commands so far.
 486     */
 487     wxCoord MaxY() const;
 488
 489     /**
 490         Gets the minimum horizontal extent used in drawing commands so far.
 491     */
 492     wxCoord MinX() const;
 493
 494     /**
 495         Gets the minimum vertical extent used in drawing commands so far.
 496     */
 497     wxCoord MinY() const;
 498
 499     /**
 500         Returns @true if the DC is ok to use. @false values arise from being
 501         unable to write the file.
 502     */
 503     bool IsOk();
 504
 505     /**
 506         Resets the bounding box. After a call to this function, the bounding
 507         box doesn't contain anything.
 508
 509         @see CalcBoundingBox()
 510     */
 511     void ResetBoundingBox();
 512
 513     /**
 514         Sets the x and y axis orientation (i.e., the direction from lowest to
 515         highest values on the axis). The default orientation is the natural
 516         orientation, e.g. x axis from left to right and y axis from bottom up.
 517
 518         @param xLeftRight
 519             @true to set the x axis orientation to the natural left to right
 520             orientation, @false to invert it.
 521         @param yBottomUp
 522             @true to set the y axis orientation to the natural bottom up
 523             orientation, @false to invert it.
 524     */
 525     void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
 526
 527     /**
 528         Sets the current background brush for the DC.
 529     */
 530     void SetBackground(const wxBrush& brush);
 531
 532     /**
 533         @a mode may be one of wxSOLID and wxTRANSPARENT. This setting determines
 534         whether text will be drawn with a background colour or not.
 535     */
 536     void SetBackgroundMode(int mode);
 537
 538     /**
 539         Sets the current brush for the DC. If the argument is wxNullBrush, the
 540         current brush is selected out of the device context, and the original
 541         brush restored, allowing the current brush to be destroyed safely.
 542
 543         @see wxBrush, wxMemoryDC (for the interpretation of colours
 544              when drawing into a monochrome bitmap).
 545     */
 546     void SetBrush(const wxBrush& brush);
 547
 548     //@{
 549     /**
 550         Not implemented.
 551     */
 552     void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width,
 553                            wxCoord height);
 554     void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
 555     void SetClippingRegion(const wxRect& rect);
 556     void SetClippingRegion(const wxRegion& region);
 557     //@}
 558
 559     /**
 560         Sets the device origin (i.e., the origin in pixels after scaling has
 561         been applied). This function may be useful in Windows printing
 562         operations for placing a graphic on a page.
 563     */
 564     void SetDeviceOrigin(wxCoord x, wxCoord y);
 565
 566     /**
 567         Sets the current font for the DC. It must be a valid font, in
 568         particular you should not pass @c wxNullFont to this method.
 569
 570         @see wxFont
 571     */
 572     void SetFont(const wxFont& font);
 573
 574     /**
 575         Does the same as wxDC::SetLogicalFunction(), except that only wxCOPY is
 576         available. Trying to set one of the other values will fail.
 577     */
 578     void SetLogicalFunction(wxRasterOperationMode function);
 579
 580     /**
 581         The mapping mode of the device context defines the unit of measurement
 582         used to convert logical units to device units. Note that in X, text
 583         drawing isn't handled consistently with the mapping mode; a font is
 584         always specified in point size. However, setting the user scale scales
 585         the text appropriately. In Windows, scalable TrueType fonts are always
 586         used; in X, results depend on availability of fonts, but usually a
 587         reasonable match is found.
 588
 589         Note that the coordinate origin should ideally be selectable, but for
 590         now is always at the top left of the screen/printer.
 591
 592         Drawing to a Windows printer device context under UNIX uses the current
 593         mapping mode, but mapping mode is currently ignored for PostScript
 594         output.
 595
 596         The mapping mode can be one of the following:
 597         - wxMM_TWIPS    - Each logical unit is 1/20 of a point, or 1/1440 of an
 598                           inch.
 599         - wxMM_POINTS   - Each logical unit is a point, or 1/72 of an inch.
 600         - wxMM_METRIC   - Each logical unit is 1 mm.
 601         - wxMM_LOMETRIC - Each logical unit is 1/10 of a mm.
 602         - wxMM_TEXT     - Each logical unit is 1 pixel.
 603     */
 604     void SetMapMode(wxMappingMode mode);
 605
 606     /**
 607         Not implemented.
 608     */
 609     void SetPalette(const wxPalette& palette);
 610
 611     /**
 612         Sets the current pen for the DC. If the argument is wxNullPen, the
 613         current pen is selected out of the device context, and the original pen
 614         restored.
 615
 616         @see wxMemoryDC (for the interpretation of colours when drawing into a
 617              monochrome bitmap)
 618     */
 619     void SetPen(const wxPen& pen);
 620
 621     /**
 622         Sets the current text background colour for the DC.
 623     */
 624     void SetTextBackground(const wxColour& colour);
 625
 626     /**
 627         Sets the current text foreground colour for the DC.
 628
 629         @see wxMemoryDC (for the interpretation of colours when drawing into a
 630              monochrome bitmap)
 631     */
 632     void SetTextForeground(const wxColour& colour);
 633
 634     /**
 635         Sets the user scaling factor, useful for applications which require
 636         "zooming".
 637     */
 638     void SetUserScale(double xScale, double yScale);
 639
 640     /**
 641         Does nothing.
 642     */
 643     bool StartDoc(const wxString& message);
 644 };
 645