interface/graphics.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        graphics.h
   3 // Purpose:     documentation for wxGraphicsPath class
   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);
 111     bool Contains(wxDouble x, wxDouble y,
 112                   int fillStyle = wxODDEVEN_RULE);
 113     //@}
 114
 115     //@{
 116     /**
 117         Gets the bounding box enclosing all points (possibly including control points).
 118     */
 119     wxRect2DDouble GetBox();
 120     void GetBox(wxDouble* x, wxDouble* y, wxDouble* w,
 121                 wxDouble* h);
 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);
 129     wxPoint2DDouble GetCurrentPoint();
 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();
 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);
 157 };
 158
 159
 160 /**
 161     @class wxGraphicsObject
 162     @wxheader{graphics.h}
 163
 164     This class is the superclass of native graphics objects like pens etc. It
 165     allows reference counting. Not instantiated by user code.
 166
 167     @library{wxcore}
 168     @category{FIXME}
 169
 170     @seealso
 171     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();
 181
 182     /**
 183         Is this object valid (@false) or still empty (@true)?
 184     */
 185     bool IsNull();
 186 };
 187
 188
 189 /**
 190     @class wxGraphicsContext
 191     @wxheader{graphics.h}
 192
 193     A wxGraphicsContext instance is the object that is drawn upon. It is created by
 194     a renderer using the CreateContext calls.., this can be either directly using a renderer
 195     instance, or indirectly using the static convenience CreateXXX functions of
 196     wxGraphicsContext that always delegate the task to the default renderer.
 197
 198     @library{wxcore}
 199     @category{FIXME}
 200
 201     @seealso
 202     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);
 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);
 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);
 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);
 277
 278     /**
 279         Creates a native graphics path which is initially empty.
 280     */
 281     wxGraphicsPath CreatePath();
 282
 283     /**
 284         Creates a native pen from a wxPen.
 285     */
 286     wxGraphicsPen CreatePen(const wxPen& pen);
 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);
 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);
 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);
 383
 384     /**
 385         Gets the current transformation matrix of this context.
 386     */
 387     wxGraphicsMatrix GetTransform();
 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     @class wxGraphicsRenderer
 463     @wxheader{graphics.h}
 464
 465     A wxGraphicsRenderer is the instance corresponding to the rendering engine
 466     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.
 467
 468     @library{wxcore}
 469     @category{FIXME}
 470 */
 471 class wxGraphicsRenderer : public wxObject
 472 {
 473 public:
 474     /**
 475         Creates a native brush from a wxBrush.
 476     */
 477     wxGraphicsBrush CreateBrush(const wxBrush& brush);
 478
 479     //@{
 480     /**
 481         Creates a wxGraphicsContext from a wxWindow.
 482     */
 483     wxGraphicsContext* CreateContext(const wxWindowDC& dc);
 484     wxGraphicsContext* CreateContext(wxWindow* window);
 485     //@}
 486
 487     /**
 488         Creates a wxGraphicsContext from a native context. This native context must be
 489         eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a cairo_t pointer for cairo.
 490     */
 491     wxGraphicsContext* CreateContextFromNativeContext(void* context);
 492
 493     /**
 494         Creates a wxGraphicsContext from a native window.
 495     */
 496     wxGraphicsContext* CreateContextFromNativeWindow(void* window);
 497
 498     /**
 499         Creates a native graphics font from a wxFont and a text colour.
 500     */
 501     wxGraphicsFont CreateFont(const wxFont& font,
 502                               const wxColour& col = wxBLACK);
 503
 504     /**
 505         Creates a native brush, having a linear gradient, starting at (x1,y1) with
 506         color c1 to (x2,y2) with color c2
 507     */
 508     wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
 509             wxDouble y1,
 510             wxDouble x2,
 511             wxDouble y2,
 512             const wxColouramp;c1,
 513             const wxColouramp;c2);
 514
 515     /**
 516         Creates a native affine transformation matrix from the passed in values. The
 517         defaults result in an identity matrix.
 518     */
 519     wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 520                                   wxDouble c = 0.0,
 521                                   wxDouble d = 1.0,
 522                                   wxDouble tx = 0.0,
 523                                   wxDouble ty = 0.0);
 524
 525     /**
 526         Creates a native graphics path which is initially empty.
 527     */
 528     wxGraphicsPath CreatePath();
 529
 530     /**
 531         Creates a native pen from a wxPen.
 532     */
 533     wxGraphicsPen CreatePen(const wxPen& pen);
 534
 535     /**
 536         Creates a native brush, having a radial gradient originating at (xo,yc) with
 537         color oColour and ends on a circle around (xc,yc) with radius r and color cColour
 538     */
 539     wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo,
 540             wxDouble yo,
 541             wxDouble xc,
 542             wxDouble yc,
 543             wxDouble radius,
 544             const wxColour& oColour,
 545             const wxColour& cColour);
 546
 547     /**
 548         Returns the default renderer on this platform. On OS X this is the Core
 549         Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and on GTK we currently default to the cairo renderer.
 550     */
 551     wxGraphicsRenderer* GetDefaultRenderer();
 552 };
 553
 554
 555 /**
 556     @class wxGraphicsBrush
 557     @wxheader{graphics.h}
 558
 559
 560     @library{wxcore}
 561     @category{FIXME}
 562 */
 563 class wxGraphicsBrush : public wxGraphicsObject
 564 {
 565 public:
 566
 567 };
 568
 569
 570 /**
 571     @class wxGraphicsFont
 572     @wxheader{graphics.h}
 573
 574
 575     @library{wxcore}
 576     @category{FIXME}
 577 */
 578 class wxGraphicsFont : public wxGraphicsObject
 579 {
 580 public:
 581
 582 };
 583
 584
 585 /**
 586     @class wxGraphicsPen
 587     @wxheader{graphics.h}
 588
 589
 590     @library{wxcore}
 591     @category{FIXME}
 592 */
 593 class wxGraphicsPen : public wxGraphicsObject
 594 {
 595 public:
 596
 597 };
 598
 599
 600 /**
 601     @class wxGraphicsMatrix
 602     @wxheader{graphics.h}
 603
 604     A wxGraphicsMatrix is a native representation of an affine matrix. The contents
 605     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.
 606
 607     @library{wxcore}
 608     @category{FIXME}
 609 */
 610 class wxGraphicsMatrix : public wxGraphicsObject
 611 {
 612 public:
 613     //@{
 614     /**
 615
 616     */
 617     void Concat(const wxGraphicsMatrix* t);
 618     void Concat(const wxGraphicsMatrix& t);
 619     //@}
 620
 621     /**
 622         Returns the component values of the matrix via the argument pointers.
 623     */
 624     void Get(wxDouble* a = NULL, wxDouble* b = NULL, wxDouble* c = NULL,
 625              wxDouble* d = NULL, wxDouble* tx = NULL,
 626              wxDouble* ty = NULL);
 627
 628     /**
 629         Returns the native representation of the matrix. For CoreGraphics this is a
 630         CFAffineMatrix pointer. For GDIPlus a Matrix Pointer and for Cairo a cairo_matrix_t pointer.
 631     */
 632     void* GetNativeMatrix();
 633
 634     /**
 635         Inverts the matrix.
 636     */
 637     void Invert();
 638
 639     /**
 640         Returns @true if the elements of the transformation matrix are equal.
 641     */
 642     bool IsEqual(const wxGraphicsMatrix& t);
 643
 644     /**
 645         Return @true if this is the identity matrix.
 646     */
 647     bool IsIdentity();
 648
 649     /**
 650         Rotates this matrix (radians).
 651     */
 652     void Rotate(wxDouble angle);
 653
 654     /**
 655         Scales this matrix.
 656     */
 657     void Scale(wxDouble xScale, wxDouble yScale);
 658
 659     /**
 660         Sets the matrix to the respective values (default values are the identity
 661         matrix)
 662     */
 663     void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0,
 664              wxDouble d = 1.0, wxDouble tx = 0.0,
 665              wxDouble ty = 0.0);
 666
 667     /**
 668         Applies this matrix to a distance (ie. performs all transforms except
 669         translations)
 670     */
 671     void TransformDistance(wxDouble* dx, wxDouble* dy);
 672
 673     /**
 674         Applies this matrix to a point.
 675     */
 676     void TransformPoint(wxDouble* x, wxDouble* y);
 677
 678     /**
 679         Translates this matrix.
 680     */
 681     void Translate(wxDouble dx, wxDouble dy);
 682 };