interface/graphics.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        graphics.h
   3 // Purpose:     interface of wxGraphicsPath
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxGraphicsPath
  11     @wxheader{graphics.h}
  12
  13     A wxGraphicsPath is a native representation of an geometric path. The contents
  14     are specific an private to the respective renderer. Instances are ref counted and can
  15     therefore be assigned as usual. The only way to get a valid instance is via a
  16     CreatePath call on the graphics context or the renderer instance.
  17
  18     @library{wxcore}
  19     @category{FIXME}
  20 */
  21 class wxGraphicsPath : public wxGraphicsObject
  22 {
  23 public:
  24     //@{
  25     /**
  26
  27     */
  28     void AddArc(wxDouble x, wxDouble y, wxDouble r,
  29                 wxDouble startAngle,
  30                 wxDouble endAngle, bool clockwise);
  31     void AddArc(const wxPoint2DDouble& c, wxDouble r,
  32                 wxDouble startAngle,
  33                 wxDouble endAngle,
  34                 bool clockwise);
  35     //@}
  36
  37     /**
  38         Appends a an arc to two tangents connecting (current) to (x1,y1) and (x1,y1) to
  39         (x2,y2), also a straight line from (current) to (x1,y1).
  40     */
  41     void AddArcToPoint(wxDouble x1, wxDouble y1, wxDouble x2,
  42                        wxDouble y2,
  43                        wxDouble r);
  44
  45     /**
  46         Appends a circle around (x,y) with radius r as a new closed subpath.
  47     */
  48     void AddCircle(wxDouble x, wxDouble y, wxDouble r);
  49
  50     //@{
  51     /**
  52
  53     */
  54     void AddCurveToPoint(wxDouble cx1, wxDouble cy1, wxDouble cx2,
  55                          wxDouble cy2,
  56                          wxDouble x,
  57                          wxDouble y);
  58     void AddCurveToPoint(const wxPoint2DDouble& c1,
  59                          const wxPoint2DDouble& c2,
  60                          const wxPoint2DDouble& e);
  61     //@}
  62
  63     /**
  64         Appends an ellipse fitting into the passed in rectangle.
  65     */
  66     void AddEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
  67
  68     //@{
  69     /**
  70
  71     */
  72     void AddLineToPoint(wxDouble x, wxDouble y);
  73     void AddLineToPoint(const wxPoint2DDouble& p);
  74     //@}
  75
  76     /**
  77         Adds another path.
  78     */
  79     void AddPath(const wxGraphicsPath& path);
  80
  81     /**
  82         Adds a quadratic Bezier curve from the current point, using a control point and
  83         an end point.
  84     */
  85     void AddQuadCurveToPoint(wxDouble cx, wxDouble cy, wxDouble x,
  86                              wxDouble y);
  87
  88     /**
  89         Appends a rectangle as a new closed subpath.
  90     */
  91     void AddRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
  92
  93     /**
  94         Appends a rounded rectangle as a new closed subpath.
  95     */
  96     void AddRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
  97                              wxDouble h,
  98                              wxDouble radius);
  99
 100     /**
 101         Closes the current sub-path.
 102     */
 103     void CloseSubpath();
 104
 105     //@{
 106     /**
 107         Returns @true if the point is within the path.
 108     */
 109     bool Contains(const wxPoint2DDouble& c,
 110                   int fillStyle = wxODDEVEN_RULE) const;
 111     const bool Contains(wxDouble x, wxDouble y,
 112                         int fillStyle = wxODDEVEN_RULE) const;
 113     //@}
 114
 115     //@{
 116     /**
 117         Gets the bounding box enclosing all points (possibly including control points).
 118     */
 119     wxRect2DDouble GetBox() const;
 120     const void GetBox(wxDouble* x, wxDouble* y, wxDouble* w,
 121                       wxDouble* h) const;
 122     //@}
 123
 124     //@{
 125     /**
 126         Gets the last point of the current path, (0,0) if not yet set.
 127     */
 128     void GetCurrentPoint(wxDouble* x, wxDouble* y) const;
 129     const wxPoint2DDouble GetCurrentPoint() const;
 130     //@}
 131
 132     /**
 133         Returns the native path (CGPathRef for Core Graphics, Path pointer for GDIPlus
 134         and a cairo_path_t pointer for cairo).
 135     */
 136     void* GetNativePath() const;
 137
 138     //@{
 139     /**
 140         Begins a new subpath at (x,y)
 141     */
 142     void MoveToPoint(wxDouble x, wxDouble y);
 143     void MoveToPoint(const wxPoint2DDouble& p);
 144     //@}
 145
 146     /**
 147         Transforms each point of this path by the matrix.
 148     */
 149     void Transform(const wxGraphicsMatrix& matrix);
 150
 151     /**
 152         Gives back the native path returned by GetNativePath() because there might be
 153         some deallocations necessary (eg on cairo the native path returned by
 154         GetNativePath is newly allocated each time).
 155     */
 156     void UnGetNativePath(void* p) const;
 157 };
 158
 159
 160
 161 /**
 162     @class wxGraphicsObject
 163     @wxheader{graphics.h}
 164
 165     This class is the superclass of native graphics objects like pens etc. It
 166     allows reference counting. Not instantiated by user code.
 167
 168     @library{wxcore}
 169     @category{FIXME}
 170
 171     @see wxGraphicsBrush, wxGraphicsPen, wxGraphicsMatrix, wxGraphicsPath
 172 */
 173 class wxGraphicsObject : public wxObject
 174 {
 175 public:
 176     /**
 177         Returns the renderer that was used to create this instance, or @NULL if it has
 178         not been initialized yet
 179     */
 180     wxGraphicsRenderer* GetRenderer() const;
 181
 182     /**
 183         Is this object valid (@false) or still empty (@true)?
 184     */
 185     bool IsNull() const;
 186 };
 187
 188
 189
 190 /**
 191     @class wxGraphicsContext
 192     @wxheader{graphics.h}
 193
 194     A wxGraphicsContext instance is the object that is drawn upon. It is created by
 195     a renderer using wxGraphicsRenderer::CreateContext(). This can be either directly
 196     using a renderer instance, or indirectly using the static convenience Create()
 197     functions of wxGraphicsContext that always delegate the task to the default renderer.
 198
 199     @code
 200     void MyCanvas::OnPaint(wxPaintEvent &event)
 201     {
 202         // Create paint DC
 203         wxPaintDC dc(this);
 204
 205         // Create graphics context from it
 206         wxGraphicsContext *gc = wxGraphicsContext::CreateContext( dc );
 207
 208         if (gc)
 209         {
 210             // make a path that contains a circle and some lines
 211             gc->SetPen( *wxRED_PEN );
 212             wxGraphicsPath path = gc->CreatePath();
 213             path.AddCircle( 50.0, 50.0, 50.0 );
 214             path.MoveToPoint(0.0, 50.0);
 215             path.AddLineToPoint(100.0, 50.0);
 216             path.MoveToPoint(50.0, 0.0);
 217             path.AddLineToPoint(50.0, 100.0 );
 218             path.CloseSubpath();
 219             path.AddRectangle(25.0, 25.0, 50.0, 50.0);
 220
 221            gc->StrokePath(path);
 222
 223            delete gc;
 224         }
 225     }
 226     @endcode
 227
 228
 229     @library{wxcore}
 230     @category{FIXME}
 231
 232     @see wxGraphicsRenderer:: CreateContext
 233 */
 234 class wxGraphicsContext : public wxGraphicsObject
 235 {
 236 public:
 237     /**
 238         Creates a wxGraphicsContext from a wxWindow.
 239
 240         @see wxGraphicsRenderer::CreateContext()
 241     */
 242     static wxGraphicsContext* Create( wxWindow* window ) ;
 243
 244     /**
 245         Creates a wxGraphicsContext from a wxWindowDC
 246
 247         @see wxGraphicsRenderer::CreateContext()
 248     */
 249     static wxGraphicsContext* Create( const wxWindowDC& dc) ;
 250
 251     /**
 252         Creates a wxGraphicsContext from a wxMemoryDC
 253
 254         @see wxGraphicsRenderer::CreateContext()
 255     */
 256     static wxGraphicsContext * Create( const wxMemoryDC& dc) ;
 257
 258     /**
 259         Creates a wxGraphicsContext from a wxPrinterDC
 260
 261         @see wxGraphicsRenderer::CreateContext()
 262     */
 263     static wxGraphicsContext * Create( const wxPrinterDC& dc) ;
 264
 265     /**
 266         Clips drawings to the region
 267     */
 268     void Clip(const wxRegion& region);
 269
 270     /**
 271         Clips drawings to the rectangle.
 272     */
 273     void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
 274
 275     /**
 276         Concatenates the passed in transform with the current transform of this context
 277     */
 278     void ConcatTransform(const wxGraphicsMatrix& matrix);
 279
 280
 281     /**
 282         Creates a native brush from a wxBrush.
 283     */
 284     wxGraphicsBrush CreateBrush(const wxBrush& brush) const;
 285
 286     /**
 287         Creates a native graphics font from a wxFont and a text colour.
 288     */
 289     wxGraphicsFont CreateFont(const wxFont& font,
 290                               const wxColour& col = wxBLACK) const;
 291
 292     /**
 293         Creates a wxGraphicsContext from a native context. This native context must be
 294         eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a
 295         cairo_t pointer for cairo.
 296
 297         Creates a wxGraphicsContext from a native window.
 298
 299         @see wxGraphicsRenderer:: CreateContextFromNativeContext
 300     */
 301     wxGraphicsContext* CreateFromNative(void* context);
 302
 303     /**
 304         @see wxGraphicsRenderer:: CreateContextFromNativeWindow
 305     */
 306     wxGraphicsContext* CreateFromNativeWindow(void* window);
 307
 308     /**
 309         Creates a native brush, having a linear gradient, starting at (x1,y1) with
 310         color c1 to (x2,y2) with color c2
 311     */
 312     wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
 313             wxDouble y1,
 314             wxDouble x2,
 315             wxDouble y2,
 316             const wxColouramp;c1,
 317             const wxColouramp;c2) const;
 318
 319     /**
 320         Creates a native affine transformation matrix from the passed in values. The
 321         defaults result in an identity matrix.
 322     */
 323     wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 324                                   wxDouble c = 0.0,
 325                                   wxDouble d = 1.0,
 326                                   wxDouble tx = 0.0,
 327                                   wxDouble ty = 0.0) const;
 328
 329     /**
 330         Creates a native graphics path which is initially empty.
 331     */
 332     wxGraphicsPath CreatePath() const;
 333
 334     /**
 335         Creates a native pen from a wxPen.
 336     */
 337     wxGraphicsPen CreatePen(const wxPen& pen) const;
 338
 339     /**
 340         Creates a native brush, having a radial gradient originating at (xo,yc) with
 341         color oColour and ends on a circle around (xc,yc) with radius r and color cColour
 342     */
 343     wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo,
 344             wxDouble yo,
 345             wxDouble xc,
 346             wxDouble yc,
 347             wxDouble radius,
 348             const wxColour& oColor,
 349             const wxColour& cColor) const;
 350
 351     /**
 352         Draws the bitmap. In case of a mono bitmap, this is treated as a mask and the
 353         current brushed is used for filling.
 354     */
 355     void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y,
 356                     wxDouble w, wxDouble h);
 357
 358     /**
 359         Draws an ellipse.
 360     */
 361     void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
 362
 363     /**
 364         Draws the icon.
 365     */
 366     void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y,
 367                   wxDouble w, wxDouble h);
 368
 369     /**
 370         Draws a polygon.
 371     */
 372     void DrawLines(size_t n, const wxPoint2DDouble* points,
 373                    int fillStyle = wxODDEVEN_RULE);
 374
 375     /**
 376         Draws the path by first filling and then stroking.
 377     */
 378     void DrawPath(const wxGraphicsPath& path,
 379                   int fillStyle = wxODDEVEN_RULE);
 380
 381     /**
 382         Draws a rectangle.
 383     */
 384     void DrawRectangle(wxDouble x, wxDouble y, wxDouble w,
 385                        wxDouble h);
 386
 387     /**
 388         Draws a rounded rectangle.
 389     */
 390     void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
 391                               wxDouble h,
 392                               wxDouble radius);
 393
 394     //@{
 395     /**
 396         Draws a text at the defined position, at the given angle.
 397     */
 398     void DrawText(const wxString& str, wxDouble x, wxDouble y,
 399                   wxDouble angle);
 400     void DrawText(const wxString& str, wxDouble x, wxDouble y);
 401     //@}
 402
 403     /**
 404         Fills the path with the current brush.
 405     */
 406     void FillPath(const wxGraphicsPath& path,
 407                   int fillStyle = wxODDEVEN_RULE);
 408
 409     /**
 410         Returns the native context (CGContextRef for Core Graphics, Graphics pointer
 411         for GDIPlus and cairo_t pointer for cairo).
 412     */
 413     void* GetNativeContext();
 414
 415     /**
 416         Fills the @a widths array with the widths from the beginning of
 417         @a text to the corresponding character of @e text.
 418     */
 419     void GetPartialTextExtents(const wxString& text,
 420                                wxArrayDouble& widths) const;
 421
 422     /**
 423         Gets the dimensions of the string using the currently selected font.
 424         @e string is the text string to measure, @e w and @e h are
 425         the total width and height respectively, @a descent is the
 426         dimension from the baseline of the font to the bottom of the
 427         descender, and @a externalLeading is any extra vertical space added
 428         to the font by the font designer (usually is zero).
 429     */
 430     void GetTextExtent(const wxString& text, wxDouble* width,
 431                        wxDouble* height,
 432                        wxDouble* descent,
 433                        wxDouble* externalLeading) const;
 434
 435     /**
 436         Gets the current transformation matrix of this context.
 437     */
 438     wxGraphicsMatrix GetTransform() const;
 439
 440     /**
 441         Resets the clipping to original shape.
 442     */
 443     void ResetClip();
 444
 445     /**
 446         Rotates the current transformation matrix (radians),
 447     */
 448     void Rotate(wxDouble angle);
 449
 450     /**
 451         Scales the current transformation matrix.
 452     */
 453     void Scale(wxDouble xScale, wxDouble yScale);
 454
 455     //@{
 456     /**
 457         Sets the brush for filling paths.
 458     */
 459     void SetBrush(const wxBrush& brush);
 460     void SetBrush(const wxGraphicsBrush& brush);
 461     //@}
 462
 463     //@{
 464     /**
 465         Sets the font for drawing text.
 466     */
 467     void SetFont(const wxFont& font, const wxColour& colour);
 468     void SetFont(const wxGraphicsFont& font);
 469     //@}
 470
 471     //@{
 472     /**
 473         Sets the pen used for stroking.
 474     */
 475     void SetPen(const wxGraphicsPen& pen);
 476     void SetPen(const wxPen& pen);
 477     //@}
 478
 479     /**
 480         Sets the current transformation matrix of this context
 481     */
 482     void SetTransform(const wxGraphicsMatrix& matrix);
 483
 484     /**
 485         Strokes a single line.
 486     */
 487     void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2,
 488                     wxDouble y2);
 489
 490     //@{
 491     /**
 492         Stroke disconnected lines from begin to end points, fastest method available
 493         for this purpose.
 494     */
 495     void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints,
 496                      const wxPoint2DDouble* endPoints);
 497     void StrokeLines(size_t n, const wxPoint2DDouble* points);
 498     //@}
 499
 500     /**
 501         Strokes along a path with the current pen.
 502     */
 503     void StrokePath(const wxGraphicsPath& path);
 504
 505     /**
 506         Translates the current transformation matrix.
 507     */
 508     void Translate(wxDouble dx, wxDouble dy);
 509 };
 510
 511
 512
 513 /**
 514     @class wxGraphicsRenderer
 515     @wxheader{graphics.h}
 516
 517     A wxGraphicsRenderer is the instance corresponding to the rendering engine
 518     used. There may be multiple instances on a system, if there are different rendering engines present, but there is always one instance per engine, eg there is ONE core graphics renderer instance on OSX. This instance is pointed back to by all objects created by it (wxGraphicsContext, wxGraphicsPath etc). Therefore you can create ag additional instances of paths etc. by calling GetRenderer() and then using the appropriate CreateXXX function.
 519
 520     @library{wxcore}
 521     @category{FIXME}
 522 */
 523 class wxGraphicsRenderer : public wxObject
 524 {
 525 public:
 526     /**
 527         Creates a native brush from a wxBrush.
 528     */
 529     wxGraphicsBrush CreateBrush(const wxBrush& brush);
 530
 531     //@{
 532     /**
 533         Creates a wxGraphicsContext from a wxWindow.
 534     */
 535     wxGraphicsContext* CreateContext(const wxWindowDC& dc);
 536     wxGraphicsContext* CreateContext(wxWindow* window);
 537     //@}
 538
 539     /**
 540         Creates a wxGraphicsContext from a native context. This native context must be
 541         eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a cairo_t pointer for cairo.
 542     */
 543     wxGraphicsContext* CreateContextFromNativeContext(void* context);
 544
 545     /**
 546         Creates a wxGraphicsContext from a native window.
 547     */
 548     wxGraphicsContext* CreateContextFromNativeWindow(void* window);
 549
 550     /**
 551         Creates a native graphics font from a wxFont and a text colour.
 552     */
 553     wxGraphicsFont CreateFont(const wxFont& font,
 554                               const wxColour& col = wxBLACK);
 555
 556     /**
 557         Creates a native brush, having a linear gradient, starting at (x1,y1) with
 558         color c1 to (x2,y2) with color c2
 559     */
 560     wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
 561             wxDouble y1,
 562             wxDouble x2,
 563             wxDouble y2,
 564             const wxColouramp;c1,
 565             const wxColouramp;c2);
 566
 567     /**
 568         Creates a native affine transformation matrix from the passed in values. The
 569         defaults result in an identity matrix.
 570     */
 571     wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 572                                   wxDouble c = 0.0,
 573                                   wxDouble d = 1.0,
 574                                   wxDouble tx = 0.0,
 575                                   wxDouble ty = 0.0);
 576
 577     /**
 578         Creates a native graphics path which is initially empty.
 579     */
 580     wxGraphicsPath CreatePath();
 581
 582     /**
 583         Creates a native pen from a wxPen.
 584     */
 585     wxGraphicsPen CreatePen(const wxPen& pen);
 586
 587     /**
 588         Creates a native brush, having a radial gradient originating at (xo,yc) with
 589         color oColour and ends on a circle around (xc,yc) with radius r and color cColour
 590     */
 591     wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo,
 592             wxDouble yo,
 593             wxDouble xc,
 594             wxDouble yc,
 595             wxDouble radius,
 596             const wxColour& oColour,
 597             const wxColour& cColour);
 598
 599     /**
 600         Returns the default renderer on this platform. On OS X this is the Core
 601         Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and on GTK we currently default to the cairo renderer.
 602     */
 603     wxGraphicsRenderer* GetDefaultRenderer();
 604 };
 605
 606
 607
 608 /**
 609     @class wxGraphicsBrush
 610     @wxheader{graphics.h}
 611
 612
 613     @library{wxcore}
 614     @category{FIXME}
 615 */
 616 class wxGraphicsBrush : public wxGraphicsObject
 617 {
 618 public:
 619
 620 };
 621
 622
 623
 624 /**
 625     @class wxGraphicsFont
 626     @wxheader{graphics.h}
 627
 628
 629     @library{wxcore}
 630     @category{FIXME}
 631 */
 632 class wxGraphicsFont : public wxGraphicsObject
 633 {
 634 public:
 635
 636 };
 637
 638
 639
 640 /**
 641     @class wxGraphicsPen
 642     @wxheader{graphics.h}
 643
 644
 645     @library{wxcore}
 646     @category{FIXME}
 647 */
 648 class wxGraphicsPen : public wxGraphicsObject
 649 {
 650 public:
 651
 652 };
 653
 654
 655
 656 /**
 657     @class wxGraphicsMatrix
 658     @wxheader{graphics.h}
 659
 660     A wxGraphicsMatrix is a native representation of an affine matrix. The contents
 661     are specific and private to the respective renderer. Instances are ref counted and can therefore be assigned as usual. The only way to get a valid instance is via a CreateMatrix call on the graphics context or the renderer instance.
 662
 663     @library{wxcore}
 664     @category{FIXME}
 665 */
 666 class wxGraphicsMatrix : public wxGraphicsObject
 667 {
 668 public:
 669     //@{
 670     /**
 671
 672     */
 673     void Concat(const wxGraphicsMatrix* t);
 674     void Concat(const wxGraphicsMatrix& t);
 675     //@}
 676
 677     /**
 678         Returns the component values of the matrix via the argument pointers.
 679     */
 680     void Get(wxDouble* a = NULL, wxDouble* b = NULL, wxDouble* c = NULL,
 681              wxDouble* d = NULL, wxDouble* tx = NULL,
 682              wxDouble* ty = NULL) const;
 683
 684     /**
 685         Returns the native representation of the matrix. For CoreGraphics this is a
 686         CFAffineMatrix pointer. For GDIPlus a Matrix Pointer and for Cairo a cairo_matrix_t pointer.
 687     */
 688     void* GetNativeMatrix() const;
 689
 690     /**
 691         Inverts the matrix.
 692     */
 693     void Invert();
 694
 695     /**
 696         Returns @true if the elements of the transformation matrix are equal.
 697     */
 698     bool IsEqual(const wxGraphicsMatrix& t) const;
 699
 700     /**
 701         Return @true if this is the identity matrix.
 702     */
 703     bool IsIdentity() const;
 704
 705     /**
 706         Rotates this matrix (radians).
 707     */
 708     void Rotate(wxDouble angle);
 709
 710     /**
 711         Scales this matrix.
 712     */
 713     void Scale(wxDouble xScale, wxDouble yScale);
 714
 715     /**
 716         Sets the matrix to the respective values (default values are the identity
 717         matrix)
 718     */
 719     void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0,
 720              wxDouble d = 1.0, wxDouble tx = 0.0,
 721              wxDouble ty = 0.0);
 722
 723     /**
 724         Applies this matrix to a distance (ie. performs all transforms except
 725         translations)
 726     */
 727     void TransformDistance(wxDouble* dx, wxDouble* dy) const;
 728
 729     /**
 730         Applies this matrix to a point.
 731     */
 732     void TransformPoint(wxDouble* x, wxDouble* y) const;
 733
 734     /**
 735         Translates this matrix.
 736     */
 737     void Translate(wxDouble dx, wxDouble dy);
 738 };
 739