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