]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/graphics.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / interface / wx / graphics.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: graphics.h
3 // Purpose: interface of various wxGraphics* classes
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
7
8 /**
9 @class wxGraphicsPath
10
11 A wxGraphicsPath is a native representation of a geometric path. The
12 contents are specific an private to the respective renderer. Instances are
13 reference counted and can therefore be assigned as usual. The only way to
14 get a valid instance is by using wxGraphicsContext::CreatePath() or
15 wxGraphicsRenderer::CreatePath().
16
17 @library{wxcore}
18 @category{gdi}
19 */
20 class wxGraphicsPath : public wxGraphicsObject
21 {
22 public:
23 /**
24 Adds an arc of a circle.
25
26 The circle is defined by the coordinates of its centre (@a x, @a y) or
27 @a c and its radius @a r. The arc goes from the starting angle @a
28 startAngle to @a endAngle either clockwise or counter-clockwise
29 depending on the value of @a clockwise argument.
30
31 The angles are measured in radians but, contrary to the usual
32 mathematical convention, are always @e clockwise from the horizontal
33 axis.
34 */
35 //@{
36 virtual void AddArc(wxDouble x, wxDouble y, wxDouble r,
37 wxDouble startAngle, wxDouble endAngle,
38 bool clockwise);
39 void AddArc(const wxPoint2DDouble& c, wxDouble r,
40 wxDouble startAngle, wxDouble endAngle, bool clockwise);
41 //@}
42
43 /**
44 Appends a an arc to two tangents connecting (current) to (@a x1,@a y1)
45 and (@a x1,@a y1) to (@a x2,@a y2), also a straight line from (current)
46 to (@a x1,@a y1).
47 */
48 virtual void AddArcToPoint(wxDouble x1, wxDouble y1, wxDouble x2,
49 wxDouble y2, wxDouble r);
50
51 /**
52 Appends a circle around (@a x,@a y) with radius @a r as a new closed
53 subpath.
54 */
55 virtual void AddCircle(wxDouble x, wxDouble y, wxDouble r);
56
57 /**
58 Adds a cubic bezier curve from the current point, using two control
59 points and an end point.
60 */
61 virtual void AddCurveToPoint(wxDouble cx1, wxDouble cy1,
62 wxDouble cx2, wxDouble cy2,
63 wxDouble x, wxDouble y);
64 /**
65 Adds a cubic bezier curve from the current point, using two control
66 points and an end point.
67 */
68 void AddCurveToPoint(const wxPoint2DDouble& c1,
69 const wxPoint2DDouble& c2,
70 const wxPoint2DDouble& e);
71
72 /**
73 Appends an ellipse fitting into the passed in rectangle.
74 */
75 virtual void AddEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
76
77 /**
78 Adds a straight line from the current point to (@a x,@a y).
79 */
80 virtual void AddLineToPoint(wxDouble x, wxDouble y);
81 /**
82 Adds a straight line from the current point to @a p.
83 */
84 void AddLineToPoint(const wxPoint2DDouble& p);
85
86 /**
87 Adds another path.
88 */
89 virtual void AddPath(const wxGraphicsPath& path);
90
91 /**
92 Adds a quadratic bezier curve from the current point, using a control
93 point and an end point.
94 */
95 virtual void AddQuadCurveToPoint(wxDouble cx, wxDouble cy,
96 wxDouble x, wxDouble y);
97
98 /**
99 Appends a rectangle as a new closed subpath.
100 */
101 virtual void AddRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
102
103 /**
104 Appends a rounded rectangle as a new closed subpath.
105 */
106 virtual void AddRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
107 wxDouble h, wxDouble radius);
108
109 /**
110 Closes the current sub-path.
111 */
112 virtual void CloseSubpath();
113
114 /**
115 @return @true if the point is within the path.
116 */
117 bool Contains(const wxPoint2DDouble& c,
118 wxPolygonFillMode fillStyle = wxODDEVEN_RULE) const;
119 /**
120 @return @true if the point is within the path.
121 */
122 virtual bool Contains(wxDouble x, wxDouble y,
123 wxPolygonFillMode fillStyle = wxODDEVEN_RULE) const;
124
125 /**
126 Gets the bounding box enclosing all points (possibly including control
127 points).
128 */
129 wxRect2DDouble GetBox() const;
130 /**
131 Gets the bounding box enclosing all points (possibly including control
132 points).
133 */
134 virtual void GetBox(wxDouble* x, wxDouble* y,
135 wxDouble* w, wxDouble* h) const;
136
137 /**
138 Gets the last point of the current path, (0,0) if not yet set.
139 */
140 virtual void GetCurrentPoint(wxDouble* x, wxDouble* y) const;
141 /**
142 Gets the last point of the current path, (0,0) if not yet set.
143 */
144 wxPoint2DDouble GetCurrentPoint() const;
145
146 /**
147 Returns the native path (CGPathRef for Core Graphics, Path pointer for
148 GDIPlus and a cairo_path_t pointer for cairo).
149 */
150 virtual void* GetNativePath() const;
151
152 /**
153 Begins a new subpath at (@a x,@a y).
154 */
155 virtual void MoveToPoint(wxDouble x, wxDouble y);
156 /**
157 Begins a new subpath at @a p.
158 */
159 void MoveToPoint(const wxPoint2DDouble& p);
160
161 /**
162 Transforms each point of this path by the matrix.
163 */
164 virtual void Transform(const wxGraphicsMatrix& matrix);
165
166 /**
167 Gives back the native path returned by GetNativePath() because there
168 might be some deallocations necessary (e.g. on cairo the native path
169 returned by GetNativePath() is newly allocated each time).
170 */
171 virtual void UnGetNativePath(void* p) const;
172 };
173
174
175
176 /**
177 @class wxGraphicsObject
178
179 This class is the superclass of native graphics objects like pens etc. It
180 allows reference counting. Not instantiated by user code.
181
182 @library{wxcore}
183 @category{gdi}
184
185 @see wxGraphicsBrush, wxGraphicsPen, wxGraphicsMatrix, wxGraphicsPath
186 */
187 class wxGraphicsObject : public wxObject
188 {
189 public:
190 /**
191 Returns the renderer that was used to create this instance, or @NULL
192 if it has not been initialized yet.
193 */
194 wxGraphicsRenderer* GetRenderer() const;
195
196 /**
197 @return @false if this object is valid, otherwise returns @true.
198 */
199 bool IsNull() const;
200 };
201
202 /**
203 Anti-aliasing modes used by wxGraphicsContext::SetAntialiasMode().
204 */
205 enum wxAntialiasMode
206 {
207 /** No anti-aliasing */
208 wxANTIALIAS_NONE,
209
210 /** The default anti-aliasing */
211 wxANTIALIAS_DEFAULT,
212 };
213
214 /**
215 Interpolation quality used by wxGraphicsContext::SetInterpolationQuality().
216 */
217 enum wxInterpolationQuality
218 {
219 /** default interpolation, based on type of context, in general medium quality */
220 wxINTERPOLATION_DEFAULT,
221 /** no interpolation */
222 wxINTERPOLATION_NONE,
223 /** fast interpolation, suited for interactivity */
224 wxINTERPOLATION_FAST,
225 /** better quality */
226 wxINTERPOLATION_GOOD,
227 /** best quality, not suited for interactivity */
228 wxINTERPOLATION_BEST
229 };
230
231 /**
232 Compositing is done using Porter-Duff compositions
233 (see http://keithp.com/~keithp/porterduff/p253-porter.pdf) with
234 wxGraphicsContext::SetCompositionMode().
235
236 The description give a short equation on how the values of a resulting
237 pixel are calculated.
238 @e R = Result, @e S = Source, @e D = Destination, colors premultiplied with alpha
239 @e Ra, @e Sa, @e Da their alpha components
240 */
241 enum wxCompositionMode
242 {
243 /**
244 Indicates invalid or unsupported composition mode.
245
246 This value can't be passed to wxGraphicsContext::SetCompositionMode().
247
248 @since 2.9.2
249 */
250 wxCOMPOSITION_INVALID = -1,
251 wxCOMPOSITION_CLEAR, /**< @e R = 0 */
252 wxCOMPOSITION_SOURCE, /**< @e R = S */
253 wxCOMPOSITION_OVER, /**< @e R = @e S + @e D*(1 - @e Sa) */
254 wxCOMPOSITION_IN, /**< @e R = @e S*@e Da */
255 wxCOMPOSITION_OUT, /**< @e R = @e S*(1 - @e Da) */
256 wxCOMPOSITION_ATOP, /**< @e R = @e S*@e Da + @e D*(1 - @e Sa) */
257
258 wxCOMPOSITION_DEST, /**< @e R = @e D, essentially a noop */
259 wxCOMPOSITION_DEST_OVER, /**< @e R = @e S*(1 - @e Da) + @e D */
260 wxCOMPOSITION_DEST_IN, /**< @e R = @e D*@e Sa */
261 wxCOMPOSITION_DEST_OUT, /**< @e R = @e D*(1 - @e Sa) */
262 wxCOMPOSITION_DEST_ATOP, /**< @e R = @e S*(1 - @e Da) + @e D*@e Sa */
263 wxCOMPOSITION_XOR, /**< @e R = @e S*(1 - @e Da) + @e D*(1 - @e Sa) */
264 wxCOMPOSITION_ADD /**< @e R = @e S + @e D */
265 };
266
267 /**
268 Represents a bitmap.
269
270 The objects of this class are not created directly but only via
271 wxGraphicsContext or wxGraphicsRenderer CreateBitmap(),
272 CreateBitmapFromImage() or CreateSubBitmap() methods. They can subsequently
273 be used with wxGraphicsContext::DrawBitmap(). The only other operation is
274 testing for the bitmap validity which can be performed using IsNull()
275 method inherited from the base class.
276 */
277 class wxGraphicsBitmap : public wxGraphicsObject
278 {
279 public:
280 /**
281 Default constructor creates an invalid bitmap.
282 */
283 wxGraphicsBitmap() {}
284
285 /**
286 Return the contents of this bitmap as wxImage.
287
288 Using this method is more efficient than converting wxGraphicsBitmap to
289 wxBitmap first and then to wxImage and can be useful if, for example,
290 you want to save wxGraphicsBitmap as a disk file in a format not
291 directly supported by wxBitmap.
292
293 Invalid image is returned if the bitmap is invalid.
294
295 @since 2.9.3
296 */
297 wxImage ConvertToImage() const;
298
299 /**
300 Return the pointer to the native bitmap data. (CGImageRef for Core Graphics,
301 cairo_surface_t for Cairo, Bitmap* for GDI+.)
302
303 @since 2.9.4
304 */
305 void* GetNativeBitmap() const;
306 };
307
308 /**
309 @class wxGraphicsContext
310
311 A wxGraphicsContext instance is the object that is drawn upon. It is
312 created by a renderer using wxGraphicsRenderer::CreateContext(). This can
313 be either directly using a renderer instance, or indirectly using the
314 static convenience Create() functions of wxGraphicsContext that always
315 delegate the task to the default renderer.
316
317 @code
318 void MyCanvas::OnPaint(wxPaintEvent &event)
319 {
320 // Create paint DC
321 wxPaintDC dc(this);
322
323 // Create graphics context from it
324 wxGraphicsContext *gc = wxGraphicsContext::Create( dc );
325
326 if (gc)
327 {
328 // make a path that contains a circle and some lines
329 gc->SetPen( *wxRED_PEN );
330 wxGraphicsPath path = gc->CreatePath();
331 path.AddCircle( 50.0, 50.0, 50.0 );
332 path.MoveToPoint(0.0, 50.0);
333 path.AddLineToPoint(100.0, 50.0);
334 path.MoveToPoint(50.0, 0.0);
335 path.AddLineToPoint(50.0, 100.0 );
336 path.CloseSubpath();
337 path.AddRectangle(25.0, 25.0, 50.0, 50.0);
338
339 gc->StrokePath(path);
340
341 delete gc;
342 }
343 }
344 @endcode
345
346 @library{wxcore}
347 @category{gdi,dc}
348
349 @see wxGraphicsRenderer::CreateContext(), wxGCDC, wxDC
350 */
351 class wxGraphicsContext : public wxGraphicsObject
352 {
353 public:
354 /**
355 Creates a wxGraphicsContext from a wxWindow.
356
357 @see wxGraphicsRenderer::CreateContext()
358 */
359 static wxGraphicsContext* Create(wxWindow* window);
360
361 /**
362 Creates a wxGraphicsContext from a wxWindowDC
363
364 @see wxGraphicsRenderer::CreateContext()
365 */
366 static wxGraphicsContext* Create(const wxWindowDC& windowDC);
367
368 /**
369 Creates a wxGraphicsContext from a wxMemoryDC
370
371 @see wxGraphicsRenderer::CreateContext()
372 */
373 static wxGraphicsContext* Create(const wxMemoryDC& memoryDC);
374
375 /**
376 Creates a wxGraphicsContext from a wxPrinterDC. Under GTK+, this will
377 only work when using the GtkPrint printing backend which is available
378 since GTK+ 2.10.
379
380 @see wxGraphicsRenderer::CreateContext(), @ref overview_unixprinting
381 */
382 static wxGraphicsContext* Create(const wxPrinterDC& printerDC);
383
384 /**
385 Creates a wxGraphicsContext from a wxEnhMetaFileDC.
386
387 This function, as wxEnhMetaFileDC class itself, is only available only
388 under MSW.
389
390 @see wxGraphicsRenderer::CreateContext()
391 */
392 static wxGraphicsContext* Create(const wxEnhMetaFileDC& metaFileDC);
393
394 /**
395 Creates a wxGraphicsContext associated with a wxImage.
396
397 The image specifies the size of the context as well as whether alpha is
398 supported (if wxImage::HasAlpha()) or not and the initial contents of
399 the context. The @a image object must have a life time greater than
400 that of the new context as the context copies its contents back to the
401 image when it is destroyed.
402
403 @since 2.9.3
404 */
405 static wxGraphicsContext* Create(wxImage& image);
406
407 /**
408 Create a lightweight context that can be used only for measuring text.
409 */
410 static wxGraphicsContext* Create();
411
412 /**
413 Clips drawings to the specified region.
414 */
415 virtual void Clip(const wxRegion& region) = 0;
416
417 /**
418 Clips drawings to the specified rectangle.
419 */
420 virtual void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h) = 0;
421
422 /**
423 Concatenates the passed in transform with the current transform of this
424 context.
425 */
426 virtual void ConcatTransform(const wxGraphicsMatrix& matrix) = 0;
427
428 /**
429 Creates wxGraphicsBitmap from an existing wxBitmap.
430
431 Returns an invalid wxNullGraphicsBitmap on failure.
432 */
433 virtual wxGraphicsBitmap CreateBitmap( const wxBitmap &bitmap ) = 0;
434
435 /**
436 Creates wxGraphicsBitmap from an existing wxImage.
437
438 This method is more efficient than converting wxImage to wxBitmap first
439 and then calling CreateBitmap() but otherwise has the same effect.
440
441 Returns an invalid wxNullGraphicsBitmap on failure.
442
443 @since 2.9.3
444 */
445 virtual wxGraphicsBitmap CreateBitmapFromImage(const wxImage& image);
446
447 /**
448 Extracts a sub-bitmap from an existing bitmap.
449
450 Currently this function is implemented in the native MSW and OS X
451 versions but not when using Cairo.
452 */
453 virtual wxGraphicsBitmap CreateSubBitmap(const wxGraphicsBitmap& bitmap,
454 wxDouble x, wxDouble y,
455 wxDouble w, wxDouble h) = 0;
456
457 /**
458 Creates a native brush from a wxBrush.
459 */
460 virtual wxGraphicsBrush CreateBrush(const wxBrush& brush) const;
461
462 /**
463 Creates a native graphics font from a wxFont and a text colour.
464 */
465 virtual wxGraphicsFont CreateFont(const wxFont& font,
466 const wxColour& col = *wxBLACK) const;
467
468 /**
469 Creates a font object with the specified attributes.
470
471 The use of overload taking wxFont is preferred, see
472 wxGraphicsRenderer::CreateFont() for more details.
473
474 @since 2.9.3
475 */
476 virtual wxGraphicsFont CreateFont(double sizeInPixels,
477 const wxString& facename,
478 int flags = wxFONTFLAG_DEFAULT,
479 const wxColour& col = *wxBLACK) const;
480
481 /**
482 Creates a wxGraphicsContext from a native context. This native context
483 must be a CGContextRef for Core Graphics, a Graphics pointer for
484 GDIPlus, or a cairo_t pointer for cairo.
485
486 @see wxGraphicsRenderer::CreateContextFromNativeContext()
487 */
488 static wxGraphicsContext* CreateFromNative(void* context);
489
490 /**
491 Creates a wxGraphicsContext from a native window.
492
493 @see wxGraphicsRenderer::CreateContextFromNativeWindow()
494 */
495 static wxGraphicsContext* CreateFromNativeWindow(void* window);
496
497 /**
498 Creates a native brush with a linear gradient.
499
500 The brush starts at (@a x1, @a y1) and ends at (@a x2, @a y2). Either
501 just the start and end gradient colours (@a c1 and @a c2) or full set
502 of gradient @a stops can be specified.
503
504 The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1.
505 */
506 //@{
507 wxGraphicsBrush
508 CreateLinearGradientBrush(wxDouble x1, wxDouble y1,
509 wxDouble x2, wxDouble y2,
510 const wxColour& c1, const wxColour& c2) const;
511
512 wxGraphicsBrush
513 CreateLinearGradientBrush(wxDouble x1, wxDouble y1,
514 wxDouble x2, wxDouble y2,
515 const wxGraphicsGradientStops& stops) const;
516 //@}
517
518 /**
519 Creates a native affine transformation matrix from the passed in
520 values. The default parameters result in an identity matrix.
521 */
522 virtual wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
523 wxDouble c = 0.0, wxDouble d = 1.0,
524 wxDouble tx = 0.0,
525 wxDouble ty = 0.0) const;
526
527 /**
528 Creates a native affine transformation matrix from the passed
529 generic one.
530
531 @since 2.9.4
532 */
533 wxGraphicsMatrix CreateMatrix(const wxAffineMatrix2DBase& mat) const;
534
535 /**
536 Creates a native graphics path which is initially empty.
537 */
538 wxGraphicsPath CreatePath() const;
539
540 /**
541 Creates a native pen from a wxPen.
542 */
543 virtual wxGraphicsPen CreatePen(const wxPen& pen) const;
544
545 /**
546 Creates a native brush with a radial gradient.
547
548 The brush originates at (@a xo, @a yc) and ends on a circle around
549 (@a xc, @a yc) with the given @a radius.
550
551 The gradient may be specified either by its start and end colours @a
552 oColor and @a cColor or by a full set of gradient @a stops.
553
554 The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1.
555 */
556 //@{
557 virtual wxGraphicsBrush
558 CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
559 wxDouble xc, wxDouble yc,
560 wxDouble radius,
561 const wxColour& oColor,
562 const wxColour& cColor) const;
563
564 virtual wxGraphicsBrush
565 CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
566 wxDouble xc, wxDouble yc,
567 wxDouble radius,
568 const wxGraphicsGradientStops& stops) = 0;
569 //@}
570
571 /**
572 Draws the bitmap. In case of a mono bitmap, this is treated as a mask
573 and the current brushed is used for filling.
574 */
575 //@{
576 virtual void DrawBitmap(const wxGraphicsBitmap& bmp,
577 wxDouble x, wxDouble y,
578 wxDouble w, wxDouble h ) = 0;
579 virtual void DrawBitmap(const wxBitmap& bmp,
580 wxDouble x, wxDouble y,
581 wxDouble w, wxDouble h) = 0;
582 //@}
583
584 /**
585 Draws an ellipse.
586 */
587 virtual void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
588
589 /**
590 Draws the icon.
591 */
592 virtual void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y,
593 wxDouble w, wxDouble h) = 0;
594
595 /**
596 Draws a polygon.
597 */
598 virtual void DrawLines(size_t n, const wxPoint2DDouble* points,
599 wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
600
601 /**
602 Draws the path by first filling and then stroking.
603 */
604 virtual void DrawPath(const wxGraphicsPath& path,
605 wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
606
607 /**
608 Draws a rectangle.
609 */
610 virtual void DrawRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
611
612 /**
613 Draws a rounded rectangle.
614 */
615 virtual void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
616 wxDouble h, wxDouble radius);
617
618 /**
619 Draws text at the defined position.
620 */
621 void DrawText(const wxString& str, wxDouble x, wxDouble y);
622 /**
623 Draws text at the defined position.
624
625 @param str
626 The text to draw.
627 @param x
628 The x coordinate position to draw the text at.
629 @param y
630 The y coordinate position to draw the text at.
631 @param angle
632 The angle relative to the (default) horizontal direction to draw
633 the string.
634 */
635 void DrawText(const wxString& str, wxDouble x, wxDouble y, wxDouble angle);
636 /**
637 Draws text at the defined position.
638
639 @param str
640 The text to draw.
641 @param x
642 The x coordinate position to draw the text at.
643 @param y
644 The y coordinate position to draw the text at.
645 @param backgroundBrush
646 Brush to fill the text with.
647 */
648 void DrawText(const wxString& str, wxDouble x, wxDouble y,
649 const wxGraphicsBrush& backgroundBrush);
650 /**
651 Draws text at the defined position.
652
653 @param str
654 The text to draw.
655 @param x
656 The x coordinate position to draw the text at.
657 @param y
658 The y coordinate position to draw the text at.
659 @param angle
660 The angle relative to the (default) horizontal direction to draw
661 the string.
662 @param backgroundBrush
663 Brush to fill the text with.
664 */
665 void DrawText(const wxString& str, wxDouble x, wxDouble y,
666 wxDouble angle, const wxGraphicsBrush& backgroundBrush);
667
668 /**
669 Fills the path with the current brush.
670 */
671 virtual void FillPath(const wxGraphicsPath& path,
672 wxPolygonFillMode fillStyle = wxODDEVEN_RULE) = 0;
673
674 /**
675 Returns the native context (CGContextRef for Core Graphics, Graphics
676 pointer for GDIPlus and cairo_t pointer for cairo).
677 */
678 virtual void* GetNativeContext() = 0;
679
680 /**
681 Fills the @a widths array with the widths from the beginning of
682 @a text to the corresponding character of @a text.
683 */
684 virtual void GetPartialTextExtents(const wxString& text,
685 wxArrayDouble& widths) const = 0;
686
687 /**
688 Gets the dimensions of the string using the currently selected font.
689
690 @param text
691 The text string to measure.
692 @param width
693 Variable to store the total calculated width of the text.
694 @param height
695 Variable to store the total calculated height of the text.
696 @param descent
697 Variable to store the dimension from the baseline of the font to
698 the bottom of the descender.
699 @param externalLeading
700 Any extra vertical space added to the font by the font designer
701 (usually is zero).
702 */
703 virtual void GetTextExtent(const wxString& text, wxDouble* width,
704 wxDouble* height, wxDouble* descent,
705 wxDouble* externalLeading) const = 0;
706
707 /**
708 Gets the current transformation matrix of this context.
709 */
710 virtual wxGraphicsMatrix GetTransform() const = 0;
711
712 /**
713 Resets the clipping to original shape.
714 */
715 virtual void ResetClip() = 0;
716
717 /**
718 Rotates the current transformation matrix (in radians).
719 */
720 virtual void Rotate(wxDouble angle) = 0;
721
722 /**
723 Scales the current transformation matrix.
724 */
725 virtual void Scale(wxDouble xScale, wxDouble yScale) = 0;
726
727 /**
728 Sets the brush for filling paths.
729 */
730 void SetBrush(const wxBrush& brush);
731 /**
732 Sets the brush for filling paths.
733 */
734 virtual void SetBrush(const wxGraphicsBrush& brush);
735
736 /**
737 Sets the font for drawing text.
738 */
739 void SetFont(const wxFont& font, const wxColour& colour);
740 /**
741 Sets the font for drawing text.
742 */
743 virtual void SetFont(const wxGraphicsFont& font);
744
745 /**
746 Sets the pen used for stroking.
747 */
748 void SetPen(const wxPen& pen);
749 /**
750 Sets the pen used for stroking.
751 */
752 virtual void SetPen(const wxGraphicsPen& pen);
753
754 /**
755 Sets the current transformation matrix of this context
756 */
757 virtual void SetTransform(const wxGraphicsMatrix& matrix) = 0;
758
759 /**
760 Strokes a single line.
761 */
762 virtual void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2, wxDouble y2);
763
764 /**
765 Stroke disconnected lines from begin to end points, fastest method
766 available for this purpose.
767 */
768 virtual void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints,
769 const wxPoint2DDouble* endPoints);
770 /**
771 Stroke lines connecting all the points.
772
773 Unlike the other overload of this function, this method draws a single
774 polyline and not a number of disconnected lines.
775 */
776 virtual void StrokeLines(size_t n, const wxPoint2DDouble* points);
777
778 /**
779 Strokes along a path with the current pen.
780 */
781 virtual void StrokePath(const wxGraphicsPath& path) = 0;
782
783 /**
784 Translates the current transformation matrix.
785 */
786 virtual void Translate(wxDouble dx, wxDouble dy) = 0;
787
788 /**
789 Redirects all rendering is done into a fully transparent temporary context
790 */
791 virtual void BeginLayer(wxDouble opacity) = 0;
792
793 /**
794 Composites back the drawings into the context with the opacity given at
795 the BeginLayer call
796 */
797 virtual void EndLayer() = 0;
798
799 /**
800 Sets the antialiasing mode, returns true if it supported
801 */
802 virtual bool SetAntialiasMode(wxAntialiasMode antialias) = 0;
803
804 /**
805 Returns the current shape antialiasing mode
806 */
807 virtual wxAntialiasMode GetAntialiasMode() const ;
808
809 /**
810 Sets the interpolation quality, returns true if it is supported.
811
812 Not implemented in Cairo backend currently.
813 */
814 virtual bool SetInterpolationQuality(wxInterpolationQuality interpolation) = 0;
815
816 /**
817 Returns the current interpolation quality.
818 */
819 virtual wxInterpolationQuality GetInterpolationQuality() const;
820
821 /**
822 Sets the compositing operator, returns true if it supported
823 */
824 virtual bool SetCompositionMode(wxCompositionMode op) = 0;
825
826 /**
827 Returns the current compositing operator
828 */
829 virtual wxCompositionMode GetCompositionMode() const;
830
831
832 /**
833 Push the current state of the context's transformation matrix on a
834 stack.
835
836 @see wxGraphicsContext::PopState
837 */
838 virtual void PushState() = 0;
839
840 /**
841 Pops a stored state from the stack and sets the current transformation
842 matrix to that state.
843
844 @see wxGraphicsContext::PopState
845 */
846 virtual void PopState() = 0;
847
848
849 virtual bool ShouldOffset() const;
850 virtual void EnableOffset(bool enable = true);
851 void DisableOffset();
852 bool OffsetEnabled();
853
854 /**
855 Begin a new document (relevant only for printing / pdf etc.)
856 If there is a progress dialog, message will be shown.
857 */
858 virtual bool StartDoc( const wxString& message );
859
860 /**
861 Done with that document (relevant only for printing / pdf etc.)
862 */
863 virtual void EndDoc();
864
865 /**
866 Opens a new page (relevant only for printing / pdf etc.) with the given
867 size in points. (If both are null the default page size will be used.)
868 */
869 virtual void StartPage( wxDouble width = 0, wxDouble height = 0 );
870
871 /**
872 Ends the current page (relevant only for printing / pdf etc.)
873 */
874 virtual void EndPage();
875
876 /**
877 Make sure that the current content of this context is immediately visible.
878 */
879 virtual void Flush();
880
881 /**
882 Returns the size of the graphics context in device coordinates.
883 */
884 void GetSize(wxDouble* width, wxDouble* height) const;
885
886 /**
887 Returns the resolution of the graphics context in device points per inch.
888 */
889 virtual void GetDPI( wxDouble* dpiX, wxDouble* dpiY);
890
891 };
892
893 /**
894 Represents a single gradient stop in a collection of gradient stops as
895 represented by wxGraphicsGradientStops.
896
897 @library{wxcore}
898 @category{gdi}
899
900 @since 2.9.1
901 */
902 class wxGraphicsGradientStop
903 {
904 public:
905 /**
906 Creates a stop with the given colour and position.
907
908 @param col The colour of this stop. Note that the alpha component of
909 the colour is honoured thus allowing the background colours to
910 partially show through the gradient.
911 @param pos The stop position, must be in [0, 1] range with 0 being the
912 beginning and 1 the end of the gradient.
913 */
914 wxGraphicsGradientStop(wxColour col = wxTransparentColour, float pos = 0.);
915
916 /// Return the stop colour.
917 const wxColour& GetColour() const;
918
919 /**
920 Change the stop colour.
921
922 @param col The new colour.
923 */
924 void SetColour(const wxColour& col);
925
926 /// Return the stop position.
927 float GetPosition() const;
928
929 /**
930 Change the stop position.
931
932 @param pos The new position, must always be in [0, 1] range.
933 */
934 void SetPosition(float pos);
935 };
936
937 /**
938 Represents a collection of wxGraphicGradientStop values for use with
939 CreateLinearGradientBrush and CreateRadialGradientBrush.
940
941 The stops are maintained in order of position. If two or more stops are
942 added with the same position then the one(s) added later come later.
943 This can be useful for producing discontinuities in the colour gradient.
944
945 Notice that this class is write-once, you can't modify the stops once they
946 had been added.
947
948 @library{wxcore}
949 @category{gdi}
950
951 @since 2.9.1
952 */
953 class wxGraphicsGradientStops
954 {
955 public:
956 /**
957 Initializes the gradient stops with the given boundary colours.
958
959 Creates a wxGraphicsGradientStops instance with start colour given
960 by @a startCol and end colour given by @a endCol.
961 */
962 wxGraphicsGradientStops(wxColour startCol = wxTransparentColour,
963 wxColour endCol = wxTransparentColour);
964
965 /**
966 Add a new stop.
967 */
968 //@{
969 void Add(const wxGraphicsGradientStop& stop);
970 void Add(wxColour col, float pos);
971 //@}
972
973 /**
974 Returns the stop at the given index.
975
976 @param n The index, must be in [0, GetCount()) range.
977 */
978 wxGraphicsGradientStop Item(unsigned n) const;
979
980 /**
981 Returns the number of stops.
982 */
983 size_t GetCount() const;
984
985 /**
986 Set the start colour to @a col
987 */
988 void SetStartColour(wxColour col);
989
990 /**
991 Returns the start colour.
992 */
993 wxColour GetStartColour() const;
994
995 /**
996 Set the end colour to @a col
997 */
998 void SetEndColour(wxColour col);
999
1000 /**
1001 Returns the end colour.
1002 */
1003 wxColour GetEndColour() const;
1004 };
1005
1006 /**
1007 @class wxGraphicsRenderer
1008
1009 A wxGraphicsRenderer is the instance corresponding to the rendering engine
1010 used. There may be multiple instances on a system, if there are different
1011 rendering engines present, but there is always only one instance per
1012 engine. This instance is pointed back to by all objects created by it
1013 (wxGraphicsContext, wxGraphicsPath etc) and can be retrieved through their
1014 wxGraphicsObject::GetRenderer() method. Therefore you can create an
1015 additional instance of a path etc. by calling
1016 wxGraphicsObject::GetRenderer() and then using the appropriate CreateXXX()
1017 function of that renderer.
1018
1019 @code
1020 wxGraphicsPath *path = // from somewhere
1021 wxGraphicsBrush *brush = path->GetRenderer()->CreateBrush( *wxBLACK_BRUSH );
1022 @endcode
1023
1024 @library{wxcore}
1025 @category{gdi}
1026 */
1027 class wxGraphicsRenderer : public wxObject
1028 {
1029 public:
1030 /**
1031 Creates wxGraphicsBitmap from an existing wxBitmap.
1032
1033 Returns an invalid wxNullGraphicsBitmap on failure.
1034 */
1035 virtual wxGraphicsBitmap CreateBitmap( const wxBitmap &bitmap ) = 0;
1036
1037 /**
1038 Creates wxGraphicsBitmap from an existing wxImage.
1039
1040 This method is more efficient than converting wxImage to wxBitmap first
1041 and then calling CreateBitmap() but otherwise has the same effect.
1042
1043 Returns an invalid wxNullGraphicsBitmap on failure.
1044
1045 @since 2.9.3
1046 */
1047 virtual wxGraphicsBitmap CreateBitmapFromImage(const wxImage& image) = 0;
1048
1049 /**
1050 Creates a wxImage from a wxGraphicsBitmap.
1051
1052 This method is used by the more convenient wxGraphicsBitmap::ConvertToImage.
1053 */
1054 virtual wxImage CreateImageFromBitmap(const wxGraphicsBitmap& bmp) = 0;
1055
1056 /**
1057 Creates wxGraphicsBitmap from a native bitmap handle.
1058
1059 @a bitmap meaning is platform-dependent. Currently it's a GDI+ @c
1060 Bitmap pointer under MSW, @c CGImage pointer under OS X or a @c
1061 cairo_surface_t pointer when using Cairo under any platform.
1062 */
1063 virtual wxGraphicsBitmap CreateBitmapFromNativeBitmap( void* bitmap ) = 0;
1064
1065 /**
1066 Creates a wxGraphicsContext from a wxWindow.
1067 */
1068 virtual wxGraphicsContext* CreateContext(wxWindow* window) = 0;
1069
1070 /**
1071 Creates a wxGraphicsContext from a wxWindowDC
1072 */
1073 virtual wxGraphicsContext* CreateContext(const wxWindowDC& windowDC) = 0 ;
1074
1075 /**
1076 Creates a wxGraphicsContext from a wxMemoryDC
1077 */
1078 virtual wxGraphicsContext* CreateContext(const wxMemoryDC& memoryDC) = 0 ;
1079
1080 /**
1081 Creates a wxGraphicsContext from a wxPrinterDC
1082 */
1083 virtual wxGraphicsContext* CreateContext(const wxPrinterDC& printerDC) = 0 ;
1084
1085 /**
1086 Creates a wxGraphicsContext from a wxEnhMetaFileDC.
1087
1088 This function, as wxEnhMetaFileDC class itself, is only available only
1089 under MSW.
1090 */
1091 virtual wxGraphicsContext* CreateContext(const wxEnhMetaFileDC& metaFileDC) = 0;
1092
1093 /**
1094 Creates a wxGraphicsContext associated with a wxImage.
1095
1096 This function is used by wxContext::CreateFromImage() and is not
1097 normally called directly.
1098
1099 @since 2.9.3
1100 */
1101 wxGraphicsContext* CreateContextFromImage(wxImage& image);
1102
1103 /**
1104 Creates a native brush from a wxBrush.
1105 */
1106 virtual wxGraphicsBrush CreateBrush(const wxBrush& brush) = 0;
1107
1108 /**
1109 Creates a wxGraphicsContext from a native context. This native context
1110 must be a CGContextRef for Core Graphics, a Graphics pointer for
1111 GDIPlus, or a cairo_t pointer for cairo.
1112 */
1113 virtual wxGraphicsContext* CreateContextFromNativeContext(void* context) = 0;
1114
1115 /**
1116 Creates a wxGraphicsContext from a native window.
1117 */
1118 virtual wxGraphicsContext* CreateContextFromNativeWindow(void* window) = 0;
1119
1120 /**
1121 Creates a wxGraphicsContext that can be used for measuring texts only.
1122 No drawing commands are allowed.
1123 */
1124 virtual wxGraphicsContext * CreateMeasuringContext() = 0;
1125
1126 /**
1127 Creates a native graphics font from a wxFont and a text colour.
1128 */
1129 virtual wxGraphicsFont CreateFont(const wxFont& font,
1130 const wxColour& col = *wxBLACK) = 0;
1131
1132 /**
1133 Creates a graphics font with the given characteristics.
1134
1135 If possible, the CreateFont() overload taking wxFont should be used
1136 instead. The main advantage of this overload is that it can be used
1137 without X server connection under Unix when using Cairo.
1138
1139 @param sizeInPixels
1140 Height of the font in user space units, i.e. normally pixels.
1141 Notice that this is different from the overload taking wxFont as
1142 wxFont size is specified in points.
1143 @param facename
1144 The name of the font. The same font name might not be available
1145 under all platforms so the font name can also be empty to use the
1146 default platform font.
1147 @param flags
1148 Combination of wxFontFlag enum elements. Currently only
1149 @c wxFONTFLAG_ITALIC and @c wxFONTFLAG_BOLD are supported. By
1150 default the normal font version is used.
1151 @param col
1152 The font colour, black by default.
1153
1154 @since 2.9.3
1155 */
1156 virtual wxGraphicsFont CreateFont(double sizeInPixels,
1157 const wxString& facename,
1158 int flags = wxFONTFLAG_DEFAULT,
1159 const wxColour& col = *wxBLACK) = 0;
1160
1161
1162 /**
1163 Creates a native brush with a linear gradient.
1164
1165 Stops support is new since wxWidgets 2.9.1, previously only the start
1166 and end colours could be specified.
1167 */
1168 virtual wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
1169 wxDouble y1,
1170 wxDouble x2,
1171 wxDouble y2,
1172 const wxGraphicsGradientStops& stops) = 0;
1173
1174 /**
1175 Creates a native affine transformation matrix from the passed in
1176 values. The defaults result in an identity matrix.
1177 */
1178 virtual wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
1179 wxDouble c = 0.0, wxDouble d = 1.0,
1180 wxDouble tx = 0.0,
1181 wxDouble ty = 0.0) = 0;
1182
1183 /**
1184 Creates a native graphics path which is initially empty.
1185 */
1186 virtual wxGraphicsPath CreatePath() = 0;
1187
1188 /**
1189 Creates a native pen from a wxPen.
1190 */
1191 virtual wxGraphicsPen CreatePen(const wxPen& pen) = 0;
1192
1193 /**
1194 Creates a native brush with a radial gradient.
1195
1196 Stops support is new since wxWidgets 2.9.1, previously only the start
1197 and end colours could be specified.
1198 */
1199 virtual wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
1200 wxDouble xc, wxDouble yc,
1201 wxDouble radius,
1202 const wxGraphicsGradientStops& stops) = 0;
1203
1204 /**
1205 Extracts a sub-bitmap from an existing bitmap.
1206
1207 Currently this function is implemented in the native MSW and OS X
1208 versions but not when using Cairo.
1209 */
1210 virtual wxGraphicsBitmap CreateSubBitmap(const wxGraphicsBitmap& bitmap,
1211 wxDouble x, wxDouble y,
1212 wxDouble w, wxDouble h) = 0;
1213
1214 /**
1215 Returns the default renderer on this platform. On OS X this is the Core
1216 Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and
1217 on GTK we currently default to the cairo renderer.
1218 */
1219 static wxGraphicsRenderer* GetDefaultRenderer();
1220 static wxGraphicsRenderer* GetCairoRenderer();
1221
1222 };
1223
1224
1225
1226 /**
1227 @class wxGraphicsBrush
1228
1229 A wxGraphicsBrush is a native representation of a brush. The contents are
1230 specific and private to the respective renderer. Instances are ref counted
1231 and can therefore be assigned as usual. The only way to get a valid
1232 instance is via wxGraphicsContext::CreateBrush() or
1233 wxGraphicsRenderer::CreateBrush().
1234
1235 @library{wxcore}
1236 @category{gdi}
1237 */
1238 class wxGraphicsBrush : public wxGraphicsObject
1239 {
1240 public:
1241
1242 };
1243
1244
1245
1246 /**
1247 @class wxGraphicsFont
1248
1249 A wxGraphicsFont is a native representation of a font. The contents are
1250 specific and private to the respective renderer. Instances are ref counted
1251 and can therefore be assigned as usual. The only way to get a valid
1252 instance is via wxGraphicsContext::CreateFont() or
1253 wxGraphicsRenderer::CreateFont().
1254
1255 @library{wxcore}
1256 @category{gdi}
1257 */
1258 class wxGraphicsFont : public wxGraphicsObject
1259 {
1260 public:
1261
1262 };
1263
1264
1265
1266 /**
1267 @class wxGraphicsPen
1268
1269 A wxGraphicsPen is a native representation of a pen. The contents are
1270 specific and private to the respective renderer. Instances are ref counted
1271 and can therefore be assigned as usual. The only way to get a valid
1272 instance is via wxGraphicsContext::CreatePen() or
1273 wxGraphicsRenderer::CreatePen().
1274
1275 @library{wxcore}
1276 @category{gdi}
1277 */
1278 class wxGraphicsPen : public wxGraphicsObject
1279 {
1280 public:
1281
1282 };
1283
1284
1285
1286 /**
1287 @class wxGraphicsMatrix
1288
1289 A wxGraphicsMatrix is a native representation of an affine matrix. The
1290 contents are specific and private to the respective renderer. Instances are
1291 ref counted and can therefore be assigned as usual. The only way to get a
1292 valid instance is via wxGraphicsContext::CreateMatrix() or
1293 wxGraphicsRenderer::CreateMatrix().
1294
1295 @library{wxcore}
1296 @category{gdi}
1297 */
1298 class wxGraphicsMatrix : public wxGraphicsObject
1299 {
1300 public:
1301 /**
1302 Concatenates the matrix passed with the current matrix.
1303 */
1304 virtual void Concat(const wxGraphicsMatrix* t);
1305 /**
1306 Concatenates the matrix passed with the current matrix.
1307 */
1308 void Concat(const wxGraphicsMatrix& t);
1309
1310 /**
1311 Returns the component values of the matrix via the argument pointers.
1312 */
1313 virtual void Get(wxDouble* a = NULL, wxDouble* b = NULL,
1314 wxDouble* c = NULL, wxDouble* d = NULL,
1315 wxDouble* tx = NULL, wxDouble* ty = NULL) const;
1316
1317 /**
1318 Returns the native representation of the matrix. For CoreGraphics this
1319 is a CFAffineMatrix pointer, for GDIPlus a Matrix Pointer, and for
1320 Cairo a cairo_matrix_t pointer.
1321 */
1322 virtual void* GetNativeMatrix() const;
1323
1324 /**
1325 Inverts the matrix.
1326 */
1327 virtual void Invert();
1328
1329 /**
1330 Returns @true if the elements of the transformation matrix are equal.
1331 */
1332 virtual bool IsEqual(const wxGraphicsMatrix* t) const;
1333 /**
1334 Returns @true if the elements of the transformation matrix are equal.
1335 */
1336 bool IsEqual(const wxGraphicsMatrix& t) const;
1337
1338 /**
1339 Return @true if this is the identity matrix.
1340 */
1341 virtual bool IsIdentity() const;
1342
1343 /**
1344 Rotates this matrix clockwise (in radians).
1345
1346 @param angle
1347 Rotation angle in radians, clockwise.
1348 */
1349 virtual void Rotate(wxDouble angle);
1350
1351 /**
1352 Scales this matrix.
1353 */
1354 virtual void Scale(wxDouble xScale, wxDouble yScale);
1355
1356 /**
1357 Sets the matrix to the respective values (default values are the
1358 identity matrix).
1359 */
1360 virtual void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0,
1361 wxDouble d = 1.0, wxDouble tx = 0.0, wxDouble ty = 0.0);
1362
1363 /**
1364 Applies this matrix to a distance (ie. performs all transforms except
1365 translations).
1366 */
1367 virtual void TransformDistance(wxDouble* dx, wxDouble* dy) const;
1368
1369 /**
1370 Applies this matrix to a point.
1371 */
1372 virtual void TransformPoint(wxDouble* x, wxDouble* y) const;
1373
1374 /**
1375 Translates this matrix.
1376 */
1377 virtual void Translate(wxDouble dx, wxDouble dy);
1378 };
1379
1380
1381 const wxGraphicsPen wxNullGraphicsPen;
1382 const wxGraphicsBrush wxNullGraphicsBrush;
1383 const wxGraphicsFont wxNullGraphicsFont;
1384 const wxGraphicsBitmap wxNullGraphicsBitmap;
1385 const wxGraphicsMatrix wxNullGraphicsMatrix;
1386 const wxGraphicsPath wxNullGraphicsPath;