interface/wx/graphics.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        graphics.h
   3 // Purpose:     interface of various wxGraphics* classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxGraphicsPath
  11
  12     A wxGraphicsPath is a native representation of a geometric path. The
  13     contents are specific an private to the respective renderer. Instances are
  14     reference counted and can therefore be assigned as usual. The only way to
  15     get a valid instance is by using wxGraphicsContext::CreatePath() or
  16     wxGraphicsRenderer::CreatePath().
  17
  18     @library{wxcore}
  19     @category{gdi}
  20 */
  21 class wxGraphicsPath : public wxGraphicsObject
  22 {
  23 public:
  24     /**
  25         Adds an arc of a circle.
  26
  27         The circle is defined by the coordinates of its centre (@a x, @a y) or
  28         @a c and its radius @a r. The arc goes from the starting angle @a
  29         startAngle to @a endAngle either clockwise or counter-clockwise
  30         depending on the value of @a clockwise argument.
  31
  32         The angles are measured in radians but, contrary to the usual
  33         mathematical convention, are always @e clockwise from the horizontal
  34         axis.
  35     */
  36     //@{
  37     virtual void AddArc(wxDouble x, wxDouble y, wxDouble r,
  38                         wxDouble startAngle, wxDouble endAngle,
  39                         bool clockwise);
  40     void AddArc(const wxPoint2DDouble& c, wxDouble r,
  41                 wxDouble startAngle, wxDouble endAngle, bool clockwise);
  42     //@}
  43
  44     /**
  45         Appends a an arc to two tangents connecting (current) to (@a x1,@a y1)
  46         and (@a x1,@a y1) to (@a x2,@a y2), also a straight line from (current)
  47         to (@a x1,@a y1).
  48     */
  49     virtual void AddArcToPoint(wxDouble x1, wxDouble y1, wxDouble x2,
  50                                wxDouble y2, wxDouble r);
  51
  52     /**
  53         Appends a circle around (@a x,@a y) with radius @a r as a new closed
  54         subpath.
  55     */
  56     virtual void AddCircle(wxDouble x, wxDouble y, wxDouble r);
  57
  58     /**
  59         Adds a cubic bezier curve from the current point, using two control
  60         points and an end point.
  61     */
  62     virtual void AddCurveToPoint(wxDouble cx1, wxDouble cy1,
  63                                  wxDouble cx2, wxDouble cy2,
  64                                  wxDouble x, wxDouble y);
  65     /**
  66         Adds a cubic bezier curve from the current point, using two control
  67         points and an end point.
  68     */
  69     void AddCurveToPoint(const wxPoint2DDouble& c1,
  70                          const wxPoint2DDouble& c2,
  71                          const wxPoint2DDouble& e);
  72
  73     /**
  74         Appends an ellipse fitting into the passed in rectangle.
  75     */
  76     virtual void AddEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
  77
  78     /**
  79         Adds a straight line from the current point to (@a x,@a y).
  80     */
  81     virtual void AddLineToPoint(wxDouble x, wxDouble y);
  82     /**
  83         Adds a straight line from the current point to @a p.
  84     */
  85     void AddLineToPoint(const wxPoint2DDouble& p);
  86
  87     /**
  88         Adds another path.
  89     */
  90     virtual void AddPath(const wxGraphicsPath& path);
  91
  92     /**
  93         Adds a quadratic bezier curve from the current point, using a control
  94         point and an end point.
  95     */
  96     virtual void AddQuadCurveToPoint(wxDouble cx, wxDouble cy,
  97                                      wxDouble x, wxDouble y);
  98
  99     /**
 100         Appends a rectangle as a new closed subpath.
 101     */
 102     virtual void AddRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
 103
 104     /**
 105         Appends a rounded rectangle as a new closed subpath.
 106     */
 107     virtual void AddRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
 108                                      wxDouble h, wxDouble radius);
 109
 110     /**
 111         Closes the current sub-path.
 112     */
 113     virtual void CloseSubpath();
 114
 115     /**
 116         @return @true if the point is within the path.
 117     */
 118     bool Contains(const wxPoint2DDouble& c,
 119                   int fillStyle = wxODDEVEN_RULE) const;
 120     /**
 121         @return @true if the point is within the path.
 122     */
 123     virtual bool Contains(wxDouble x, wxDouble y,
 124                           int fillStyle = wxODDEVEN_RULE) const;
 125
 126     /**
 127         Gets the bounding box enclosing all points (possibly including control
 128         points).
 129     */
 130     wxRect2DDouble GetBox() const;
 131     /**
 132         Gets the bounding box enclosing all points (possibly including control
 133         points).
 134     */
 135     virtual void GetBox(wxDouble* x, wxDouble* y,
 136                         wxDouble* w, wxDouble* h) const;
 137
 138     /**
 139         Gets the last point of the current path, (0,0) if not yet set.
 140     */
 141     virtual void GetCurrentPoint(wxDouble* x, wxDouble* y) const;
 142     /**
 143         Gets the last point of the current path, (0,0) if not yet set.
 144     */
 145     wxPoint2DDouble GetCurrentPoint() const;
 146
 147     /**
 148         Returns the native path (CGPathRef for Core Graphics, Path pointer for
 149         GDIPlus and a cairo_path_t pointer for cairo).
 150     */
 151     virtual void* GetNativePath() const;
 152
 153     /**
 154         Begins a new subpath at (@a x,@a y).
 155     */
 156     virtual void MoveToPoint(wxDouble x, wxDouble y);
 157     /**
 158         Begins a new subpath at @a p.
 159     */
 160     void MoveToPoint(const wxPoint2DDouble& p);
 161
 162     /**
 163         Transforms each point of this path by the matrix.
 164     */
 165     virtual void Transform(const wxGraphicsMatrix& matrix);
 166
 167     /**
 168         Gives back the native path returned by GetNativePath() because there
 169         might be some deallocations necessary (e.g. on cairo the native path
 170         returned by GetNativePath() is newly allocated each time).
 171     */
 172     virtual void UnGetNativePath(void* p) const;
 173 };
 174
 175
 176
 177 /**
 178     @class wxGraphicsObject
 179
 180     This class is the superclass of native graphics objects like pens etc. It
 181     allows reference counting. Not instantiated by user code.
 182
 183     @library{wxcore}
 184     @category{gdi}
 185
 186     @see wxGraphicsBrush, wxGraphicsPen, wxGraphicsMatrix, wxGraphicsPath
 187 */
 188 class wxGraphicsObject : public wxObject
 189 {
 190 public:
 191     /**
 192         Returns the renderer that was used to create this instance, or @NULL
 193         if it has not been initialized yet.
 194     */
 195     wxGraphicsRenderer* GetRenderer() const;
 196
 197     /**
 198         @return @false if this object is valid, otherwise returns @true.
 199     */
 200     bool IsNull() const;
 201 };
 202
 203 /**
 204     Anti-aliasing modes used by wxGraphicsContext::SetAntialiasMode().
 205 */
 206 enum wxAntialiasMode
 207 {
 208     /** No anti-aliasing */
 209     wxANTIALIAS_NONE,
 210
 211     /** The default anti-aliasing */
 212     wxANTIALIAS_DEFAULT,
 213 };
 214
 215 /**
 216     Interpolation quality used by wxGraphicsContext::SetInterpolationQuality().
 217  */
 218 enum wxInterpolationQuality
 219 {
 220     /** default interpolation, based on type of context, in general medium quality */
 221     wxINTERPOLATION_DEFAULT,
 222     /** no interpolation */
 223     wxINTERPOLATION_NONE,
 224     /** fast interpolation, suited for interactivity */
 225     wxINTERPOLATION_FAST,
 226     /** better quality */
 227     wxINTERPOLATION_GOOD,
 228     /** best quality, not suited for interactivity */
 229     wxINTERPOLATION_BEST
 230 };
 231
 232 /**
 233     Compositing is done using Porter-Duff compositions
 234     (see http://keithp.com/~keithp/porterduff/p253-porter.pdf) with
 235     wxGraphicsContext::SetCompositionMode().
 236
 237     The description give a short equation on how the values of a resulting
 238     pixel are calculated.
 239     @e R = Result, @e S = Source, @e D = Destination, colors premultiplied with alpha
 240     @e Ra, @e Sa, @e Da their alpha components
 241 */
 242 enum wxCompositionMode
 243 {
 244     /**
 245         Indicates invalid or unsupported composition mode.
 246
 247         This value can't be passed to wxGraphicsContext::SetCompositionMode().
 248
 249         @since 2.9.2
 250      */
 251     wxCOMPOSITION_INVALID = -1,
 252     wxCOMPOSITION_CLEAR, /**< @e R = 0 */
 253     wxCOMPOSITION_SOURCE, /**< @e R = S */
 254     wxCOMPOSITION_OVER, /**< @e R = @e S + @e D*(1 - @e Sa) */
 255     wxCOMPOSITION_IN, /**< @e R = @e S*@e Da */
 256     wxCOMPOSITION_OUT, /**< @e R = @e S*(1 - @e Da) */
 257     wxCOMPOSITION_ATOP, /**< @e R = @e S*@e Da + @e D*(1 - @e Sa) */
 258
 259     wxCOMPOSITION_DEST, /**< @e R = @e D, essentially a noop */
 260     wxCOMPOSITION_DEST_OVER, /**< @e R = @e S*(1 - @e Da) + @e D */
 261     wxCOMPOSITION_DEST_IN, /**< @e R = @e D*@e Sa */
 262     wxCOMPOSITION_DEST_OUT, /**< @e R = @e D*(1 - @e Sa) */
 263     wxCOMPOSITION_DEST_ATOP, /**< @e R = @e S*(1 - @e Da) + @e D*@e Sa */
 264     wxCOMPOSITION_XOR, /**< @e R = @e S*(1 - @e Da) + @e D*(1 - @e Sa) */
 265     wxCOMPOSITION_ADD  /**< @e R = @e S + @e D */
 266 };
 267
 268
 269 /**
 270     @class wxGraphicsContext
 271
 272     A wxGraphicsContext instance is the object that is drawn upon. It is
 273     created by a renderer using wxGraphicsRenderer::CreateContext(). This can
 274     be either directly using a renderer instance, or indirectly using the
 275     static convenience Create() functions of wxGraphicsContext that always
 276     delegate the task to the default renderer.
 277
 278     @code
 279     void MyCanvas::OnPaint(wxPaintEvent &event)
 280     {
 281         // Create paint DC
 282         wxPaintDC dc(this);
 283
 284         // Create graphics context from it
 285         wxGraphicsContext *gc = wxGraphicsContext::Create( dc );
 286
 287         if (gc)
 288         {
 289             // make a path that contains a circle and some lines
 290             gc->SetPen( *wxRED_PEN );
 291             wxGraphicsPath path = gc->CreatePath();
 292             path.AddCircle( 50.0, 50.0, 50.0 );
 293             path.MoveToPoint(0.0, 50.0);
 294             path.AddLineToPoint(100.0, 50.0);
 295             path.MoveToPoint(50.0, 0.0);
 296             path.AddLineToPoint(50.0, 100.0 );
 297             path.CloseSubpath();
 298             path.AddRectangle(25.0, 25.0, 50.0, 50.0);
 299
 300             gc->StrokePath(path);
 301
 302             delete gc;
 303         }
 304     }
 305     @endcode
 306
 307     @library{wxcore}
 308     @category{gdi,dc}
 309
 310     @see wxGraphicsRenderer::CreateContext(), wxGCDC, wxDC
 311 */
 312 class wxGraphicsContext : public wxGraphicsObject
 313 {
 314 public:
 315     /**
 316         Creates a wxGraphicsContext from a wxWindow.
 317
 318         @see wxGraphicsRenderer::CreateContext()
 319     */
 320     static wxGraphicsContext* Create(wxWindow* window);
 321
 322     /**
 323         Creates a wxGraphicsContext from a wxWindowDC
 324
 325         @see wxGraphicsRenderer::CreateContext()
 326     */
 327     static wxGraphicsContext* Create(const wxWindowDC& dc);
 328
 329     /**
 330         Creates a wxGraphicsContext from a wxMemoryDC
 331
 332         @see wxGraphicsRenderer::CreateContext()
 333     */
 334     static wxGraphicsContext* Create(const wxMemoryDC& dc);
 335
 336     /**
 337         Creates a wxGraphicsContext from a wxPrinterDC. Under GTK+, this will
 338         only work when using the GtkPrint printing backend which is available
 339         since GTK+ 2.10.
 340
 341         @see wxGraphicsRenderer::CreateContext(), @ref overview_unixprinting
 342     */
 343     static wxGraphicsContext* Create(const wxPrinterDC& dc);
 344
 345     /**
 346         Creates a wxGraphicsContext from a wxEnhMetaFileDC.
 347
 348         This function, as wxEnhMetaFileDC class itself, is only available only
 349         under MSW.
 350
 351         @see wxGraphicsRenderer::CreateContext()
 352     */
 353     static wxGraphicsContext* Create(const wxEnhMetaFileDC& dc);
 354
 355     /**
 356         Clips drawings to the specified region.
 357     */
 358     virtual void Clip(const wxRegion& region) = 0;
 359
 360     /**
 361         Clips drawings to the specified rectangle.
 362     */
 363     virtual void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h) = 0;
 364
 365     /**
 366         Concatenates the passed in transform with the current transform of this
 367         context.
 368     */
 369     virtual void ConcatTransform(const wxGraphicsMatrix& matrix) = 0;
 370
 371     /**
 372         Creates a native brush from a wxBrush.
 373     */
 374     virtual wxGraphicsBrush CreateBrush(const wxBrush& brush) const;
 375
 376     /**
 377         Creates a native graphics font from a wxFont and a text colour.
 378     */
 379     virtual wxGraphicsFont CreateFont(const wxFont& font,
 380                                       const wxColour& col = *wxBLACK) const;
 381
 382     /**
 383         Creates a wxGraphicsContext from a native context. This native context
 384         must be a CGContextRef for Core Graphics, a Graphics pointer for
 385         GDIPlus, or a cairo_t pointer for cairo.
 386
 387         @see wxGraphicsRenderer::CreateContextFromNativeContext()
 388     */
 389     static wxGraphicsContext* CreateFromNative(void* context);
 390
 391     /**
 392         Creates a wxGraphicsContext from a native window.
 393
 394         @see wxGraphicsRenderer::CreateContextFromNativeWindow()
 395     */
 396     static wxGraphicsContext* CreateFromNativeWindow(void* window);
 397
 398     /**
 399         Creates a native brush with a linear gradient.
 400
 401         The brush starts at (@a x1, @a y1) and ends at (@a x2, @a y2). Either
 402         just the start and end gradient colours (@a c1 and @a c2) or full set
 403         of gradient @a stops can be specified.
 404
 405         The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1.
 406     */
 407     //@{
 408     wxGraphicsBrush
 409     CreateLinearGradientBrush(wxDouble x1, wxDouble y1,
 410                               wxDouble x2, wxDouble y2,
 411                               const wxColour& c1, const wxColour& c2) const;
 412
 413     wxGraphicsBrush
 414     CreateLinearGradientBrush(wxDouble x1, wxDouble y1,
 415                               wxDouble x2, wxDouble y2,
 416                               const wxGraphicsGradientStops& stops) const;
 417     //@}
 418
 419     /**
 420         Creates a native affine transformation matrix from the passed in
 421         values. The default parameters result in an identity matrix.
 422     */
 423     virtual wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 424                                           wxDouble c = 0.0, wxDouble d = 1.0,
 425                                           wxDouble tx = 0.0,
 426                                           wxDouble ty = 0.0) const;
 427
 428     /**
 429         Creates a native graphics path which is initially empty.
 430     */
 431     wxGraphicsPath CreatePath() const;
 432
 433     /**
 434         Creates a native pen from a wxPen.
 435     */
 436     virtual wxGraphicsPen CreatePen(const wxPen& pen) const;
 437
 438     /**
 439         Creates a native brush with a radial gradient.
 440
 441         The brush originates at (@a xo, @a yc) and ends on a circle around
 442         (@a xc, @a yc) with the given @a radius.
 443
 444         The gradient may be specified either by its start and end colours @a
 445         oColor and @a cColor or by a full set of gradient @a stops.
 446
 447         The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1.
 448     */
 449     //@{
 450     virtual wxGraphicsBrush
 451     CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
 452                               wxDouble xc, wxDouble yc,
 453                               wxDouble radius,
 454                               const wxColour& oColor,
 455                               const wxColour& cColor) const;
 456
 457     virtual wxGraphicsBrush
 458     CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
 459                               wxDouble xc, wxDouble yc,
 460                               wxDouble radius,
 461                               const wxGraphicsGradientStops& stops) = 0;
 462     //@}
 463
 464     /**
 465         Draws the bitmap. In case of a mono bitmap, this is treated as a mask
 466         and the current brushed is used for filling.
 467     */
 468     virtual void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y,
 469                             wxDouble w, wxDouble h) = 0;
 470
 471     /**
 472         Draws an ellipse.
 473     */
 474     virtual void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
 475
 476     /**
 477         Draws the icon.
 478     */
 479     virtual void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y,
 480                           wxDouble w, wxDouble h) = 0;
 481
 482     /**
 483         Draws a polygon.
 484     */
 485     virtual void DrawLines(size_t n, const wxPoint2DDouble* points,
 486                            wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
 487
 488     /**
 489         Draws the path by first filling and then stroking.
 490     */
 491     virtual void DrawPath(const wxGraphicsPath& path,
 492                           wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
 493
 494     /**
 495         Draws a rectangle.
 496     */
 497     virtual void DrawRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
 498
 499     /**
 500         Draws a rounded rectangle.
 501     */
 502     virtual void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
 503                                       wxDouble h, wxDouble radius);
 504
 505     /**
 506         Draws text at the defined position.
 507     */
 508     void DrawText(const wxString& str, wxDouble x, wxDouble y);
 509     /**
 510         Draws text at the defined position.
 511
 512         @param str
 513             The text to draw.
 514         @param x
 515             The x coordinate position to draw the text at.
 516         @param y
 517             The y coordinate position to draw the text at.
 518         @param angle
 519             The angle relative to the (default) horizontal direction to draw
 520             the string.
 521     */
 522     void DrawText(const wxString& str, wxDouble x, wxDouble y, wxDouble angle);
 523     /**
 524         Draws text at the defined position.
 525
 526         @param str
 527             The text to draw.
 528         @param x
 529             The x coordinate position to draw the text at.
 530         @param y
 531             The y coordinate position to draw the text at.
 532         @param backgroundBrush
 533             Brush to fill the text with.
 534     */
 535     void DrawText(const wxString& str, wxDouble x, wxDouble y,
 536                   const wxGraphicsBrush& backgroundBrush);
 537     /**
 538         Draws text at the defined position.
 539
 540         @param str
 541             The text to draw.
 542         @param x
 543             The x coordinate position to draw the text at.
 544         @param y
 545             The y coordinate position to draw the text at.
 546         @param angle
 547             The angle relative to the (default) horizontal direction to draw
 548             the string.
 549         @param backgroundBrush
 550             Brush to fill the text with.
 551     */
 552     void DrawText(const wxString& str, wxDouble x, wxDouble y,
 553                   wxDouble angle, const wxGraphicsBrush& backgroundBrush);
 554
 555     /**
 556         Fills the path with the current brush.
 557     */
 558     virtual void FillPath(const wxGraphicsPath& path,
 559                           wxPolygonFillMode fillStyle = wxODDEVEN_RULE) = 0;
 560
 561     /**
 562         Returns the native context (CGContextRef for Core Graphics, Graphics
 563         pointer for GDIPlus and cairo_t pointer for cairo).
 564     */
 565     virtual void* GetNativeContext() = 0;
 566
 567     /**
 568         Fills the @a widths array with the widths from the beginning of
 569         @a text to the corresponding character of @a text.
 570     */
 571     virtual void GetPartialTextExtents(const wxString& text,
 572                                        wxArrayDouble& widths) const = 0;
 573
 574     /**
 575         Gets the dimensions of the string using the currently selected font.
 576
 577         @param text
 578             The text string to measure.
 579         @param width
 580             Variable to store the total calculated width of the text.
 581         @param height
 582             Variable to store the total calculated height of the text.
 583         @param descent
 584             Variable to store the dimension from the baseline of the font to
 585             the bottom of the descender.
 586         @param externalLeading
 587             Any extra vertical space added to the font by the font designer
 588             (usually is zero).
 589     */
 590     virtual void GetTextExtent(const wxString& text, wxDouble* width,
 591                                wxDouble* height, wxDouble* descent,
 592                                wxDouble* externalLeading) const = 0;
 593
 594     /**
 595         Gets the current transformation matrix of this context.
 596     */
 597     virtual wxGraphicsMatrix GetTransform() const = 0;
 598
 599     /**
 600         Resets the clipping to original shape.
 601     */
 602     virtual void ResetClip() = 0;
 603
 604     /**
 605         Rotates the current transformation matrix (in radians).
 606     */
 607     virtual void Rotate(wxDouble angle) = 0;
 608
 609     /**
 610         Scales the current transformation matrix.
 611     */
 612     virtual void Scale(wxDouble xScale, wxDouble yScale) = 0;
 613
 614     /**
 615         Sets the brush for filling paths.
 616     */
 617     void SetBrush(const wxBrush& brush);
 618     /**
 619         Sets the brush for filling paths.
 620     */
 621     virtual void SetBrush(const wxGraphicsBrush& brush);
 622
 623     /**
 624         Sets the font for drawing text.
 625     */
 626     void SetFont(const wxFont& font, const wxColour& colour);
 627     /**
 628         Sets the font for drawing text.
 629     */
 630     virtual void SetFont(const wxGraphicsFont& font);
 631
 632     /**
 633         Sets the pen used for stroking.
 634     */
 635     void SetPen(const wxPen& pen);
 636     /**
 637         Sets the pen used for stroking.
 638     */
 639     virtual void SetPen(const wxGraphicsPen& pen);
 640
 641     /**
 642         Sets the current transformation matrix of this context
 643     */
 644     virtual void SetTransform(const wxGraphicsMatrix& matrix) = 0;
 645
 646     /**
 647         Strokes a single line.
 648     */
 649     virtual void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2, wxDouble y2);
 650
 651     /**
 652         Stroke disconnected lines from begin to end points, fastest method
 653         available for this purpose.
 654     */
 655     virtual void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints,
 656                              const wxPoint2DDouble* endPoints);
 657     /**
 658         Stroke lines connecting all the points.
 659
 660         Unlike the other overload of this function, this method draws a single
 661         polyline and not a number of disconnected lines.
 662     */
 663     virtual void StrokeLines(size_t n, const wxPoint2DDouble* points);
 664
 665     /**
 666         Strokes along a path with the current pen.
 667     */
 668     virtual void StrokePath(const wxGraphicsPath& path) = 0;
 669
 670     /**
 671         Translates the current transformation matrix.
 672     */
 673     virtual void Translate(wxDouble dx, wxDouble dy) = 0;
 674
 675     /**
 676         Redirects all rendering is done into a fully transparent temporary context
 677     */
 678     virtual void BeginLayer(wxDouble opacity) = 0;
 679
 680     /**
 681         Composites back the drawings into the context with the opacity given at
 682         the BeginLayer call
 683     */
 684     virtual void EndLayer() = 0;
 685
 686     /**
 687         Sets the antialiasing mode, returns true if it supported
 688     */
 689     virtual bool SetAntialiasMode(wxAntialiasMode antialias) = 0;
 690
 691     /**
 692         Returns the current shape antialiasing mode
 693     */
 694     virtual wxAntialiasMode GetAntialiasMode() const ;
 695
 696     /**
 697         Sets the interpolation quality, returns true if it supported
 698      */
 699     virtual bool SetInterpolationQuality(wxInterpolationQuality interpolation) = 0;
 700
 701     /**
 702         Returns the current interpolation quality
 703      */
 704     virtual wxInterpolationQuality GetInterpolationQuality() const;
 705
 706     /**
 707         Sets the compositing operator, returns true if it supported
 708     */
 709     virtual bool SetCompositionMode(wxCompositionMode op) = 0;
 710
 711     /**
 712         Returns the current compositing operator
 713     */
 714     virtual wxCompositionMode GetCompositionMode() const;
 715
 716 };
 717
 718 /**
 719     Represents a single gradient stop in a collection of gradient stops as
 720     represented by wxGraphicsGradientStops.
 721
 722     @library{wxcore}
 723     @category{gdi}
 724
 725     @since 2.9.1
 726 */
 727 class wxGraphicsGradientStop
 728 {
 729 public:
 730     /**
 731         Creates a stop with the given colour and position.
 732
 733         @param col The colour of this stop. Note that the alpha component of
 734             the colour is honoured thus allowing the background colours to
 735             partially show through the gradient.
 736         @param pos The stop position, must be in [0, 1] range with 0 being the
 737             beginning and 1 the end of the gradient.
 738     */
 739     wxGraphicsGradientStop(wxColour col = wxTransparentColour, float pos = 0.);
 740
 741     /// Return the stop colour.
 742     const wxColour& GetColour() const;
 743
 744     /**
 745         Change the stop colour.
 746
 747         @param col The new colour.
 748     */
 749     void SetColour(const wxColour& col);
 750
 751     /// Return the stop position.
 752     float GetPosition() const;
 753
 754     /**
 755         Change the stop position.
 756
 757         @param pos The new position, must always be in [0, 1] range.
 758     */
 759     void SetPosition(float pos);
 760 };
 761
 762 /**
 763     Represents a collection of wxGraphicGradientStop values for use with
 764     CreateLinearGradientBrush and CreateRadialGradientBrush.
 765
 766     The stops are maintained in order of position.  If two or more stops are
 767     added with the same position then the one(s) added later come later.
 768     This can be useful for producing discontinuities in the colour gradient.
 769
 770     Notice that this class is write-once, you can't modify the stops once they
 771     had been added.
 772
 773     @library{wxcore}
 774     @category{gdi}
 775
 776     @since 2.9.1
 777 */
 778 class wxGraphicsGradientStops
 779 {
 780 public:
 781     /**
 782         Initializes the gradient stops with the given boundary colours.
 783
 784         Creates a wxGraphicsGradientStops instance with start colour given
 785         by @a startCol and end colour given by @a endCol.
 786     */
 787     wxGraphicsGradientStops(wxColour startCol = wxTransparentColour,
 788                             wxColour endCol = wxTransparentColour);
 789
 790     /**
 791         Add a new stop.
 792     */
 793     //@{
 794     void Add(const wxGraphicsGradientStop& stop);
 795     void Add(wxColour col, float pos);
 796     //@}
 797
 798     /**
 799         Returns the stop at the given index.
 800
 801         @param n The index, must be in [0, GetCount()) range.
 802     */
 803     wxGraphicsGradientStop Item(unsigned n) const;
 804
 805     /**
 806         Returns the number of stops.
 807     */
 808     unsigned GetCount() const;
 809
 810     /**
 811         Set the start colour to @a col
 812     */
 813     void SetStartColour(wxColour col);
 814
 815     /**
 816         Returns the start colour.
 817     */
 818     wxColour GetStartColour() const;
 819
 820     /**
 821         Set the end colour to @a col
 822     */
 823     void SetEndColour(wxColour col);
 824
 825     /**
 826         Returns the end colour.
 827     */
 828     wxColour GetEndColour() const;
 829 };
 830
 831 /**
 832     @class wxGraphicsRenderer
 833
 834     A wxGraphicsRenderer is the instance corresponding to the rendering engine
 835     used. There may be multiple instances on a system, if there are different
 836     rendering engines present, but there is always only one instance per
 837     engine. This instance is pointed back to by all objects created by it
 838     (wxGraphicsContext, wxGraphicsPath etc) and can be retrieved through their
 839     wxGraphicsObject::GetRenderer() method. Therefore you can create an
 840     additional instance of a path etc. by calling
 841     wxGraphicsObject::GetRenderer() and then using the appropriate CreateXXX()
 842     function of that renderer.
 843
 844     @code
 845     wxGraphicsPath *path = // from somewhere
 846     wxGraphicsBrush *brush = path->GetRenderer()->CreateBrush( *wxBLACK_BRUSH );
 847     @endcode
 848
 849     @library{wxcore}
 850     @category{gdi}
 851 */
 852 class wxGraphicsRenderer : public wxObject
 853 {
 854 public:
 855     /**
 856         Creates a wxGraphicsContext from a wxWindow.
 857     */
 858     virtual wxGraphicsContext* CreateContext(wxWindow* window) = 0;
 859
 860     /**
 861         Creates a wxGraphicsContext from a wxWindowDC
 862     */
 863     virtual wxGraphicsContext* CreateContext(const wxWindowDC& dc) = 0 ;
 864
 865     /**
 866         Creates a wxGraphicsContext from a wxMemoryDC
 867     */
 868     virtual wxGraphicsContext* CreateContext(const wxMemoryDC& dc) = 0 ;
 869
 870     /**
 871         Creates a wxGraphicsContext from a wxPrinterDC
 872     */
 873     virtual wxGraphicsContext* CreateContext(const wxPrinterDC& dc) = 0 ;
 874
 875     /**
 876         Creates a wxGraphicsContext from a wxEnhMetaFileDC.
 877
 878         This function, as wxEnhMetaFileDC class itself, is only available only
 879         under MSW.
 880     */
 881     virtual wxGraphicsContext* CreateContext(const wxEnhMetaFileDC& dc) = 0;
 882
 883     /**
 884         Creates a native brush from a wxBrush.
 885     */
 886     virtual wxGraphicsBrush CreateBrush(const wxBrush& brush) = 0;
 887
 888     /**
 889         Creates a wxGraphicsContext from a native context. This native context
 890         must be a CGContextRef for Core Graphics, a Graphics pointer for
 891         GDIPlus, or a cairo_t pointer for cairo.
 892     */
 893     virtual wxGraphicsContext* CreateContextFromNativeContext(void* context) = 0;
 894
 895     /**
 896         Creates a wxGraphicsContext from a native window.
 897     */
 898     virtual wxGraphicsContext* CreateContextFromNativeWindow(void* window) = 0;
 899
 900     /**
 901         Creates a wxGraphicsContext that can be used for measuring texts only.
 902         No drawing commands are allowed.
 903     */
 904     virtual wxGraphicsContext * CreateMeasuringContext() = 0;
 905
 906     /**
 907         Creates a native graphics font from a wxFont and a text colour.
 908     */
 909     virtual wxGraphicsFont CreateFont(const wxFont& font,
 910                                       const wxColour& col = *wxBLACK) = 0;
 911
 912
 913     /**
 914         Creates a native brush with a linear gradient.
 915
 916         Stops support is new since wxWidgets 2.9.1, previously only the start
 917         and end colours could be specified.
 918     */
 919     virtual wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
 920                                                       wxDouble y1,
 921                                                       wxDouble x2,
 922                                                       wxDouble y2,
 923                                                       const wxGraphicsGradientStops& stops) = 0;
 924
 925     /**
 926         Creates a native affine transformation matrix from the passed in
 927         values. The defaults result in an identity matrix.
 928     */
 929     virtual wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 930                                           wxDouble c = 0.0, wxDouble d = 1.0,
 931                                           wxDouble tx = 0.0,
 932                                           wxDouble ty = 0.0) = 0;
 933
 934     /**
 935         Creates a native graphics path which is initially empty.
 936     */
 937     virtual wxGraphicsPath CreatePath() = 0;
 938
 939     /**
 940         Creates a native pen from a wxPen.
 941     */
 942     virtual wxGraphicsPen CreatePen(const wxPen& pen) = 0;
 943
 944     /**
 945         Creates a native brush with a radial gradient.
 946
 947         Stops support is new since wxWidgets 2.9.1, previously only the start
 948         and end colours could be specified.
 949     */
 950     virtual wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
 951                                                       wxDouble xc, wxDouble yc,
 952                                                       wxDouble radius,
 953                                                       const wxGraphicsGradientStops& stops) = 0;
 954
 955     /**
 956         Returns the default renderer on this platform. On OS X this is the Core
 957         Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and
 958         on GTK we currently default to the cairo renderer.
 959     */
 960     static wxGraphicsRenderer* GetDefaultRenderer();
 961 };
 962
 963
 964
 965 /**
 966     @class wxGraphicsBrush
 967
 968     A wxGraphicsBrush is a native representation of a brush. The contents are
 969     specific and private to the respective renderer. Instances are ref counted
 970     and can therefore be assigned as usual. The only way to get a valid
 971     instance is via wxGraphicsContext::CreateBrush() or
 972     wxGraphicsRenderer::CreateBrush().
 973
 974     @library{wxcore}
 975     @category{gdi}
 976 */
 977 class wxGraphicsBrush : public wxGraphicsObject
 978 {
 979 public:
 980
 981 };
 982
 983
 984
 985 /**
 986     @class wxGraphicsFont
 987
 988     A wxGraphicsFont is a native representation of a font. The contents are
 989     specific and private to the respective renderer. Instances are ref counted
 990     and can therefore be assigned as usual. The only way to get a valid
 991     instance is via wxGraphicsContext::CreateFont() or
 992     wxGraphicsRenderer::CreateFont().
 993
 994     @library{wxcore}
 995     @category{gdi}
 996 */
 997 class wxGraphicsFont : public wxGraphicsObject
 998 {
 999 public:
1000
1001 };
1002
1003
1004
1005 /**
1006     @class wxGraphicsPen
1007
1008     A wxGraphicsPen is a native representation of a pen. The contents are
1009     specific and private to the respective renderer. Instances are ref counted
1010     and can therefore be assigned as usual. The only way to get a valid
1011     instance is via wxGraphicsContext::CreatePen() or
1012     wxGraphicsRenderer::CreatePen().
1013
1014     @library{wxcore}
1015     @category{gdi}
1016 */
1017 class wxGraphicsPen : public wxGraphicsObject
1018 {
1019 public:
1020
1021 };
1022
1023
1024
1025 /**
1026     @class wxGraphicsMatrix
1027
1028     A wxGraphicsMatrix is a native representation of an affine matrix. The
1029     contents are specific and private to the respective renderer. Instances are
1030     ref counted and can therefore be assigned as usual. The only way to get a
1031     valid instance is via wxGraphicsContext::CreateMatrix() or
1032     wxGraphicsRenderer::CreateMatrix().
1033
1034     @library{wxcore}
1035     @category{gdi}
1036 */
1037 class wxGraphicsMatrix : public wxGraphicsObject
1038 {
1039 public:
1040     /**
1041         Concatenates the matrix passed with the current matrix.
1042     */
1043     virtual void Concat(const wxGraphicsMatrix* t);
1044     /**
1045         Concatenates the matrix passed with the current matrix.
1046     */
1047     void Concat(const wxGraphicsMatrix& t);
1048
1049     /**
1050         Returns the component values of the matrix via the argument pointers.
1051     */
1052     virtual void Get(wxDouble* a = NULL, wxDouble* b = NULL,
1053                      wxDouble* c = NULL, wxDouble* d = NULL,
1054                      wxDouble* tx = NULL, wxDouble* ty = NULL) const;
1055
1056     /**
1057         Returns the native representation of the matrix. For CoreGraphics this
1058         is a CFAffineMatrix pointer, for GDIPlus a Matrix Pointer, and for
1059         Cairo a cairo_matrix_t pointer.
1060     */
1061     virtual void* GetNativeMatrix() const;
1062
1063     /**
1064         Inverts the matrix.
1065     */
1066     virtual void Invert();
1067
1068     /**
1069         Returns @true if the elements of the transformation matrix are equal.
1070     */
1071     virtual bool IsEqual(const wxGraphicsMatrix* t) const;
1072     /**
1073         Returns @true if the elements of the transformation matrix are equal.
1074     */
1075     bool IsEqual(const wxGraphicsMatrix& t) const;
1076
1077     /**
1078         Return @true if this is the identity matrix.
1079     */
1080     virtual bool IsIdentity() const;
1081
1082     /**
1083         Rotates this matrix (in radians).
1084     */
1085     virtual void Rotate(wxDouble angle);
1086
1087     /**
1088         Scales this matrix.
1089     */
1090     virtual void Scale(wxDouble xScale, wxDouble yScale);
1091
1092     /**
1093         Sets the matrix to the respective values (default values are the
1094         identity matrix).
1095     */
1096     virtual void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0,
1097                      wxDouble d = 1.0, wxDouble tx = 0.0, wxDouble ty = 0.0);
1098
1099     /**
1100         Applies this matrix to a distance (ie. performs all transforms except
1101         translations).
1102     */
1103     virtual void TransformDistance(wxDouble* dx, wxDouble* dy) const;
1104
1105     /**
1106         Applies this matrix to a point.
1107     */
1108     virtual void TransformPoint(wxDouble* x, wxDouble* y) const;
1109
1110     /**
1111         Translates this matrix.
1112     */
1113     virtual void Translate(wxDouble dx, wxDouble dy);
1114 };
1115