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