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         Clips drawings to the specified region.
 347     */
 348     virtual void Clip(const wxRegion& region) = 0;
 349
 350     /**
 351         Clips drawings to the specified rectangle.
 352     */
 353     virtual void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h) = 0;
 354
 355     /**
 356         Concatenates the passed in transform with the current transform of this
 357         context.
 358     */
 359     virtual void ConcatTransform(const wxGraphicsMatrix& matrix) = 0;
 360
 361     /**
 362         Creates a native brush from a wxBrush.
 363     */
 364     virtual wxGraphicsBrush CreateBrush(const wxBrush& brush) const;
 365
 366     /**
 367         Creates a native graphics font from a wxFont and a text colour.
 368     */
 369     virtual wxGraphicsFont CreateFont(const wxFont& font,
 370                                       const wxColour& col = *wxBLACK) const;
 371
 372     /**
 373         Creates a wxGraphicsContext from a native context. This native context
 374         must be a CGContextRef for Core Graphics, a Graphics pointer for
 375         GDIPlus, or a cairo_t pointer for cairo.
 376
 377         @see wxGraphicsRenderer::CreateContextFromNativeContext()
 378     */
 379     static wxGraphicsContext* CreateFromNative(void* context);
 380
 381     /**
 382         Creates a wxGraphicsContext from a native window.
 383
 384         @see wxGraphicsRenderer::CreateContextFromNativeWindow()
 385     */
 386     static wxGraphicsContext* CreateFromNativeWindow(void* window);
 387
 388     /**
 389         Creates a native brush with a linear gradient.
 390
 391         The brush starts at (@a x1, @a y1) and ends at (@a x2, @a y2). Either
 392         just the start and end gradient colours (@a c1 and @a c2) or full set
 393         of gradient @a stops can be specified.
 394
 395         The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1.
 396     */
 397     //@{
 398     wxGraphicsBrush
 399     CreateLinearGradientBrush(wxDouble x1, wxDouble y1,
 400                               wxDouble x2, wxDouble y2,
 401                               const wxColour& c1, const wxColour& c2) const;
 402
 403     wxGraphicsBrush
 404     CreateLinearGradientBrush(wxDouble x1, wxDouble y1,
 405                               wxDouble x2, wxDouble y2,
 406                               const wxGraphicsGradientStops& stops) const;
 407     //@}
 408
 409     /**
 410         Creates a native affine transformation matrix from the passed in
 411         values. The default parameters result in an identity matrix.
 412     */
 413     virtual wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 414                                           wxDouble c = 0.0, wxDouble d = 1.0,
 415                                           wxDouble tx = 0.0,
 416                                           wxDouble ty = 0.0) const;
 417
 418     /**
 419         Creates a native graphics path which is initially empty.
 420     */
 421     wxGraphicsPath CreatePath() const;
 422
 423     /**
 424         Creates a native pen from a wxPen.
 425     */
 426     virtual wxGraphicsPen CreatePen(const wxPen& pen) const;
 427
 428     /**
 429         Creates a native brush with a radial gradient.
 430
 431         The brush originates at (@a xo, @a yc) and ends on a circle around
 432         (@a xc, @a yc) with the given @a radius.
 433
 434         The gradient may be specified either by its start and end colours @a
 435         oColor and @a cColor or by a full set of gradient @a stops.
 436
 437         The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1.
 438     */
 439     //@{
 440     virtual wxGraphicsBrush
 441     CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
 442                               wxDouble xc, wxDouble yc,
 443                               wxDouble radius,
 444                               const wxColour& oColor,
 445                               const wxColour& cColor) const;
 446
 447     virtual wxGraphicsBrush
 448     CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
 449                               wxDouble xc, wxDouble yc,
 450                               wxDouble radius,
 451                               const wxGraphicsGradientStops& stops) = 0;
 452     //@}
 453
 454     /**
 455         Draws the bitmap. In case of a mono bitmap, this is treated as a mask
 456         and the current brushed is used for filling.
 457     */
 458     virtual void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y,
 459                             wxDouble w, wxDouble h) = 0;
 460
 461     /**
 462         Draws an ellipse.
 463     */
 464     virtual void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
 465
 466     /**
 467         Draws the icon.
 468     */
 469     virtual void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y,
 470                           wxDouble w, wxDouble h) = 0;
 471
 472     /**
 473         Draws a polygon.
 474     */
 475     virtual void DrawLines(size_t n, const wxPoint2DDouble* points,
 476                            wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
 477
 478     /**
 479         Draws the path by first filling and then stroking.
 480     */
 481     virtual void DrawPath(const wxGraphicsPath& path,
 482                           wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
 483
 484     /**
 485         Draws a rectangle.
 486     */
 487     virtual void DrawRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
 488
 489     /**
 490         Draws a rounded rectangle.
 491     */
 492     virtual void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
 493                                       wxDouble h, wxDouble radius);
 494
 495     /**
 496         Draws text at the defined position.
 497     */
 498     void DrawText(const wxString& str, wxDouble x, wxDouble y);
 499     /**
 500         Draws text at the defined position.
 501
 502         @param str
 503             The text to draw.
 504         @param x
 505             The x coordinate position to draw the text at.
 506         @param y
 507             The y coordinate position to draw the text at.
 508         @param angle
 509             The angle relative to the (default) horizontal direction to draw
 510             the string.
 511     */
 512     void DrawText(const wxString& str, wxDouble x, wxDouble y, wxDouble angle);
 513     /**
 514         Draws text at the defined position.
 515
 516         @param str
 517             The text to draw.
 518         @param x
 519             The x coordinate position to draw the text at.
 520         @param y
 521             The y coordinate position to draw the text at.
 522         @param backgroundBrush
 523             Brush to fill the text with.
 524     */
 525     void DrawText(const wxString& str, wxDouble x, wxDouble y,
 526                   const wxGraphicsBrush& backgroundBrush);
 527     /**
 528         Draws text at the defined position.
 529
 530         @param str
 531             The text to draw.
 532         @param x
 533             The x coordinate position to draw the text at.
 534         @param y
 535             The y coordinate position to draw the text at.
 536         @param angle
 537             The angle relative to the (default) horizontal direction to draw
 538             the string.
 539         @param backgroundBrush
 540             Brush to fill the text with.
 541     */
 542     void DrawText(const wxString& str, wxDouble x, wxDouble y,
 543                   wxDouble angle, const wxGraphicsBrush& backgroundBrush);
 544
 545     /**
 546         Fills the path with the current brush.
 547     */
 548     virtual void FillPath(const wxGraphicsPath& path,
 549                           wxPolygonFillMode fillStyle = wxODDEVEN_RULE) = 0;
 550
 551     /**
 552         Returns the native context (CGContextRef for Core Graphics, Graphics
 553         pointer for GDIPlus and cairo_t pointer for cairo).
 554     */
 555     virtual void* GetNativeContext() = 0;
 556
 557     /**
 558         Fills the @a widths array with the widths from the beginning of
 559         @a text to the corresponding character of @a text.
 560     */
 561     virtual void GetPartialTextExtents(const wxString& text,
 562                                        wxArrayDouble& widths) const = 0;
 563
 564     /**
 565         Gets the dimensions of the string using the currently selected font.
 566
 567         @param text
 568             The text string to measure.
 569         @param width
 570             Variable to store the total calculated width of the text.
 571         @param height
 572             Variable to store the total calculated height of the text.
 573         @param descent
 574             Variable to store the dimension from the baseline of the font to
 575             the bottom of the descender.
 576         @param externalLeading
 577             Any extra vertical space added to the font by the font designer
 578             (usually is zero).
 579     */
 580     virtual void GetTextExtent(const wxString& text, wxDouble* width,
 581                                wxDouble* height, wxDouble* descent,
 582                                wxDouble* externalLeading) const = 0;
 583
 584     /**
 585         Gets the current transformation matrix of this context.
 586     */
 587     virtual wxGraphicsMatrix GetTransform() const = 0;
 588
 589     /**
 590         Resets the clipping to original shape.
 591     */
 592     virtual void ResetClip() = 0;
 593
 594     /**
 595         Rotates the current transformation matrix (in radians).
 596     */
 597     virtual void Rotate(wxDouble angle) = 0;
 598
 599     /**
 600         Scales the current transformation matrix.
 601     */
 602     virtual void Scale(wxDouble xScale, wxDouble yScale) = 0;
 603
 604     /**
 605         Sets the brush for filling paths.
 606     */
 607     void SetBrush(const wxBrush& brush);
 608     /**
 609         Sets the brush for filling paths.
 610     */
 611     virtual void SetBrush(const wxGraphicsBrush& brush);
 612
 613     /**
 614         Sets the font for drawing text.
 615     */
 616     void SetFont(const wxFont& font, const wxColour& colour);
 617     /**
 618         Sets the font for drawing text.
 619     */
 620     virtual void SetFont(const wxGraphicsFont& font);
 621
 622     /**
 623         Sets the pen used for stroking.
 624     */
 625     void SetPen(const wxPen& pen);
 626     /**
 627         Sets the pen used for stroking.
 628     */
 629     virtual void SetPen(const wxGraphicsPen& pen);
 630
 631     /**
 632         Sets the current transformation matrix of this context
 633     */
 634     virtual void SetTransform(const wxGraphicsMatrix& matrix) = 0;
 635
 636     /**
 637         Strokes a single line.
 638     */
 639     virtual void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2, wxDouble y2);
 640
 641     /**
 642         Stroke disconnected lines from begin to end points, fastest method
 643         available for this purpose.
 644     */
 645     virtual void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints,
 646                              const wxPoint2DDouble* endPoints);
 647     /**
 648         Stroke lines connecting all the points.
 649
 650         Unlike the other overload of this function, this method draws a single
 651         polyline and not a number of disconnected lines.
 652     */
 653     virtual void StrokeLines(size_t n, const wxPoint2DDouble* points);
 654
 655     /**
 656         Strokes along a path with the current pen.
 657     */
 658     virtual void StrokePath(const wxGraphicsPath& path) = 0;
 659
 660     /**
 661         Translates the current transformation matrix.
 662     */
 663     virtual void Translate(wxDouble dx, wxDouble dy) = 0;
 664
 665     /**
 666         Redirects all rendering is done into a fully transparent temporary context
 667     */
 668     virtual void BeginLayer(wxDouble opacity) = 0;
 669
 670     /**
 671         Composites back the drawings into the context with the opacity given at
 672         the BeginLayer call
 673     */
 674     virtual void EndLayer() = 0;
 675
 676     /**
 677         Sets the antialiasing mode, returns true if it supported
 678     */
 679     virtual bool SetAntialiasMode(wxAntialiasMode antialias) = 0;
 680
 681     /**
 682         Returns the current shape antialiasing mode
 683     */
 684     virtual wxAntialiasMode GetAntialiasMode() const ;
 685
 686     /**
 687         Sets the interpolation quality, returns true if it supported
 688      */
 689     virtual bool SetInterpolationQuality(wxInterpolationQuality interpolation) = 0;
 690
 691     /**
 692         Returns the current interpolation quality
 693      */
 694     virtual wxInterpolationQuality GetInterpolationQuality() const;
 695
 696     /**
 697         Sets the compositing operator, returns true if it supported
 698     */
 699     virtual bool SetCompositionMode(wxCompositionMode op) = 0;
 700
 701     /**
 702         Returns the current compositing operator
 703     */
 704     virtual wxCompositionMode GetCompositionMode() const;
 705
 706 };
 707
 708 /**
 709     Represents a single gradient stop in a collection of gradient stops as
 710     represented by wxGraphicsGradientStops.
 711
 712     @library{wxcore}
 713     @category{gdi}
 714
 715     @since 2.9.1
 716 */
 717 class wxGraphicsGradientStop
 718 {
 719 public:
 720     /**
 721         Creates a stop with the given colour and position.
 722
 723         @param col The colour of this stop. Note that the alpha component of
 724             the colour is honoured thus allowing the background colours to
 725             partially show through the gradient.
 726         @param pos The stop position, must be in [0, 1] range with 0 being the
 727             beginning and 1 the end of the gradient.
 728     */
 729     wxGraphicsGradientStop(wxColour col = wxTransparentColour, float pos = 0.);
 730
 731     /// Return the stop colour.
 732     const wxColour& GetColour() const;
 733
 734     /**
 735         Change the stop colour.
 736
 737         @param col The new colour.
 738     */
 739     void SetColour(const wxColour& col);
 740
 741     /// Return the stop position.
 742     float GetPosition() const;
 743
 744     /**
 745         Change the stop position.
 746
 747         @param pos The new position, must always be in [0, 1] range.
 748     */
 749     void SetPosition(float pos);
 750 };
 751
 752 /**
 753     Represents a collection of wxGraphicGradientStop values for use with
 754     CreateLinearGradientBrush and CreateRadialGradientBrush.
 755
 756     The stops are maintained in order of position.  If two or more stops are
 757     added with the same position then the one(s) added later come later.
 758     This can be useful for producing discontinuities in the colour gradient.
 759
 760     Notice that this class is write-once, you can't modify the stops once they
 761     had been added.
 762
 763     @library{wxcore}
 764     @category{gdi}
 765
 766     @since 2.9.1
 767 */
 768 class wxGraphicsGradientStops
 769 {
 770 public:
 771     /**
 772         Initializes the gradient stops with the given boundary colours.
 773
 774         Creates a wxGraphicsGradientStops instance with start colour given
 775         by @a startCol and end colour given by @a endCol.
 776     */
 777     wxGraphicsGradientStops(wxColour startCol = wxTransparentColour,
 778                             wxColour endCol = wxTransparentColour);
 779
 780     /**
 781         Add a new stop.
 782     */
 783     //@{
 784     void Add(const wxGraphicsGradientStop& stop);
 785     void Add(wxColour col, float pos);
 786     //@}
 787
 788     /**
 789         Returns the stop at the given index.
 790
 791         @param n The index, must be in [0, GetCount()) range.
 792     */
 793     wxGraphicsGradientStop Item(unsigned n) const;
 794
 795     /**
 796         Returns the number of stops.
 797     */
 798     unsigned GetCount() const;
 799
 800     /**
 801         Set the start colour to @a col
 802     */
 803     void SetStartColour(wxColour col);
 804
 805     /**
 806         Returns the start colour.
 807     */
 808     wxColour GetStartColour() const;
 809
 810     /**
 811         Set the end colour to @a col
 812     */
 813     void SetEndColour(wxColour col);
 814
 815     /**
 816         Returns the end colour.
 817     */
 818     wxColour GetEndColour() const;
 819 };
 820
 821 /**
 822     @class wxGraphicsRenderer
 823
 824     A wxGraphicsRenderer is the instance corresponding to the rendering engine
 825     used. There may be multiple instances on a system, if there are different
 826     rendering engines present, but there is always only one instance per
 827     engine. This instance is pointed back to by all objects created by it
 828     (wxGraphicsContext, wxGraphicsPath etc) and can be retrieved through their
 829     wxGraphicsObject::GetRenderer() method. Therefore you can create an
 830     additional instance of a path etc. by calling
 831     wxGraphicsObject::GetRenderer() and then using the appropriate CreateXXX()
 832     function of that renderer.
 833
 834     @code
 835     wxGraphicsPath *path = // from somewhere
 836     wxGraphicsBrush *brush = path->GetRenderer()->CreateBrush( *wxBLACK_BRUSH );
 837     @endcode
 838
 839     @library{wxcore}
 840     @category{gdi}
 841 */
 842 class wxGraphicsRenderer : public wxObject
 843 {
 844 public:
 845     /**
 846         Creates a wxGraphicsContext from a wxWindow.
 847     */
 848     virtual wxGraphicsContext* CreateContext(wxWindow* window) = 0;
 849
 850     /**
 851         Creates a wxGraphicsContext from a wxWindowDC
 852     */
 853     virtual wxGraphicsContext* CreateContext(const wxWindowDC& dc) = 0 ;
 854
 855     /**
 856         Creates a wxGraphicsContext from a wxMemoryDC
 857     */
 858     virtual wxGraphicsContext* CreateContext(const wxMemoryDC& dc) = 0 ;
 859
 860     /**
 861         Creates a wxGraphicsContext from a wxPrinterDC
 862     */
 863     virtual wxGraphicsContext* CreateContext(const wxPrinterDC& dc) = 0 ;
 864
 865     /**
 866         Creates a native brush from a wxBrush.
 867     */
 868     virtual wxGraphicsBrush CreateBrush(const wxBrush& brush) = 0;
 869
 870     /**
 871         Creates a wxGraphicsContext from a native context. This native context
 872         must be a CGContextRef for Core Graphics, a Graphics pointer for
 873         GDIPlus, or a cairo_t pointer for cairo.
 874     */
 875     virtual wxGraphicsContext* CreateContextFromNativeContext(void* context) = 0;
 876
 877     /**
 878         Creates a wxGraphicsContext from a native window.
 879     */
 880     virtual wxGraphicsContext* CreateContextFromNativeWindow(void* window) = 0;
 881
 882     /**
 883         Creates a wxGraphicsContext that can be used for measuring texts only.
 884         No drawing commands are allowed.
 885     */
 886     virtual wxGraphicsContext * CreateMeasuringContext() = 0;
 887
 888     /**
 889         Creates a native graphics font from a wxFont and a text colour.
 890     */
 891     virtual wxGraphicsFont CreateFont(const wxFont& font,
 892                                       const wxColour& col = *wxBLACK) = 0;
 893
 894
 895     /**
 896         Creates a native brush with a linear gradient.
 897
 898         Stops support is new since wxWidgets 2.9.1, previously only the start
 899         and end colours could be specified.
 900     */
 901     virtual wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
 902                                                       wxDouble y1,
 903                                                       wxDouble x2,
 904                                                       wxDouble y2,
 905                                                       const wxGraphicsGradientStops& stops) = 0;
 906
 907     /**
 908         Creates a native affine transformation matrix from the passed in
 909         values. The defaults result in an identity matrix.
 910     */
 911     virtual wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 912                                           wxDouble c = 0.0, wxDouble d = 1.0,
 913                                           wxDouble tx = 0.0,
 914                                           wxDouble ty = 0.0) = 0;
 915
 916     /**
 917         Creates a native graphics path which is initially empty.
 918     */
 919     virtual wxGraphicsPath CreatePath() = 0;
 920
 921     /**
 922         Creates a native pen from a wxPen.
 923     */
 924     virtual wxGraphicsPen CreatePen(const wxPen& pen) = 0;
 925
 926     /**
 927         Creates a native brush with a radial gradient.
 928
 929         Stops support is new since wxWidgets 2.9.1, previously only the start
 930         and end colours could be specified.
 931     */
 932     virtual wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
 933                                                       wxDouble xc, wxDouble yc,
 934                                                       wxDouble radius,
 935                                                       const wxGraphicsGradientStops& stops) = 0;
 936
 937     /**
 938         Returns the default renderer on this platform. On OS X this is the Core
 939         Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and
 940         on GTK we currently default to the cairo renderer.
 941     */
 942     static wxGraphicsRenderer* GetDefaultRenderer();
 943 };
 944
 945
 946
 947 /**
 948     @class wxGraphicsBrush
 949
 950     A wxGraphicsBrush is a native representation of a brush. The contents are
 951     specific and private to the respective renderer. Instances are ref counted
 952     and can therefore be assigned as usual. The only way to get a valid
 953     instance is via wxGraphicsContext::CreateBrush() or
 954     wxGraphicsRenderer::CreateBrush().
 955
 956     @library{wxcore}
 957     @category{gdi}
 958 */
 959 class wxGraphicsBrush : public wxGraphicsObject
 960 {
 961 public:
 962
 963 };
 964
 965
 966
 967 /**
 968     @class wxGraphicsFont
 969
 970     A wxGraphicsFont is a native representation of a font. The contents are
 971     specific and private to the respective renderer. Instances are ref counted
 972     and can therefore be assigned as usual. The only way to get a valid
 973     instance is via wxGraphicsContext::CreateFont() or
 974     wxGraphicsRenderer::CreateFont().
 975
 976     @library{wxcore}
 977     @category{gdi}
 978 */
 979 class wxGraphicsFont : public wxGraphicsObject
 980 {
 981 public:
 982
 983 };
 984
 985
 986
 987 /**
 988     @class wxGraphicsPen
 989
 990     A wxGraphicsPen is a native representation of a pen. The contents are
 991     specific and private to the respective renderer. Instances are ref counted
 992     and can therefore be assigned as usual. The only way to get a valid
 993     instance is via wxGraphicsContext::CreatePen() or
 994     wxGraphicsRenderer::CreatePen().
 995
 996     @library{wxcore}
 997     @category{gdi}
 998 */
 999 class wxGraphicsPen : public wxGraphicsObject
