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