]> git.saurik.com Git - wxWidgets.git/blob - interface/graphics.h
Minor doc improvements
[wxWidgets.git] / interface / graphics.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: graphics.h
3 // Purpose: interface of wxGraphicsPath
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxGraphicsPath
11 @wxheader{graphics.h}
12
13 A wxGraphicsPath is a native representation of an geometric path. The contents
14 are specific an private to the respective renderer. Instances are ref counted and can
15 therefore be assigned as usual. The only way to get a valid instance is via a
16 CreatePath call on the graphics context or the renderer instance.
17
18 @library{wxcore}
19 @category{FIXME}
20 */
21 class wxGraphicsPath : public wxGraphicsObject
22 {
23 public:
24 //@{
25 /**
26
27 */
28 void AddArc(wxDouble x, wxDouble y, wxDouble r,
29 wxDouble startAngle,
30 wxDouble endAngle, bool clockwise);
31 void AddArc(const wxPoint2DDouble& c, wxDouble r,
32 wxDouble startAngle,
33 wxDouble endAngle,
34 bool clockwise);
35 //@}
36
37 /**
38 Appends a an arc to two tangents connecting (current) to (x1,y1) and (x1,y1) to
39 (x2,y2), also a straight line from (current) to (x1,y1).
40 */
41 void AddArcToPoint(wxDouble x1, wxDouble y1, wxDouble x2,
42 wxDouble y2,
43 wxDouble r);
44
45 /**
46 Appends a circle around (x,y) with radius r as a new closed subpath.
47 */
48 void AddCircle(wxDouble x, wxDouble y, wxDouble r);
49
50 //@{
51 /**
52
53 */
54 void AddCurveToPoint(wxDouble cx1, wxDouble cy1, wxDouble cx2,
55 wxDouble cy2,
56 wxDouble x,
57 wxDouble y);
58 void AddCurveToPoint(const wxPoint2DDouble& c1,
59 const wxPoint2DDouble& c2,
60 const wxPoint2DDouble& e);
61 //@}
62
63 /**
64 Appends an ellipse fitting into the passed in rectangle.
65 */
66 void AddEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
67
68 //@{
69 /**
70
71 */
72 void AddLineToPoint(wxDouble x, wxDouble y);
73 void AddLineToPoint(const wxPoint2DDouble& p);
74 //@}
75
76 /**
77 Adds another path.
78 */
79 void AddPath(const wxGraphicsPath& path);
80
81 /**
82 Adds a quadratic Bezier curve from the current point, using a control point and
83 an end point.
84 */
85 void AddQuadCurveToPoint(wxDouble cx, wxDouble cy, wxDouble x,
86 wxDouble y);
87
88 /**
89 Appends a rectangle as a new closed subpath.
90 */
91 void AddRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
92
93 /**
94 Appends a rounded rectangle as a new closed subpath.
95 */
96 void AddRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
97 wxDouble h,
98 wxDouble radius);
99
100 /**
101 Closes the current sub-path.
102 */
103 void CloseSubpath();
104
105 //@{
106 /**
107 Returns @true if the point is within the path.
108 */
109 bool Contains(const wxPoint2DDouble& c,
110 int fillStyle = wxODDEVEN_RULE) const;
111 const bool Contains(wxDouble x, wxDouble y,
112 int fillStyle = wxODDEVEN_RULE) const;
113 //@}
114
115 //@{
116 /**
117 Gets the bounding box enclosing all points (possibly including control points).
118 */
119 wxRect2DDouble GetBox() const;
120 const void GetBox(wxDouble* x, wxDouble* y, wxDouble* w,
121 wxDouble* h) const;
122 //@}
123
124 //@{
125 /**
126 Gets the last point of the current path, (0,0) if not yet set.
127 */
128 void GetCurrentPoint(wxDouble* x, wxDouble* y) const;
129 const wxPoint2DDouble GetCurrentPoint() const;
130 //@}
131
132 /**
133 Returns the native path (CGPathRef for Core Graphics, Path pointer for GDIPlus
134 and a cairo_path_t pointer for cairo).
135 */
136 void* GetNativePath() const;
137
138 //@{
139 /**
140 Begins a new subpath at (x,y)
141 */
142 void MoveToPoint(wxDouble x, wxDouble y);
143 void MoveToPoint(const wxPoint2DDouble& p);
144 //@}
145
146 /**
147 Transforms each point of this path by the matrix.
148 */
149 void Transform(const wxGraphicsMatrix& matrix);
150
151 /**
152 Gives back the native path returned by GetNativePath() because there might be
153 some deallocations necessary (eg on cairo the native path returned by
154 GetNativePath is newly allocated each time).
155 */
156 void UnGetNativePath(void* p) const;
157 };
158
159
160
161 /**
162 @class wxGraphicsObject
163 @wxheader{graphics.h}
164
165 This class is the superclass of native graphics objects like pens etc. It
166 allows reference counting. Not instantiated by user code.
167
168 @library{wxcore}
169 @category{FIXME}
170
171 @see wxGraphicsBrush, wxGraphicsPen, wxGraphicsMatrix, wxGraphicsPath
172 */
173 class wxGraphicsObject : public wxObject
174 {
175 public:
176 /**
177 Returns the renderer that was used to create this instance, or @NULL if it has
178 not been initialized yet
179 */
180 wxGraphicsRenderer* GetRenderer() const;
181
182 /**
183 Is this object valid (@false) or still empty (@true)?
184 */
185 bool IsNull() const;
186 };
187
188
189
190 /**
191 @class wxGraphicsContext
192 @wxheader{graphics.h}
193
194 A wxGraphicsContext instance is the object that is drawn upon. It is created by
195 a renderer using wxGraphicsRenderer::CreateContext(). This can be either directly
196 using a renderer instance, or indirectly using the static convenience Create()
197 functions of wxGraphicsContext that always delegate the task to the default renderer.
198
199 @code
200 void MyCanvas::OnPaint(wxPaintEvent &event)
201 {
202 // Create paint DC
203 wxPaintDC dc(this);
204
205 // Create graphics context from it
206 wxGraphicsContext *gc = wxGraphicsContext::Create( dc );
207
208 if (gc)
209 {
210 // make a path that contains a circle and some lines
211 gc->SetPen( *wxRED_PEN );
212 wxGraphicsPath path = gc->CreatePath();
213 path.AddCircle( 50.0, 50.0, 50.0 );
214 path.MoveToPoint(0.0, 50.0);
215 path.AddLineToPoint(100.0, 50.0);
216 path.MoveToPoint(50.0, 0.0);
217 path.AddLineToPoint(50.0, 100.0 );
218 path.CloseSubpath();
219 path.AddRectangle(25.0, 25.0, 50.0, 50.0);
220
221 gc->StrokePath(path);
222
223 delete gc;
224 }
225 }
226 @endcode
227
228
229 @library{wxcore}
230 @category{FIXME}
231
232 @see wxGraphicsRenderer:: CreateContext
233 */
234 class wxGraphicsContext : public wxGraphicsObject
235 {
236 public:
237 /**
238 Creates a wxGraphicsContext from a wxWindow.
239
240 @see wxGraphicsRenderer::CreateContext()
241 */
242 static wxGraphicsContext* Create( wxWindow* window ) ;
243
244 /**
245 Creates a wxGraphicsContext from a wxWindowDC
246
247 @see wxGraphicsRenderer::CreateContext()
248 */
249 static wxGraphicsContext* Create( const wxWindowDC& dc) ;
250
251 /**
252 Creates a wxGraphicsContext from a wxMemoryDC
253
254 @see wxGraphicsRenderer::CreateContext()
255 */
256 static wxGraphicsContext * Create( const wxMemoryDC& dc) ;
257
258 /**
259 Creates a wxGraphicsContext from a wxPrinterDC
260
261 @see wxGraphicsRenderer::CreateContext()
262 */
263 static wxGraphicsContext * Create( const wxPrinterDC& dc) ;
264
265 /**
266 Clips drawings to the region
267 */
268 void Clip(const wxRegion& region);
269
270 /**
271 Clips drawings to the rectangle.
272 */
273 void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
274
275 /**
276 Concatenates the passed in transform with the current transform of this context
277 */
278 void ConcatTransform(const wxGraphicsMatrix& matrix);
279
280
281 /**
282 Creates a native brush from a wxBrush.
283 */
284 wxGraphicsBrush CreateBrush(const wxBrush& brush) const;
285
286 /**
287 Creates a native graphics font from a wxFont and a text colour.
288 */
289 wxGraphicsFont CreateFont(const wxFont& font,
290 const wxColour& col = wxBLACK) const;
291
292 /**
293 Creates a wxGraphicsContext from a native context. This native context must be
294 eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a
295 cairo_t pointer for cairo.
296
297 Creates a wxGraphicsContext from a native window.
298
299 @see wxGraphicsRenderer:: CreateContextFromNativeContext
300 */
301 wxGraphicsContext* CreateFromNative(void* context);
302
303 /**
304 @see wxGraphicsRenderer:: CreateContextFromNativeWindow
305 */
306 wxGraphicsContext* CreateFromNativeWindow(void* window);
307
308 /**
309 Creates a native brush, having a linear gradient, starting at (x1,y1) with
310 color c1 to (x2,y2) with color c2
311 */
312 wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
313 wxDouble y1,
314 wxDouble x2,
315 wxDouble y2,
316 const wxColouramp;c1,
317 const wxColouramp;c2) const;
318
319 /**
320 Creates a native affine transformation matrix from the passed in values. The
321 defaults result in an identity matrix.
322 */
323 wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
324 wxDouble c = 0.0,
325 wxDouble d = 1.0,
326 wxDouble tx = 0.0,
327 wxDouble ty = 0.0) const;
328
329 /**
330 Creates a native graphics path which is initially empty.
331 */
332 wxGraphicsPath CreatePath() const;
333
334 /**
335 Creates a native pen from a wxPen.
336 */
337 wxGraphicsPen CreatePen(const wxPen& pen) const;
338
339 /**
340 Creates a native brush, having a radial gradient originating at (xo,yc) with
341 color oColour and ends on a circle around (xc,yc) with radius r and color cColour
342 */
343 wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo,
344 wxDouble yo,
345 wxDouble xc,
346 wxDouble yc,
347 wxDouble radius,
348 const wxColour& oColor,
349 const wxColour& cColor) const;
350
351 /**
352 Draws the bitmap. In case of a mono bitmap, this is treated as a mask and the
353 current brushed is used for filling.
354 */
355 void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y,
356 wxDouble w, wxDouble h);
357
358 /**
359 Draws an ellipse.
360 */
361 void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
362
363 /**
364 Draws the icon.
365 */
366 void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y,
367 wxDouble w, wxDouble h);
368
369 /**
370 Draws a polygon.
371 */
372 void DrawLines(size_t n, const wxPoint2DDouble* points,
373 int fillStyle = wxODDEVEN_RULE);
374
375 /**
376 Draws the path by first filling and then stroking.
377 */
378 void DrawPath(const wxGraphicsPath& path,
379 int fillStyle = wxODDEVEN_RULE);
380
381 /**
382 Draws a rectangle.
383 */
384 void DrawRectangle(wxDouble x, wxDouble y, wxDouble w,
385 wxDouble h);
386
387 /**
388 Draws a rounded rectangle.
389 */
390 void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
391 wxDouble h,
392 wxDouble radius);
393
394 //@{
395 /**
396 Draws a text at the defined position, at the given angle.
397 */
398 void DrawText(const wxString& str, wxDouble x, wxDouble y,
399 wxDouble angle);
400 void DrawText(const wxString& str, wxDouble x, wxDouble y);
401 //@}
402
403 /**
404 Fills the path with the current brush.
405 */
406 void FillPath(const wxGraphicsPath& path,
407 int fillStyle = wxODDEVEN_RULE);
408
409 /**
410 Returns the native context (CGContextRef for Core Graphics, Graphics pointer
411 for GDIPlus and cairo_t pointer for cairo).
412 */
413 void* GetNativeContext();
414
415 /**
416 Fills the @a widths array with the widths from the beginning of
417 @a text to the corresponding character of @e text.
418 */
419 void GetPartialTextExtents(const wxString& text,
420 wxArrayDouble& widths) const;
421
422 /**
423 Gets the dimensions of the string using the currently selected font.
424 @e string is the text string to measure, @e w and @e h are
425 the total width and height respectively, @a descent is the
426 dimension from the baseline of the font to the bottom of the
427 descender, and @a externalLeading is any extra vertical space added
428 to the font by the font designer (usually is zero).
429 */
430 void GetTextExtent(const wxString& text, wxDouble* width,
431 wxDouble* height,
432 wxDouble* descent,
433 wxDouble* externalLeading) const;
434
435 /**
436 Gets the current transformation matrix of this context.
437 */
438 wxGraphicsMatrix GetTransform() const;
439
440 /**
441 Resets the clipping to original shape.
442 */
443 void ResetClip();
444
445 /**
446 Rotates the current transformation matrix (radians),
447 */
448 void Rotate(wxDouble angle);
449
450 /**
451 Scales the current transformation matrix.
452 */
453 void Scale(wxDouble xScale, wxDouble yScale);
454
455 //@{
456 /**
457 Sets the brush for filling paths.
458 */
459 void SetBrush(const wxBrush& brush);
460 void SetBrush(const wxGraphicsBrush& brush);
461 //@}
462
463 //@{
464 /**
465 Sets the font for drawing text.
466 */
467 void SetFont(const wxFont& font, const wxColour& colour);
468 void SetFont(const wxGraphicsFont& font);
469 //@}
470
471 //@{
472 /**
473 Sets the pen used for stroking.
474 */
475 void SetPen(const wxGraphicsPen& pen);
476 void SetPen(const wxPen& pen);
477 //@}
478
479 /**
480 Sets the current transformation matrix of this context
481 */
482 void SetTransform(const wxGraphicsMatrix& matrix);
483
484 /**
485 Strokes a single line.
486 */
487 void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2,
488 wxDouble y2);
489
490 //@{
491 /**
492 Stroke disconnected lines from begin to end points, fastest method available
493 for this purpose.
494 */
495 void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints,
496 const wxPoint2DDouble* endPoints);
497 void StrokeLines(size_t n, const wxPoint2DDouble* points);
498 //@}
499
500 /**
501 Strokes along a path with the current pen.
502 */
503 void StrokePath(const wxGraphicsPath& path);
504
505 /**
506 Translates the current transformation matrix.
507 */
508 void Translate(wxDouble dx, wxDouble dy);
509 };
510
511
512
513 /**
514 @class wxGraphicsRenderer
515 @wxheader{graphics.h}
516
517 A wxGraphicsRenderer is the instance corresponding to the rendering engine
518 used. There may be multiple instances on a system, if there are different
519 rendering engines present, but there is always only one instance per engine.
520 This instance is pointed back to by all objects created by it (wxGraphicsContext,
521 wxGraphicsPath etc) and can be retrieved through their wxGraphicsObject::GetRenderer()
522 method. Therefore you can create an additional instance of a path etc. by calling
523 wxGraphicsObject::GetRenderer() and then using the appropriate CreateXXX function
524 of that renderer.
525
526 @code
527 wxGraphicsPath *path = // from somewhere
528 wxGraphicsBrush *brush = path->GetRenderer()->CreateBrush( *wxBLACK_BRUSH );
529 @endcode
530
531 @library{wxcore}
532 @category{FIXME}
533 */
534 class wxGraphicsRenderer : public wxObject
535 {
536 public:
537 /**
538 Creates a wxGraphicsContext from a wxWindow.
539 */
540 virtual wxGraphicsContext* CreateContext(wxWindow* window) = 0;
541
542 /**
543 Creates a wxGraphicsContext from a wxWindowDC
544 */
545 virtual wxGraphicsContext * CreateContext( const wxWindowDC& dc) = 0 ;
546
547 /**
548 Creates a wxGraphicsContext from a wxMemoryDC
549 */
550 virtual wxGraphicsContext * CreateContext( const wxMemoryDC& dc) = 0 ;
551
552 /**
553 Creates a wxGraphicsContext from a wxPrinterDC
554 */
555 virtual wxGraphicsContext * CreateContext( const wxPrinterDC& dc) = 0 ;
556
557 /**
558 Creates a native brush from a wxBrush.
559 */
560 wxGraphicsBrush CreateBrush(const wxBrush& brush);
561
562
563 /**
564 Creates a wxGraphicsContext from a native context. This native context must be
565 eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a cairo_t
566 pointer for cairo.
567 */
568 wxGraphicsContext* CreateContextFromNativeContext(void* context);
569
570 /**
571 Creates a wxGraphicsContext from a native window.
572 */
573 wxGraphicsContext* CreateContextFromNativeWindow(void* window);
574
575 /**
576 Creates a native graphics font from a wxFont and a text colour.
577 */
578 wxGraphicsFont CreateFont(const wxFont& font,
579 const wxColour& col = wxBLACK);
580
581 /**
582 Creates a native brush, having a linear gradient, starting at (x1,y1) with
583 color c1 to (x2,y2) with color c2
584 */
585 wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
586 wxDouble y1,
587 wxDouble x2,
588 wxDouble y2,
589 const wxColouramp;c1,
590 const wxColouramp;c2);
591
592 /**
593 Creates a native affine transformation matrix from the passed in values. The
594 defaults result in an identity matrix.
595 */
596 wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
597 wxDouble c = 0.0,
598 wxDouble d = 1.0,
599 wxDouble tx = 0.0,
600 wxDouble ty = 0.0);
601
602 /**
603 Creates a native graphics path which is initially empty.
604 */
605 wxGraphicsPath CreatePath();
606
607 /**
608 Creates a native pen from a wxPen.
609 */
610 wxGraphicsPen CreatePen(const wxPen& pen);
611
612 /**
613 Creates a native brush, having a radial gradient originating at (xo,yc) with
614 color oColour and ends on a circle around (xc,yc) with radius r and color cColour
615 */
616 wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo,
617 wxDouble yo,
618 wxDouble xc,
619 wxDouble yc,
620 wxDouble radius,
621 const wxColour& oColour,
622 const wxColour& cColour);
623
624 /**
625 Returns the default renderer on this platform. On OS X this is the Core
626 Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and on GTK we currently default to the cairo renderer.
627 */
628 static wxGraphicsRenderer* GetDefaultRenderer();
629 };
630
631
632
633 /**
634 @class wxGraphicsBrush
635 @wxheader{graphics.h}
636
637
638 @library{wxcore}
639 @category{FIXME}
640 */
641 class wxGraphicsBrush : public wxGraphicsObject
642 {
643 public:
644
645 };
646
647
648
649 /**
650 @class wxGraphicsFont
651 @wxheader{graphics.h}
652
653
654 @library{wxcore}
655 @category{FIXME}
656 */
657 class wxGraphicsFont : public wxGraphicsObject
658 {
659 public:
660
661 };
662
663
664
665 /**
666 @class wxGraphicsPen
667 @wxheader{graphics.h}
668
669
670 @library{wxcore}
671 @category{FIXME}
672 */
673 class wxGraphicsPen : public wxGraphicsObject
674 {
675 public:
676
677 };
678
679
680
681 /**
682 @class wxGraphicsMatrix
683 @wxheader{graphics.h}
684
685 A wxGraphicsMatrix is a native representation of an affine matrix. The contents
686 are specific and private to the respective renderer. Instances are ref counted and can therefore be assigned as usual. The only way to get a valid instance is via a CreateMatrix call on the graphics context or the renderer instance.
687
688 @library{wxcore}
689 @category{FIXME}
690 */
691 class wxGraphicsMatrix : public wxGraphicsObject
692 {
693 public:
694 //@{
695 /**
696
697 */
698 void Concat(const wxGraphicsMatrix* t);
699 void Concat(const wxGraphicsMatrix& t);
700 //@}
701
702 /**
703 Returns the component values of the matrix via the argument pointers.
704 */
705 void Get(wxDouble* a = NULL, wxDouble* b = NULL, wxDouble* c = NULL,
706 wxDouble* d = NULL, wxDouble* tx = NULL,
707 wxDouble* ty = NULL) const;
708
709 /**
710 Returns the native representation of the matrix. For CoreGraphics this is a
711 CFAffineMatrix pointer. For GDIPlus a Matrix Pointer and for Cairo a cairo_matrix_t pointer.
712 */
713 void* GetNativeMatrix() const;
714
715 /**
716 Inverts the matrix.
717 */
718 void Invert();
719
720 /**
721 Returns @true if the elements of the transformation matrix are equal.
722 */
723 bool IsEqual(const wxGraphicsMatrix& t) const;
724
725 /**
726 Return @true if this is the identity matrix.
727 */
728 bool IsIdentity() const;
729
730 /**
731 Rotates this matrix (radians).
732 */
733 void Rotate(wxDouble angle);
734
735 /**
736 Scales this matrix.
737 */
738 void Scale(wxDouble xScale, wxDouble yScale);
739
740 /**
741 Sets the matrix to the respective values (default values are the identity
742 matrix)
743 */
744 void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0,
745 wxDouble d = 1.0, wxDouble tx = 0.0,
746 wxDouble ty = 0.0);
747
748 /**
749 Applies this matrix to a distance (ie. performs all transforms except
750 translations)
751 */
752 void TransformDistance(wxDouble* dx, wxDouble* dy) const;
753
754 /**
755 Applies this matrix to a point.
756 */
757 void TransformPoint(wxDouble* x, wxDouble* y) const;
758
759 /**
760 Translates this matrix.
761 */
762 void Translate(wxDouble dx, wxDouble dy);
763 };
764