interface/dcsvg.h

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