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