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 the CreateContext calls.., this can be either directly using a renderer
 196     instance, or indirectly using the static convenience CreateXXX functions of
 197     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 = dc.CreateGraphicsContext();
 207
 208         if (gc)
 209         {
 210             // make a path that contains a circle and some lines, centered at 100,100
 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     /**
 239         Clips drawings to the rectangle.
 240     */
 241     void Clip(const wxRegion& region);
 242     void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
 243     //@}
 244
 245     /**
 246         Concatenates the passed in transform with the current transform of this context
 247     */
 248     void ConcatTransform(const wxGraphicsMatrix& matrix);
 249
 250     //@{
 251     /**
 252         Creates a wxGraphicsContext from a wxWindow.
 253
 254         @see wxGraphicsRenderer:: CreateContext
 255     */
 256     wxGraphicsContext* Create(const wxWindowDC& dc);
 257     wxGraphicsContext* Create(wxWindow* window);
 258     //@}
 259
 260     /**
 261         Creates a native brush from a wxBrush.
 262     */
 263     wxGraphicsBrush CreateBrush(const wxBrush& brush) const;
 264
 265     /**
 266         Creates a native graphics font from a wxFont and a text colour.
 267     */
 268     wxGraphicsFont CreateFont(const wxFont& font,
 269                               const wxColour& col = wxBLACK) const;
 270
 271     /**
 272         Creates a wxGraphicsContext from a native context. This native context must be
 273         eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a
 274         cairo_t pointer for cairo.
 275
 276         Creates a wxGraphicsContext from a native window.
 277
 278         @see wxGraphicsRenderer:: CreateContextFromNativeContext
 279     */
 280     wxGraphicsContext* CreateFromNative(void* context);
 281
 282     /**
 283         @see wxGraphicsRenderer:: CreateContextFromNativeWindow
 284     */
 285     wxGraphicsContext* CreateFromNativeWindow(void* window);
 286
 287     /**
 288         Creates a native brush, having a linear gradient, starting at (x1,y1) with
 289         color c1 to (x2,y2) with color c2
 290     */
 291     wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
 292             wxDouble y1,
 293             wxDouble x2,
 294             wxDouble y2,
 295             const wxColouramp;c1,
 296             const wxColouramp;c2) const;
 297
 298     /**
 299         Creates a native affine transformation matrix from the passed in values. The
 300         defaults result in an identity matrix.
 301     */
 302     wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 303                                   wxDouble c = 0.0,
 304                                   wxDouble d = 1.0,
 305                                   wxDouble tx = 0.0,
 306                                   wxDouble ty = 0.0) const;
 307
 308     /**
 309         Creates a native graphics path which is initially empty.
 310     */
 311     wxGraphicsPath CreatePath() const;
 312
 313     /**
 314         Creates a native pen from a wxPen.
 315     */
 316     wxGraphicsPen CreatePen(const wxPen& pen) const;
 317
 318     /**
 319         Creates a native brush, having a radial gradient originating at (xo,yc) with
 320         color oColour and ends on a circle around (xc,yc) with radius r and color cColour
 321     */
 322     wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo,
 323             wxDouble yo,
 324             wxDouble xc,
 325             wxDouble yc,
 326             wxDouble radius,
 327             const wxColour& oColor,
 328             const wxColour& cColor) const;
 329
 330     /**
 331         Draws the bitmap. In case of a mono bitmap, this is treated as a mask and the
 332         current brushed is used for filling.
 333     */
 334     void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y,
 335                     wxDouble w, wxDouble h);
 336
 337     /**
 338         Draws an ellipse.
 339     */
 340     void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
 341
 342     /**
 343         Draws the icon.
 344     */
 345     void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y,
 346                   wxDouble w, wxDouble h);
 347
 348     /**
 349         Draws a polygon.
 350     */
 351     void DrawLines(size_t n, const wxPoint2DDouble* points,
 352                    int fillStyle = wxODDEVEN_RULE);
 353
 354     /**
 355         Draws the path by first filling and then stroking.
 356     */
 357     void DrawPath(const wxGraphicsPath& path,
 358                   int fillStyle = wxODDEVEN_RULE);
 359
 360     /**
 361         Draws a rectangle.
 362     */
 363     void DrawRectangle(wxDouble x, wxDouble y, wxDouble w,
 364                        wxDouble h);
 365
 366     /**
 367         Draws a rounded rectangle.
 368     */
 369     void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
 370                               wxDouble h,
 371                               wxDouble radius);
 372
 373     //@{
 374     /**
 375         Draws a text at the defined position, at the given angle.
 376     */
 377     void DrawText(const wxString& str, wxDouble x, wxDouble y,
 378                   wxDouble angle);
 379     void DrawText(const wxString& str, wxDouble x, wxDouble y);
 380     //@}
 381
 382     /**
 383         Fills the path with the current brush.
 384     */
 385     void FillPath(const wxGraphicsPath& path,
 386                   int fillStyle = wxODDEVEN_RULE);
 387
 388     /**
 389         Returns the native context (CGContextRef for Core Graphics, Graphics pointer
 390         for GDIPlus and cairo_t pointer for cairo).
 391     */
 392     void* GetNativeContext();
 393
 394     /**
 395         Fills the @a widths array with the widths from the beginning of
 396         @a text to the corresponding character of @e text.
 397     */
 398     void GetPartialTextExtents(const wxString& text,
 399                                wxArrayDouble& widths) const;
 400
 401     /**
 402         Gets the dimensions of the string using the currently selected font.
 403         @e string is the text string to measure, @e w and @e h are
 404         the total width and height respectively, @a descent is the
 405         dimension from the baseline of the font to the bottom of the
 406         descender, and @a externalLeading is any extra vertical space added
 407         to the font by the font designer (usually is zero).
 408     */
 409     void GetTextExtent(const wxString& text, wxDouble* width,
 410                        wxDouble* height,
 411                        wxDouble* descent,
 412                        wxDouble* externalLeading) const;
 413
 414     /**
 415         Gets the current transformation matrix of this context.
 416     */
 417     wxGraphicsMatrix GetTransform() const;
 418
 419     /**
 420         Resets the clipping to original shape.
 421     */
 422     void ResetClip();
 423
 424     /**
 425         Rotates the current transformation matrix (radians),
 426     */
 427     void Rotate(wxDouble angle);
 428
 429     /**
 430         Scales the current transformation matrix.
 431     */
 432     void Scale(wxDouble xScale, wxDouble yScale);
 433
 434     //@{
 435     /**
 436         Sets the brush for filling paths.
 437     */
 438     void SetBrush(const wxBrush& brush);
 439     void SetBrush(const wxGraphicsBrush& brush);
 440     //@}
 441
 442     //@{
 443     /**
 444         Sets the font for drawing text.
 445     */
 446     void SetFont(const wxFont& font, const wxColour& colour);
 447     void SetFont(const wxGraphicsFont& font);
 448     //@}
 449
 450     //@{
 451     /**
 452         Sets the pen used for stroking.
 453     */
 454     void SetPen(const wxGraphicsPen& pen);
 455     void SetPen(const wxPen& pen);
 456     //@}
 457
 458     /**
 459         Sets the current transformation matrix of this context
 460     */
 461     void SetTransform(const wxGraphicsMatrix& matrix);
 462
 463     /**
 464         Strokes a single line.
 465     */
 466     void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2,
 467                     wxDouble y2);
 468
 469     //@{
 470     /**
 471         Stroke disconnected lines from begin to end points, fastest method available
 472         for this purpose.
 473     */
 474     void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints,
 475                      const wxPoint2DDouble* endPoints);
 476     void StrokeLines(size_t n, const wxPoint2DDouble* points);
 477     //@}
 478
 479     /**
 480         Strokes along a path with the current pen.
 481     */
 482     void StrokePath(const wxGraphicsPath& path);
 483
 484     /**
 485         Translates the current transformation matrix.
 486     */
 487     void Translate(wxDouble dx, wxDouble dy);
 488 };
 489
 490
 491
 492 /**
 493     @class wxGraphicsRenderer
 494     @wxheader{graphics.h}
 495
 496     A wxGraphicsRenderer is the instance corresponding to the rendering engine
 497     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.
 498
 499     @library{wxcore}
 500     @category{FIXME}
 501 */
 502 class wxGraphicsRenderer : public wxObject
 503 {
 504 public:
 505     /**
 506         Creates a native brush from a wxBrush.
 507     */
 508     wxGraphicsBrush CreateBrush(const wxBrush& brush);
 509
 510     //@{
 511     /**
 512         Creates a wxGraphicsContext from a wxWindow.
 513     */
 514     wxGraphicsContext* CreateContext(const wxWindowDC& dc);
 515     wxGraphicsContext* CreateContext(wxWindow* window);
 516     //@}
 517
 518     /**
 519         Creates a wxGraphicsContext from a native context. This native context must be
 520         eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a cairo_t pointer for cairo.
 521     */
 522     wxGraphicsContext* CreateContextFromNativeContext(void* context);
 523
 524     /**
 525         Creates a wxGraphicsContext from a native window.
 526     */
 527     wxGraphicsContext* CreateContextFromNativeWindow(void* window);
 528
 529     /**
 530         Creates a native graphics font from a wxFont and a text colour.
 531     */
 532     wxGraphicsFont CreateFont(const wxFont& font,
 533                               const wxColour& col = wxBLACK);
 534
 535     /**
 536         Creates a native brush, having a linear gradient, starting at (x1,y1) with
 537         color c1 to (x2,y2) with color c2
 538     */
 539     wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
 540             wxDouble y1,
 541             wxDouble x2,
 542             wxDouble y2,
 543             const wxColouramp;c1,
 544             const wxColouramp;c2);
 545
 546     /**
 547         Creates a native affine transformation matrix from the passed in values. The
 548         defaults result in an identity matrix.
 549     */
 550     wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 551                                   wxDouble c = 0.0,
 552                                   wxDouble d = 1.0,
 553                                   wxDouble tx = 0.0,
 554                                   wxDouble ty = 0.0);
 555
 556     /**
 557         Creates a native graphics path which is initially empty.
 558     */
 559     wxGraphicsPath CreatePath();
 560
 561     /**
 562         Creates a native pen from a wxPen.
 563     */
 564     wxGraphicsPen CreatePen(const wxPen& pen);
 565
 566     /**
 567         Creates a native brush, having a radial gradient originating at (xo,yc) with
 568         color oColour and ends on a circle around (xc,yc) with radius r and color cColour
 569     */
 570     wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo,
 571             wxDouble yo,
 572             wxDouble xc,
 573             wxDouble yc,
 574             wxDouble radius,
 575             const wxColour& oColour,
 576             const wxColour& cColour);
 577
 578     /**
 579         Returns the default renderer on this platform. On OS X this is the Core
 580         Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and on GTK we currently default to the cairo renderer.
 581     */
 582     wxGraphicsRenderer* GetDefaultRenderer();
 583 };
 584
 585
 586
 587 /**
 588     @class wxGraphicsBrush
 589     @wxheader{graphics.h}
 590
 591
 592     @library{wxcore}
 593     @category{FIXME}
 594 */
 595 class wxGraphicsBrush : public wxGraphicsObject
 596 {
 597 public:
 598
 599 };
 600
 601
 602
 603 /**
 604     @class wxGraphicsFont
 605     @wxheader{graphics.h}
 606
 607
 608     @library{wxcore}
 609     @category{FIXME}
 610 */
 611 class wxGraphicsFont : public wxGraphicsObject
 612 {
 613 public:
 614
 615 };
 616
 617
 618
 619 /**
 620     @class wxGraphicsPen
 621     @wxheader{graphics.h}
 622
 623
 624     @library{wxcore}
 625     @category{FIXME}
 626 */
 627 class wxGraphicsPen : public wxGraphicsObject
 628 {
 629 public:
 630
 631 };
 632
 633
 634
 635 /**
 636     @class wxGraphicsMatrix
 637     @wxheader{graphics.h}
 638
 639     A wxGraphicsMatrix is a native representation of an affine matrix. The contents
 640     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.
 641
 642     @library{wxcore}
 643     @category{FIXME}
 644 */
 645 class wxGraphicsMatrix : public wxGraphicsObject
 646 {
 647 public:
 648     //@{
 649     /**
 650
 651     */
 652     void Concat(const wxGraphicsMatrix* t);
 653     void Concat(const wxGraphicsMatrix& t);
 654     //@}
 655
 656     /**
 657         Returns the component values of the matrix via the argument pointers.
 658     */
 659     void Get(wxDouble* a = NULL, wxDouble* b = NULL, wxDouble* c = NULL,
 660              wxDouble* d = NULL, wxDouble* tx = NULL,
 661              wxDouble* ty = NULL) const;
 662
 663     /**
 664         Returns the native representation of the matrix. For CoreGraphics this is a
 665         CFAffineMatrix pointer. For GDIPlus a Matrix Pointer and for Cairo a cairo_matrix_t pointer.
 666     */
 667     void* GetNativeMatrix() const;
 668
 669     /**
 670         Inverts the matrix.
 671     */
 672     void Invert();
 673
 674     /**
 675         Returns @true if the elements of the transformation matrix are equal.
 676     */
 677     bool IsEqual(const wxGraphicsMatrix& t) const;
 678
 679     /**
 680         Return @true if this is the identity matrix.
 681     */
 682     bool IsIdentity() const;
 683
 684     /**
 685         Rotates this matrix (radians).
 686     */
 687     void Rotate(wxDouble angle);
 688
 689     /**
 690         Scales this matrix.
 691     */
 692     void Scale(wxDouble xScale, wxDouble yScale);
 693
 694     /**
 695         Sets the matrix to the respective values (default values are the identity
 696         matrix)
 697     */
 698     void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0,
 699              wxDouble d = 1.0, wxDouble tx = 0.0,
 700              wxDouble ty = 0.0);
 701
 702     /**
 703         Applies this matrix to a distance (ie. performs all transforms except
 704         translations)
 705     */
 706     void TransformDistance(wxDouble* dx, wxDouble* dy) const;
 707
 708     /**
 709         Applies this matrix to a point.
 710     */
 711     void TransformPoint(wxDouble* x, wxDouble* y) const;
 712
 713     /**
 714         Translates this matrix.
 715     */
 716     void Translate(wxDouble dx, wxDouble dy);
 717 };
 718