interface/wx/graphics.h

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