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