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