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