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