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