interface/dcsvg.h

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