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