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