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