1000 {
1001 public:
1002
1003 };
1004
1005
1006
1007 /**
1008     @class wxGraphicsMatrix
1009
1010     A wxGraphicsMatrix is a native representation of an affine matrix. The
1011     contents are specific and private to the respective renderer. Instances are
1012     ref counted and can therefore be assigned as usual. The only way to get a
1013     valid instance is via wxGraphicsContext::CreateMatrix() or
1014     wxGraphicsRenderer::CreateMatrix().
1015
1016     @library{wxcore}
1017     @category{gdi}
1018 */
1019 class wxGraphicsMatrix : public wxGraphicsObject
1020 {
1021 public:
1022     /**
1023         Concatenates the matrix passed with the current matrix.
1024     */
1025     virtual void Concat(const wxGraphicsMatrix* t);
1026     /**
1027         Concatenates the matrix passed with the current matrix.
1028     */
1029     void Concat(const wxGraphicsMatrix& t);
1030
1031     /**
1032         Returns the component values of the matrix via the argument pointers.
1033     */
1034     virtual void Get(wxDouble* a = NULL, wxDouble* b = NULL,
1035                      wxDouble* c = NULL, wxDouble* d = NULL,
1036                      wxDouble* tx = NULL, wxDouble* ty = NULL) const;
1037
1038     /**
1039         Returns the native representation of the matrix. For CoreGraphics this
1040         is a CFAffineMatrix pointer, for GDIPlus a Matrix Pointer, and for
1041         Cairo a cairo_matrix_t pointer.
1042     */
1043     virtual void* GetNativeMatrix() const;
1044
1045     /**
1046         Inverts the matrix.
1047     */
1048     virtual void Invert();
1049
1050     /**
1051         Returns @true if the elements of the transformation matrix are equal.
1052     */
1053     virtual bool IsEqual(const wxGraphicsMatrix* t) const;
1054     /**
1055         Returns @true if the elements of the transformation matrix are equal.
1056     */
1057     bool IsEqual(const wxGraphicsMatrix& t) const;
1058
1059     /**
1060         Return @true if this is the identity matrix.
1061     */
1062     virtual bool IsIdentity() const;
1063
1064     /**
1065         Rotates this matrix (in radians).
1066     */
1067     virtual void Rotate(wxDouble angle);
1068
1069     /**
1070         Scales this matrix.
1071     */
1072     virtual void Scale(wxDouble xScale, wxDouble yScale);
1073
1074     /**
1075         Sets the matrix to the respective values (default values are the
1076         identity matrix).
1077     */
1078     virtual void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0,
1079                      wxDouble d = 1.0, wxDouble tx = 0.0, wxDouble ty = 0.0);
1080
1081     /**
1082         Applies this matrix to a distance (ie. performs all transforms except
1083         translations).
1084     */
1085     virtual void TransformDistance(wxDouble* dx, wxDouble* dy) const;
1086
1087     /**
1088         Applies this matrix to a point.
1089     */
1090     virtual void TransformPoint(wxDouble* x, wxDouble* y) const;
1091
1092     /**
1093         Translates this matrix.
1094     */
1095     virtual void Translate(wxDouble dx, wxDouble dy);
1096 };
1097