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