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, int 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, int fill_style = wxODDEVEN_RULE);
 234     void DrawPolygon(wxList* points, wxCoord xoffset = 0,
 235                      wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE);
 236     //@}
 237
 238     /**
 239         Draws a rectangle with the given top left corner, and with the given
 240         size.  The current pen is used for the outline and the current brush
 241         for filling the shape.
 242     */
 243     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 244
 245     /**
 246         Draws the text rotated by @a angle degrees.
 247
 248         The wxMSW wxDC and wxSVGFileDC rotate the text around slightly
 249         different points, depending on the size of the font.
 250     */
 251     void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
 252                          double angle);
 253
 254     /**
 255         Draws a rectangle with the given top left corner, and with the given
 256         size.  The corners are quarter-circles using the given radius. The
 257         current pen is used for the outline and the current brush for filling
 258         the shape.
 259
 260         If @a radius is positive, the value is assumed to be the radius of the
 261         rounded corner. If @a radius is negative, the absolute value is assumed
 262         to be the @e proportion of the smallest dimension of the rectangle.
 263         This means that the corner can be a sensible size relative to the size
 264         of the rectangle, and also avoids the strange effects X produces when
 265         the corners are too big for the rectangle.
 266     */
 267     void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
 268                               wxCoord height, double radius = 20);
 269
 270     /**
 271         Draws a spline between all given control points, using the current pen.
 272         The programmer is responsible for deleting the list of points.
 273         The spline is drawn using a series of lines, using an algorithm taken from
 274         the X drawing program "XFIG".
 275     */
 276     void DrawSpline(const wxPointList* points);
 277
 278     /**
 279         Draws a three-point spline using the current pen.
 280     */
 281     void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
 282                     wxCoord x3, wxCoord y3);
 283
 284     /**
 285         Draws a text string at the specified point, using the current text
 286         font, and the current text foreground and background colours.
 287
 288         The coordinates refer to the top-left corner of the rectangle bounding
 289         the string. See wxDC::GetTextExtent() for how to get the dimensions of
 290         a text string, which can be used to position the text more precisely.
 291     */
 292     void DrawText(const wxString& text, wxCoord x, wxCoord y);
 293
 294     /**
 295         Does nothing.
 296     */
 297     void EndDoc();
 298
 299     /**
 300         Does nothing.
 301     */
 302     void EndDrawing();
 303
 304     /**
 305         Does nothing.
 306     */
 307     void EndPage();
 308
 309     /**
 310         Not implemented.
 311     */
 312     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
 313                    int style = wxFLOOD_SURFACE);
 314
 315     //@{
 316     /**
 317         Gets the brush used for painting the background.
 318
 319         @see SetBackground()
 320     */
 321     wxBrush GetBackground() const;
 322     const wxBrush GetBackground() const;
 323     //@}
 324
 325     /**
 326         Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
 327
 328         @see SetBackgroundMode()
 329     */
 330     int GetBackgroundMode() const;
 331
 332     //@{
 333     /**
 334         Gets the current brush.
 335
 336         @see SetBrush()
 337     */
 338     wxBrush GetBrush() const;
 339     const wxBrush GetBrush() const;
 340     //@}
 341
 342     /**
 343         Gets the character height of the currently set font.
 344     */
 345     wxCoord GetCharHeight() const;
 346
 347     /**
 348         Gets the average character width of the currently set font.
 349     */
 350     wxCoord GetCharWidth() const;
 351
 352     /**
 353         Not implemented.
 354     */
 355     void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height);
 356
 357     //@{
 358     /**
 359         Gets the current font.
 360
 361         @see SetFont()
 362     */
 363     wxFont GetFont() const;
 364     const wxFont GetFont() const;
 365     //@}
 366
 367     /**
 368         Gets the current logical function.
 369
 370         @see SetLogicalFunction()
 371     */
 372     int GetLogicalFunction() const;
 373
 374     /**
 375         Gets the mapping mode for the device context.
 376
 377         @see SetMapMode()
 378     */
 379     int GetMapMode() const;
 380
 381     //@{
 382     /**
 383         Gets the current pen.
 384
 385         @see SetPen()
 386     */
 387     wxPen GetPen() const;
 388     const wxPen GetPen() const;
 389     //@}
 390
 391     /**
 392         Not implemented.
 393     */
 394     bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
 395
 396     /**
 397         For a Windows printer device context, this gets the horizontal and
 398         vertical resolution.
 399     */
 400     void GetSize(wxCoord* width, wxCoord* height);
 401
 402     //@{
 403     /**
 404         Gets the current text background colour.
 405
 406         @see 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
 415         @param string
 416             The text string to measure.
 417         @param w
 418             This value will be set to the width after this call.
 419         @param h
 420             This value will be set to the height after this call.
 421         @param descent
 422             The dimension from the baseline of the font to the bottom of the
 423             descender.
 424         @param externalLeading
 425             Any extra vertical space added to the font by the font designer
 426             (usually is zero).
 427         @param font
 428             Specifies an alternative to the currently selected font: but note
 429             that this does not yet work under Windows, so you need to set a
 430             font for the device context first.
 431
 432         @see wxFont, SetFont()
 433     */
 434     void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
 435                        wxCoord* descent = NULL,
 436                        wxCoord* externalLeading = NULL,
 437                        const wxFont* font = NULL) const;
 438
 439     //@{
 440     /**
 441         Gets the current text foreground colour.
 442
 443         @see SetTextForeground()
 444     */
 445     wxColour GetTextForeground() const;
 446     const wxColour GetTextForeground() const;
 447     //@}
 448
 449     /**
 450         Gets the current user scale factor.
 451
 452         @see SetUserScale()
 453     */
 454     void GetUserScale(double* x, double* y) const;
 455
 456     /**
 457         Converts logical X coordinate to device coordinate, using the current
 458         mapping mode.
 459     */
 460     wxCoord LogicalToDeviceX(wxCoord x) const;
 461
 462     /**
 463         Converts logical X coordinate to relative device coordinate, using the
 464         current mapping mode but ignoring the x axis orientation. Use this for
 465         converting a width, for example.
 466     */
 467     wxCoord LogicalToDeviceXRel(wxCoord x) const;
 468
 469     /**
 470         Converts logical Y coordinate to device coordinate, using the current
 471         mapping mode.
 472     */
 473     wxCoord LogicalToDeviceY(wxCoord y) const;
 474
 475     /**
 476         Converts logical Y coordinate to relative device coordinate, using the
 477         current mapping mode but ignoring the y axis orientation. Use this for
 478         converting a height, for example.
 479     */
 480     wxCoord LogicalToDeviceYRel(wxCoord y) const;
 481
 482     /**
 483         Gets the maximum horizontal extent used in drawing commands so far.
 484     */
 485     wxCoord MaxX() const;
 486
 487     /**
 488         Gets the maximum vertical extent used in drawing commands so far.
 489     */
 490     wxCoord MaxY() const;
 491
 492     /**
 493         Gets the minimum horizontal extent used in drawing commands so far.
 494     */
 495     wxCoord MinX() const;
 496
 497     /**
 498         Gets the minimum vertical extent used in drawing commands so far.
 499     */
 500     wxCoord MinY() const;
 501
 502     /**
 503         Returns @true if the DC is ok to use. @false values arise from being
 504         unable to write the file.
 505     */
 506     bool Ok();
 507
 508     /**
 509         Resets the bounding box. After a call to this function, the bounding
 510         box doesn't contain anything.
 511
 512         @see CalcBoundingBox()
 513     */
 514     void ResetBoundingBox();
 515
 516     /**
 517         Sets the x and y axis orientation (i.e., the direction from lowest to
 518         highest values on the axis). The default orientation is the natural
 519         orientation, e.g. x axis from left to right and y axis from bottom up.
 520
 521         @param xLeftRight
 522             @true to set the x axis orientation to the natural left to right
 523             orientation, @false to invert it.
 524         @param yBottomUp
 525             @true to set the y axis orientation to the natural bottom up
 526             orientation, @false to invert it.
 527     */
 528     void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
 529
 530     /**
 531         Sets the current background brush for the DC.
 532     */
 533     void SetBackground(const wxBrush& brush);
 534
 535     /**
 536         @a mode may be one of wxSOLID and wxTRANSPARENT. This setting determines
 537         whether text will be drawn with a background colour or not.
 538     */
 539     void SetBackgroundMode(int mode);
 540
 541     /**
 542         Sets the current brush for the DC. If the argument is wxNullBrush, the
 543         current brush is selected out of the device context, and the original
 544         brush restored, allowing the current brush to be destroyed safely.
 545
 546         @see wxBrush, wxMemoryDC (for the interpretation of colours
 547              when drawing into a monochrome bitmap).
 548     */
 549     void SetBrush(const wxBrush& brush);
 550
 551     //@{
 552     /**
 553         Not implemented.
 554     */
 555     void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width,
 556                            wxCoord height);
 557     void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
 558     void SetClippingRegion(const wxRect& rect);
 559     void SetClippingRegion(const wxRegion& region);
 560     //@}
 561
 562     /**
 563         Sets the device origin (i.e., the origin in pixels after scaling has
 564         been applied). This function may be useful in Windows printing
 565         operations for placing a graphic on a page.
 566     */
 567     void SetDeviceOrigin(wxCoord x, wxCoord y);
 568
 569     /**
 570         Sets the current font for the DC. It must be a valid font, in
 571         particular you should not pass @c wxNullFont to this method.
 572
 573         @see wxFont
 574     */
 575     void SetFont(const wxFont& font);
 576
 577     /**
 578         Does the same as wxDC::SetLogicalFunction(), except that only wxCOPY is
 579         avalaible. Trying to set one of the othe values will fail.
 580     */
 581     void SetLogicalFunction(int function);
 582
 583     /**
 584         The mapping mode of the device context defines the unit of measurement
 585         used to convert logical units to device units. Note that in X, text
 586         drawing isn't handled consistently with the mapping mode; a font is
 587         always specified in point size. However, setting the user scale scales
 588         the text appropriately. In Windows, scalable TrueType fonts are always
 589         used; in X, results depend on availability of fonts, but usually a
 590         reasonable match is found.
 591
 592         Note that the coordinate origin should ideally be selectable, but for
 593         now is always at the top left of the screen/printer.
 594
 595         Drawing to a Windows printer device context under UNIX uses the current
 596         mapping mode, but mapping mode is currently ignored for PostScript
 597         output.
 598
 599         The mapping mode can be one of the following:
 600         - wxMM_TWIPS    - Each logical unit is 1/20 of a point, or 1/1440 of an
 601                           inch.
 602         - wxMM_POINTS   - Each logical unit is a point, or 1/72 of an inch.
 603         - wxMM_METRIC   - Each logical unit is 1 mm.
 604         - wxMM_LOMETRIC - Each logical unit is 1/10 of a mm.
 605         - wxMM_TEXT     - Each logical unit is 1 pixel.
 606     */
 607     void SetMapMode(int mode);
 608
 609     /**
 610         Not implemented.
 611     */
 612     void SetPalette(const wxPalette& palette);
 613
 614     /**
 615         Sets the current pen for the DC. If the argument is wxNullPen, the
 616         current pen is selected out of the device context, and the original pen
 617         restored.
 618
 619         @see wxMemoryDC (for the interpretation of colours when drawing into a
 620              monochrome bitmap)
 621     */
 622     void SetPen(const wxPen& pen);
 623
 624     /**
 625         Sets the current text background colour for the DC.
 626     */
 627     void SetTextBackground(const wxColour& colour);
 628
 629     /**
 630         Sets the current text foreground colour for the DC.
 631
 632         @see wxMemoryDC (for the interpretation of colours when drawing into a
 633              monochrome bitmap)
 634     */
 635     void SetTextForeground(const wxColour& colour);
 636
 637     /**
 638         Sets the user scaling factor, useful for applications which require
 639         "zooming".
 640     */
 641     void SetUserScale(double xScale, double yScale);
 642
 643     /**
 644         Does nothing.
 645     */
 646     bool StartDoc(const wxString& message);
 647 };
 648