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