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