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 originats 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 disconnected lines from begin to end points, fastest method
 624         available for this purpose.
 625     */
 626     virtual void StrokeLines(size_t n, const wxPoint2DDouble* points);
 627
 628     /**
 629         Strokes along a path with the current pen.
 630     */
 631     virtual void StrokePath(const wxGraphicsPath& path) = 0;
 632
 633     /**
 634         Translates the current transformation matrix.
 635     */
 636     virtual void Translate(wxDouble dx, wxDouble dy) = 0;
 637
 638     /**
 639         Redirects all rendering is done into a fully transparent temporary context
 640     */
 641     virtual void BeginLayer(wxDouble opacity) = 0;
 642
 643     /**
 644         Composites back the drawings into the context with the opacity given at
 645         the BeginLayer call
 646     */
 647     virtual void EndLayer() = 0;
 648
 649     /**
 650         Sets the antialiasing mode, returns true if it supported
 651     */
 652     virtual bool SetAntialiasMode(wxAntialiasMode antialias) = 0;
 653
 654     /**
 655         Returns the current shape antialiasing mode
 656     */
 657     virtual wxAntialiasMode GetAntialiasMode() const ;
 658
 659     /**
 660         Sets the compositing operator, returns true if it supported
 661     */
 662     virtual bool SetCompositionMode(wxCompositionMode op) = 0;
 663
 664     /**
 665         Returns the current compositing operator
 666     */
 667     virtual wxCompositionMode GetCompositionMode() const;
 668
 669 };
 670
 671 /**
 672     Represents a single gradient stop in a collection of gradient stops as
 673     represented by wxGraphicsGradientStops.
 674
 675     @library{wxcore}
 676     @category{gdi}
 677
 678     @since 2.9.1
 679 */
 680 class wxGraphicsGradientStop
 681 {
 682 public:
 683     /**
 684         Creates a stop with the given colour and position.
 685
 686         @param col The colour of this stop. Note that the alpha component of
 687             the colour is honoured thus allowing the background colours to
 688             partially show through the gradient.
 689         @param pos The stop position, must be in [0, 1] range with 0 being the
 690             beginning and 1 the end of the gradient.
 691     */
 692     wxGraphicsGradientStop(wxColour col = wxTransparentColour, float pos = 0.);
 693
 694     /// Return the stop colour.
 695     const wxColour& GetColour() const;
 696
 697     /**
 698         Change the stop colour.
 699
 700         @param col The new colour.
 701     */
 702     void SetColour(const wxColour& col);
 703
 704     /// Return the stop position.
 705     float GetPosition() const;
 706
 707     /**
 708         Change the stop position.
 709
 710         @param pos The new position, must always be in [0, 1] range.
 711     */
 712     void SetPosition(float pos);
 713 };
 714
 715 /**
 716     Represents a collection of wxGraphicGradientStop values for use with
 717     CreateLinearGradientBrush and CreateRadialGradientBrush.
 718
 719     The stops are maintained in order of position.  If two or more stops are
 720     added with the same position then the one(s) added later come later.
 721     This can be useful for producing discontinuities in the colour gradient.
 722
 723     Notice that this class is write-once, you can't modify the stops once they
 724     had been added.
 725
 726     @library{wxcore}
 727     @category{gdi}
 728
 729     @since 2.9.1
 730 */
 731 class wxGraphicsGradientStops
 732 {
 733 public:
 734     /**
 735         Initializes the gradient stops with the given boundary colours.
 736
 737         Creates a wxGraphicsGradientStops instance with start colour given
 738         by @a startCol and end colour given by @a endCol.
 739     */
 740     wxGraphicsGradientStops(wxColour startCol = wxTransparentColour,
 741                             wxColour endCol = wxTransparentColour);
 742
 743     /**
 744         Add a new stop.
 745     */
 746     //@{
 747     void Add(const wxGraphicsGradientStop& stop);
 748     void Add(wxColour col, float pos);
 749     //@}
 750
 751     /**
 752         Returns the stop at the given index.
 753
 754         @param n The index, must be in [0, GetCount()) range.
 755     */
 756     wxGraphicsGradientStop Item(unsigned n) const;
 757
 758     /**
 759         Returns the number of stops.
 760     */
 761     unsigned GetCount() const;
 762
 763     /**
 764         Set the start colour to @a col
 765     */
 766     void SetStartColour(wxColour col);
 767
 768     /**
 769         Returns the start colour.
 770     */
 771     wxColour GetStartColour() const;
 772
 773     /**
 774         Set the end colour to @a col
 775     */
 776     void SetEndColour(wxColour col);
 777
 778     /**
 779         Returns the end colour.
 780     */
 781     wxColour GetEndColour() const;
 782 };
 783
 784 /**
 785     @class wxGraphicsRenderer
 786
 787     A wxGraphicsRenderer is the instance corresponding to the rendering engine
 788     used. There may be multiple instances on a system, if there are different
 789     rendering engines present, but there is always only one instance per
 790     engine. This instance is pointed back to by all objects created by it
 791     (wxGraphicsContext, wxGraphicsPath etc) and can be retrieved through their
 792     wxGraphicsObject::GetRenderer() method. Therefore you can create an
 793     additional instance of a path etc. by calling
 794     wxGraphicsObject::GetRenderer() and then using the appropriate CreateXXX()
 795     function of that renderer.
 796
 797     @code
 798     wxGraphicsPath *path = // from somewhere
 799     wxGraphicsBrush *brush = path->GetRenderer()->CreateBrush( *wxBLACK_BRUSH );
 800     @endcode
 801
 802     @library{wxcore}
 803     @category{gdi}
 804 */
 805 class wxGraphicsRenderer : public wxObject
 806 {
 807 public:
 808     /**
 809         Creates a wxGraphicsContext from a wxWindow.
 810     */
 811     virtual wxGraphicsContext* CreateContext(wxWindow* window) = 0;
 812
 813     /**
 814         Creates a wxGraphicsContext from a wxWindowDC
 815     */
 816     virtual wxGraphicsContext* CreateContext(const wxWindowDC& dc) = 0 ;
 817
 818     /**
 819         Creates a wxGraphicsContext from a wxMemoryDC
 820     */
 821     virtual wxGraphicsContext* CreateContext(const wxMemoryDC& dc) = 0 ;
 822
 823     /**
 824         Creates a wxGraphicsContext from a wxPrinterDC
 825     */
 826     virtual wxGraphicsContext* CreateContext(const wxPrinterDC& dc) = 0 ;
 827
 828     /**
 829         Creates a native brush from a wxBrush.
 830     */
 831     virtual wxGraphicsBrush CreateBrush(const wxBrush& brush) = 0;
 832
 833     /**
 834         Creates a wxGraphicsContext from a native context. This native context
 835         must be a CGContextRef for Core Graphics, a Graphics pointer for
 836         GDIPlus, or a cairo_t pointer for cairo.
 837     */
 838     virtual wxGraphicsContext* CreateContextFromNativeContext(void* context) = 0;
 839
 840     /**
 841         Creates a wxGraphicsContext from a native window.
 842     */
 843     virtual wxGraphicsContext* CreateContextFromNativeWindow(void* window) = 0;
 844
 845     /**
 846         Creates a wxGraphicsContext that can be used for measuring texts only.
 847         No drawing commands are allowed.
 848     */
 849     virtual wxGraphicsContext * CreateMeasuringContext() = 0;
 850
 851     /**
 852         Creates a native graphics font from a wxFont and a text colour.
 853     */
 854     virtual wxGraphicsFont CreateFont(const wxFont& font,
 855                                       const wxColour& col = *wxBLACK) = 0;
 856
 857
 858     /**
 859         Creates a native brush with a linear gradient.
 860
 861         Stops support is new since wxWidgets 2.9.1, previously only the start
 862         and end colours could be specified.
 863     */
 864     virtual wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
 865                                                       wxDouble y1,
 866                                                       wxDouble x2,
 867                                                       wxDouble y2,
 868                                                       const wxGraphicsGradientStops& stops) = 0;
 869
 870     /**
 871         Creates a native affine transformation matrix from the passed in
 872         values. The defaults result in an identity matrix.
 873     */
 874     virtual wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
 875                                           wxDouble c = 0.0, wxDouble d = 1.0,
 876                                           wxDouble tx = 0.0,
 877                                           wxDouble ty = 0.0) = 0;
 878
 879     /**
 880         Creates a native graphics path which is initially empty.
 881     */
 882     virtual wxGraphicsPath CreatePath() = 0;
 883
 884     /**
 885         Creates a native pen from a wxPen.
 886     */
 887     virtual wxGraphicsPen CreatePen(const wxPen& pen) = 0;
 888
 889     /**
 890         Creates a native brush with a radial gradient.
 891
 892         Stops support is new since wxWidgets 2.9.1, previously only the start
 893         and end colours could be specified.
 894     */
 895     virtual wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
 896                                                       wxDouble xc, wxDouble yc,
 897                                                       wxDouble radius,
 898                                                       const wxGraphicsGradientStops& stops) = 0;
 899
 900     /**
 901         Returns the default renderer on this platform. On OS X this is the Core
 902         Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and
 903         on GTK we currently default to the cairo renderer.
 904     */
 905     static wxGraphicsRenderer* GetDefaultRenderer();
 906 };
 907
 908
 909
 910 /**
 911     @class wxGraphicsBrush
 912
 913     A wxGraphicsBrush is a native representation of a brush. The contents are
 914     specific and private to the respective renderer. Instances are ref counted
 915     and can therefore be assigned as usual. The only way to get a valid
 916     instance is via wxGraphicsContext::CreateBrush() or
 917     wxGraphicsRenderer::CreateBrush().
 918
 919     @library{wxcore}
 920     @category{gdi}
 921 */
 922 class wxGraphicsBrush : public wxGraphicsObject
 923 {
 924 public:
 925
 926 };
 927
 928
 929
 930 /**
 931     @class wxGraphicsFont
 932
 933     A wxGraphicsFont is a native representation of a font. The contents are
 934     specific and private to the respective renderer. Instances are ref counted
 935     and can therefore be assigned as usual. The only way to get a valid
 936     instance is via wxGraphicsContext::CreateFont() or
 937     wxGraphicsRenderer::CreateFont().
 938
 939     @library{wxcore}
 940     @category{gdi}
 941 */
 942 class wxGraphicsFont : public wxGraphicsObject
 943 {
 944 public:
 945
 946 };
 947
 948
 949
 950 /**
 951     @class wxGraphicsPen
 952
 953     A wxGraphicsPen is a native representation of a pen. The contents are
 954     specific and private to the respective renderer. Instances are ref counted
 955     and can therefore be assigned as usual. The only way to get a valid
 956     instance is via wxGraphicsContext::CreatePen() or
 957     wxGraphicsRenderer::CreatePen().
 958
 959     @library{wxcore}
 960     @category{gdi}
 961 */
 962 class wxGraphicsPen : public wxGraphicsObject
 963 {
 964 public:
 965
 966 };
 967
 968
 969
 970 /**
 971     @class wxGraphicsMatrix
 972
 973     A wxGraphicsMatrix is a native representation of an affine matrix. The
 974     contents are specific and private to the respective renderer. Instances are
 975     ref counted and can therefore be assigned as usual. The only way to get a
 976     valid instance is via wxGraphicsContext::CreateMatrix() or
 977     wxGraphicsRenderer::CreateMatrix().
 978
 979     @library{wxcore}
 980     @category{gdi}
 981 */
 982 class wxGraphicsMatrix : public wxGraphicsObject
 983 {
 984 public:
 985     /**
 986         Concatenates the matrix passed with the current matrix.
 987     */
 988     virtual void Concat(const wxGraphicsMatrix* t);
 989     /**
 990         Concatenates the matrix passed with the current matrix.
 991     */
 992     void Concat(const wxGraphicsMatrix& t);
 993
 994     /**
 995         Returns the component values of the matrix via the argument pointers.
 996     */
 997     virtual void Get(wxDouble* a = NULL, wxDouble* b = NULL,
 998                      wxDouble* c = NULL, wxDouble* d = NULL,
 999                      wxDouble* tx = NULL, wxDouble* ty = NULL) const;
1000
1001     /**
1002         Returns the native representation of the matrix. For CoreGraphics this
1003         is a CFAffineMatrix pointer, for GDIPlus a Matrix Pointer, and for
1004         Cairo a cairo_matrix_t pointer.
1005     */
1006     virtual void* GetNativeMatrix() const;
1007
1008     /**
1009         Inverts the matrix.
1010     */
1011     virtual void Invert();
1012
1013     /**
1014         Returns @true if the elements of the transformation matrix are equal.
1015     */
1016     virtual bool IsEqual(const wxGraphicsMatrix* t) const;
1017     /**
1018         Returns @true if the elements of the transformation matrix are equal.
1019     */
1020     bool IsEqual(const wxGraphicsMatrix& t) const;
1021
1022     /**
1023         Return @true if this is the identity matrix.
1024     */
1025     virtual bool IsIdentity() const;
1026
1027     /**
1028         Rotates this matrix (in radians).
1029     */
1030     virtual void Rotate(wxDouble angle);
1031
1032     /**
1033         Scales this matrix.
1034     */
1035     virtual void Scale(wxDouble xScale, wxDouble yScale);
1036
1037     /**
1038         Sets the matrix to the respective values (default values are the
1039         identity matrix).
1040     */
1041     virtual void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0,
1042                      wxDouble d = 1.0, wxDouble tx = 0.0, wxDouble ty = 0.0);
1043
1044     /**
1045         Applies this matrix to a distance (ie. performs all transforms except
1046         translations).
1047     */
1048     virtual void TransformDistance(wxDouble* dx, wxDouble* dy) const;
1049
1050     /**
1051         Applies this matrix to a point.
1052     */
1053     virtual void TransformPoint(wxDouble* x, wxDouble* y) const;
1054
1055     /**
1056         Translates this matrix.
1057     */
1058     virtual void Translate(wxDouble dx, wxDouble dy);
1059 };
1060