]> git.saurik.com Git - wxWidgets.git/blob - interface/graphics.h
compilation fix for PCH-less build
[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(), wxGCDC, wxDC
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. Under
260 GTK+, this will only work when using the GtkPrint
261 printing backend which is available since GTK+ 2.10.
262
263 @see wxGraphicsRenderer::CreateContext(), @ref overview_unixprinting "Printing under Unix"
264 */
265 static wxGraphicsContext * Create( const wxPrinterDC& dc) ;
266
267 /**
268 Clips drawings to the region
269 */
270 void Clip(const wxRegion& region);
271
272 /**
273 Clips drawings to the rectangle.
274 */
275 void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
276
277 /**
278 Concatenates the passed in transform with the current transform of this context
279 */
280 void ConcatTransform(const wxGraphicsMatrix& matrix);
281
282
283 /**
284 Creates a native brush from a wxBrush.
285 */
286 wxGraphicsBrush CreateBrush(const wxBrush& brush) const;
287
288 /**
289 Creates a native graphics font from a wxFont and a text colour.
290 */
291 wxGraphicsFont CreateFont(const wxFont& font,
292 const wxColour& col = wxBLACK) const;
293
294 /**
295 Creates a wxGraphicsContext from a native context. This native context must be
296 eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a
297 cairo_t pointer for cairo.
298
299 @see wxGraphicsRenderer:: CreateContextFromNativeContext
300 */
301 wxGraphicsContext* CreateFromNative(void* context);
302
303 /**
304 Creates a wxGraphicsContext from a native window.
305
306 @see wxGraphicsRenderer:: CreateContextFromNativeWindow
307 */
308 wxGraphicsContext* CreateFromNativeWindow(void* window);
309
310 /**
311 Creates a native brush, having a linear gradient, starting at (x1,y1) with
312 color c1 to (x2,y2) with color c2
313 */
314 wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
315 wxDouble y1,
316 wxDouble x2,
317 wxDouble y2,
318 const wxColouramp;c1,
319 const wxColouramp;c2) const;
320
321 /**
322 Creates a native affine transformation matrix from the passed in values. The
323 defaults result in an identity matrix.
324 */
325 wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
326 wxDouble c = 0.0,
327 wxDouble d = 1.0,
328 wxDouble tx = 0.0,
329 wxDouble ty = 0.0) const;
330
331 /**
332 Creates a native graphics path which is initially empty.
333 */
334 wxGraphicsPath CreatePath() const;
335
336 /**
337 Creates a native pen from a wxPen.
338 */
339 wxGraphicsPen CreatePen(const wxPen& pen) const;
340
341 /**
342 Creates a native brush, having a radial gradient originating at (xo,yc) with
343 color oColour and ends on a circle around (xc,yc) with radius r and color cColour
344 */
345 wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo,
346 wxDouble yo,
347 wxDouble xc,
348 wxDouble yc,
349 wxDouble radius,
350 const wxColour& oColor,
351 const wxColour& cColor) const;
352
353 /**
354 Draws the bitmap. In case of a mono bitmap, this is treated as a mask and the
355 current brushed is used for filling.
356 */
357 void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y,
358 wxDouble w, wxDouble h);
359
360 /**
361 Draws an ellipse.
362 */
363 void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h);
364
365 /**
366 Draws the icon.
367 */
368 void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y,
369 wxDouble w, wxDouble h);
370
371 /**
372 Draws a polygon.
373 */
374 void DrawLines(size_t n, const wxPoint2DDouble* points,
375 int fillStyle = wxODDEVEN_RULE);
376
377 /**
378 Draws the path by first filling and then stroking.
379 */
380 void DrawPath(const wxGraphicsPath& path,
381 int fillStyle = wxODDEVEN_RULE);
382
383 /**
384 Draws a rectangle.
385 */
386 void DrawRectangle(wxDouble x, wxDouble y, wxDouble w,
387 wxDouble h);
388
389 /**
390 Draws a rounded rectangle.
391 */
392 void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w,
393 wxDouble h,
394 wxDouble radius);
395
396 //@{
397 /**
398 Draws a text at the defined position, at the given angle.
399 */
400 void DrawText(const wxString& str, wxDouble x, wxDouble y,
401 wxDouble angle);
402 void DrawText(const wxString& str, wxDouble x, wxDouble y);
403 //@}
404
405 /**
406 Fills the path with the current brush.
407 */
408 void FillPath(const wxGraphicsPath& path,
409 int fillStyle = wxODDEVEN_RULE);
410
411 /**
412 Returns the native context (CGContextRef for Core Graphics, Graphics pointer
413 for GDIPlus and cairo_t pointer for cairo).
414 */
415 void* GetNativeContext();
416
417 /**
418 Fills the @a widths array with the widths from the beginning of
419 @a text to the corresponding character of @e text.
420 */
421 void GetPartialTextExtents(const wxString& text,
422 wxArrayDouble& widths) const;
423
424 /**
425 Gets the dimensions of the string using the currently selected font.
426 @e string is the text string to measure, @e w and @e h are
427 the total width and height respectively, @a descent is the
428 dimension from the baseline of the font to the bottom of the
429 descender, and @a externalLeading is any extra vertical space added
430 to the font by the font designer (usually is zero).
431 */
432 void GetTextExtent(const wxString& text, wxDouble* width,
433 wxDouble* height,
434 wxDouble* descent,
435 wxDouble* externalLeading) const;
436
437 /**
438 Gets the current transformation matrix of this context.
439 */
440 wxGraphicsMatrix GetTransform() const;
441
442 /**
443 Resets the clipping to original shape.
444 */
445 void ResetClip();
446
447 /**
448 Rotates the current transformation matrix (radians),
449 */
450 void Rotate(wxDouble angle);
451
452 /**
453 Scales the current transformation matrix.
454 */
455 void Scale(wxDouble xScale, wxDouble yScale);
456
457 //@{
458 /**
459 Sets the brush for filling paths.
460 */
461 void SetBrush(const wxBrush& brush);
462 void SetBrush(const wxGraphicsBrush& brush);
463 //@}
464
465 //@{
466 /**
467 Sets the font for drawing text.
468 */
469 void SetFont(const wxFont& font, const wxColour& colour);
470 void SetFont(const wxGraphicsFont& font);
471 //@}
472
473 //@{
474 /**
475 Sets the pen used for stroking.
476 */
477 void SetPen(const wxGraphicsPen& pen);
478 void SetPen(const wxPen& pen);
479 //@}
480
481 /**
482 Sets the current transformation matrix of this context
483 */
484 void SetTransform(const wxGraphicsMatrix& matrix);
485
486 /**
487 Strokes a single line.
488 */
489 void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2,
490 wxDouble y2);
491
492 //@{
493 /**
494 Stroke disconnected lines from begin to end points, fastest method available
495 for this purpose.
496 */
497 void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints,
498 const wxPoint2DDouble* endPoints);
499 void StrokeLines(size_t n, const wxPoint2DDouble* points);
500 //@}
501
502 /**
503 Strokes along a path with the current pen.
504 */
505 void StrokePath(const wxGraphicsPath& path);
506
507 /**
508 Translates the current transformation matrix.
509 */
510 void Translate(wxDouble dx, wxDouble dy);
511 };
512
513
514
515 /**
516 @class wxGraphicsRenderer
517 @wxheader{graphics.h}
518
519 A wxGraphicsRenderer is the instance corresponding to the rendering engine
520 used. There may be multiple instances on a system, if there are different
521 rendering engines present, but there is always only one instance per engine.
522 This instance is pointed back to by all objects created by it (wxGraphicsContext,
523 wxGraphicsPath etc) and can be retrieved through their wxGraphicsObject::GetRenderer()
524 method. Therefore you can create an additional instance of a path etc. by calling
525 wxGraphicsObject::GetRenderer() and then using the appropriate CreateXXX function
526 of that renderer.
527
528 @code
529 wxGraphicsPath *path = // from somewhere
530 wxGraphicsBrush *brush = path->GetRenderer()->CreateBrush( *wxBLACK_BRUSH );
531 @endcode
532
533 @library{wxcore}
534 @category{FIXME}
535 */
536 class wxGraphicsRenderer : public wxObject
537 {
538 public:
539 /**
540 Creates a wxGraphicsContext from a wxWindow.
541 */
542 virtual wxGraphicsContext* CreateContext(wxWindow* window) = 0;
543
544 /**
545 Creates a wxGraphicsContext from a wxWindowDC
546 */
547 virtual wxGraphicsContext * CreateContext( const wxWindowDC& dc) = 0 ;
548
549 /**
550 Creates a wxGraphicsContext from a wxMemoryDC
551 */
552 virtual wxGraphicsContext * CreateContext( const wxMemoryDC& dc) = 0 ;
553
554 /**
555 Creates a wxGraphicsContext from a wxPrinterDC
556 */
557 virtual wxGraphicsContext * CreateContext( const wxPrinterDC& dc) = 0 ;
558
559 /**
560 Creates a native brush from a wxBrush.
561 */
562 wxGraphicsBrush CreateBrush(const wxBrush& brush);
563
564
565 /**
566 Creates a wxGraphicsContext from a native context. This native context must be
567 eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a cairo_t
568 pointer for cairo.
569 */
570 wxGraphicsContext* CreateContextFromNativeContext(void* context);
571
572 /**
573 Creates a wxGraphicsContext from a native window.
574 */
575 wxGraphicsContext* CreateContextFromNativeWindow(void* window);
576
577 /**
578 Creates a native graphics font from a wxFont and a text colour.
579 */
580 wxGraphicsFont CreateFont(const wxFont& font,
581 const wxColour& col = wxBLACK);
582
583 /**
584 Creates a native brush, having a linear gradient, starting at (x1,y1) with
585 color c1 to (x2,y2) with color c2
586 */
587 wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1,
588 wxDouble y1,
589 wxDouble x2,
590 wxDouble y2,
591 const wxColouramp;c1,
592 const wxColouramp;c2);
593
594 /**
595 Creates a native affine transformation matrix from the passed in values. The
596 defaults result in an identity matrix.
597 */
598 wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0,
599 wxDouble c = 0.0,
600 wxDouble d = 1.0,
601 wxDouble tx = 0.0,
602 wxDouble ty = 0.0);
603
604 /**
605 Creates a native graphics path which is initially empty.
606 */
607 wxGraphicsPath CreatePath();
608
609 /**
610 Creates a native pen from a wxPen.
611 */
612 wxGraphicsPen CreatePen(const wxPen& pen);
613
614 /**
615 Creates a native brush, having a radial gradient originating at (xo,yc) with
616 color oColour and ends on a circle around (xc,yc) with radius r and color cColour
617 */
618 wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo,
619 wxDouble yo,
620 wxDouble xc,
621 wxDouble yc,
622 wxDouble radius,
623 const wxColour& oColour,
624 const wxColour& cColour);
625
626 /**
627 Returns the default renderer on this platform. On OS X this is the Core
628 Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and on GTK we currently default to the cairo renderer.
629 */
630 static wxGraphicsRenderer* GetDefaultRenderer();
631 };
632
633
634
635 /**
636 @class wxGraphicsBrush
637 @wxheader{graphics.h}
638
639
640 @library{wxcore}
641 @category{FIXME}
642 */
643 class wxGraphicsBrush : public wxGraphicsObject
644 {
645 public:
646
647 };
648
649
650
651 /**
652 @class wxGraphicsFont
653 @wxheader{graphics.h}
654
655
656 @library{wxcore}
657 @category{FIXME}
658 */
659 class wxGraphicsFont : public wxGraphicsObject
660 {
661 public:
662
663 };
664
665
666
667 /**
668 @class wxGraphicsPen
669 @wxheader{graphics.h}
670
671
672 @library{wxcore}
673 @category{FIXME}
674 */
675 class wxGraphicsPen : public wxGraphicsObject
676 {
677 public:
678
679 };
680
681
682
683 /**
684 @class wxGraphicsMatrix
685 @wxheader{graphics.h}
686
687 A wxGraphicsMatrix is a native representation of an affine matrix. The contents
688 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.
689
690 @library{wxcore}
691 @category{FIXME}
692 */
693 class wxGraphicsMatrix : public wxGraphicsObject
694 {
695 public:
696 //@{
697 /**
698
699 */
700 void Concat(const wxGraphicsMatrix* t);
701 void Concat(const wxGraphicsMatrix& t);
702 //@}
703
704 /**
705 Returns the component values of the matrix via the argument pointers.
706 */
707 void Get(wxDouble* a = NULL, wxDouble* b = NULL, wxDouble* c = NULL,
708 wxDouble* d = NULL, wxDouble* tx = NULL,
709 wxDouble* ty = NULL) const;
710
711 /**
712 Returns the native representation of the matrix. For CoreGraphics this is a
713 CFAffineMatrix pointer. For GDIPlus a Matrix Pointer and for Cairo a cairo_matrix_t pointer.
714 */
715 void* GetNativeMatrix() const;
716
717 /**
718 Inverts the matrix.
719 */
720 void Invert();
721
722 /**
723 Returns @true if the elements of the transformation matrix are equal.
724 */
725 bool IsEqual(const wxGraphicsMatrix& t) const;
726
727 /**
728 Return @true if this is the identity matrix.
729 */
730 bool IsIdentity() const;
731
732 /**
733 Rotates this matrix (radians).
734 */
735 void Rotate(wxDouble angle);
736
737 /**
738 Scales this matrix.
739 */
740 void Scale(wxDouble xScale, wxDouble yScale);
741
742 /**
743 Sets the matrix to the respective values (default values are the identity
744 matrix)
745 */
746 void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0,
747 wxDouble d = 1.0, wxDouble tx = 0.0,
748 wxDouble ty = 0.0);
749
750 /**
751 Applies this matrix to a distance (ie. performs all transforms except
752 translations)
753 */
754 void TransformDistance(wxDouble* dx, wxDouble* dy) const;
755
756 /**
757 Applies this matrix to a point.
758 */
759 void TransformPoint(wxDouble* x, wxDouble* y) const;
760
761 /**
762 Translates this matrix.
763 */
764 void Translate(wxDouble dx, wxDouble dy);
765 };
766