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