1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: graphics context header
4 // Author: Stefan Csomor
7 // Copyright: (c) Stefan Csomor
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_GRAPHICS_H_
13 #define _WX_GRAPHICS_H_
17 #if wxUSE_GRAPHICS_CONTEXT
19 #include "wx/geometry.h"
20 #include "wx/dynarray.h"
22 class WXDLLIMPEXP_FWD_CORE wxWindowDC
;
23 class WXDLLIMPEXP_FWD_CORE wxMemoryDC
;
24 class WXDLLIMPEXP_FWD_CORE wxGraphicsContext
;
25 class WXDLLIMPEXP_FWD_CORE wxGraphicsPath
;
26 class WXDLLIMPEXP_FWD_CORE wxGraphicsMatrix
;
27 class WXDLLIMPEXP_FWD_CORE wxGraphicsFigure
;
28 class WXDLLIMPEXP_FWD_CORE wxGraphicsRenderer
;
29 class WXDLLIMPEXP_FWD_CORE wxGraphicsPen
;
30 class WXDLLIMPEXP_FWD_CORE wxGraphicsBrush
;
31 class WXDLLIMPEXP_FWD_CORE wxGraphicsFont
;
34 * notes about the graphics context apis
36 * angles : are measured in radians, 0.0 being in direction of positiv x axis, PI/2 being
37 * in direction of positive y axis.
40 // Base class of all objects used for drawing in the new graphics API, the always point back to their
41 // originating rendering engine, there is no dynamic unloading of a renderer currently allowed,
42 // these references are not counted
45 // The data used by objects like graphics pens etc is ref counted, in order to avoid unnecessary expensive
46 // duplication. Any operation on a shared instance that results in a modified state, uncouples this
47 // instance from the other instances that were shared - using copy on write semantics
50 class WXDLLIMPEXP_FWD_CORE wxGraphicsObjectRefData
;
51 class WXDLLIMPEXP_FWD_CORE wxGraphicsMatrixData
;
52 class WXDLLIMPEXP_FWD_CORE wxGraphicsPathData
;
54 class WXDLLIMPEXP_CORE wxGraphicsObject
: public wxObject
58 wxGraphicsObject( wxGraphicsRenderer
* renderer
) ;
59 virtual ~wxGraphicsObject() ;
63 // returns the renderer that was used to create this instance, or NULL if it has not been initialized yet
64 wxGraphicsRenderer
* GetRenderer() const ;
65 wxGraphicsObjectRefData
* GetGraphicsData() const ;
67 virtual wxObjectRefData
* CreateRefData() const;
68 virtual wxObjectRefData
* CloneRefData(const wxObjectRefData
* data
) const;
70 DECLARE_DYNAMIC_CLASS(wxGraphicsObject
)
73 class WXDLLIMPEXP_CORE wxGraphicsPen
: public wxGraphicsObject
77 virtual ~wxGraphicsPen() {}
79 DECLARE_DYNAMIC_CLASS(wxGraphicsPen
)
82 extern WXDLLEXPORT_DATA(wxGraphicsPen
) wxNullGraphicsPen
;
84 class WXDLLIMPEXP_CORE wxGraphicsBrush
: public wxGraphicsObject
88 virtual ~wxGraphicsBrush() {}
90 DECLARE_DYNAMIC_CLASS(wxGraphicsBrush
)
93 extern WXDLLEXPORT_DATA(wxGraphicsBrush
) wxNullGraphicsBrush
;
95 class WXDLLIMPEXP_CORE wxGraphicsFont
: public wxGraphicsObject
99 virtual ~wxGraphicsFont() {}
101 DECLARE_DYNAMIC_CLASS(wxGraphicsFont
)
104 extern WXDLLEXPORT_DATA(wxGraphicsFont
) wxNullGraphicsFont
;
106 class WXDLLIMPEXP_CORE wxGraphicsMatrix
: public wxGraphicsObject
109 wxGraphicsMatrix() {}
111 virtual ~wxGraphicsMatrix() {}
113 // concatenates the matrix
114 virtual void Concat( const wxGraphicsMatrix
*t
);
115 void Concat( const wxGraphicsMatrix
&t
) { Concat( &t
); }
117 // sets the matrix to the respective values
118 virtual void Set(wxDouble a
=1.0, wxDouble b
=0.0, wxDouble c
=0.0, wxDouble d
=1.0,
119 wxDouble tx
=0.0, wxDouble ty
=0.0);
121 // gets the component valuess of the matrix
122 virtual void Get(wxDouble
* a
=NULL
, wxDouble
* b
=NULL
, wxDouble
* c
=NULL
,
123 wxDouble
* d
=NULL
, wxDouble
* tx
=NULL
, wxDouble
* ty
=NULL
) const;
125 // makes this the inverse matrix
126 virtual void Invert();
128 // returns true if the elements of the transformation matrix are equal ?
129 virtual bool IsEqual( const wxGraphicsMatrix
* t
) const;
130 bool IsEqual( const wxGraphicsMatrix
& t
) const { return IsEqual( &t
); }
132 // return true if this is the identity matrix
133 virtual bool IsIdentity() const;
139 // add the translation to this matrix
140 virtual void Translate( wxDouble dx
, wxDouble dy
);
142 // add the scale to this matrix
143 virtual void Scale( wxDouble xScale
, wxDouble yScale
);
145 // add the rotation to this matrix (radians)
146 virtual void Rotate( wxDouble angle
);
149 // apply the transforms
152 // applies that matrix to the point
153 virtual void TransformPoint( wxDouble
*x
, wxDouble
*y
) const;
155 // applies the matrix except for translations
156 virtual void TransformDistance( wxDouble
*dx
, wxDouble
*dy
) const;
158 // returns the native representation
159 virtual void * GetNativeMatrix() const;
161 const wxGraphicsMatrixData
* GetMatrixData() const
162 { return (const wxGraphicsMatrixData
*) GetRefData(); }
163 wxGraphicsMatrixData
* GetMatrixData()
164 { return (wxGraphicsMatrixData
*) GetRefData(); }
167 DECLARE_DYNAMIC_CLASS(wxGraphicsMatrix
)
170 extern WXDLLEXPORT_DATA(wxGraphicsMatrix
) wxNullGraphicsMatrix
;
172 class WXDLLIMPEXP_CORE wxGraphicsPath
: public wxGraphicsObject
176 virtual ~wxGraphicsPath() {}
179 // These are the path primitives from which everything else can be constructed
182 // begins a new subpath at (x,y)
183 virtual void MoveToPoint( wxDouble x
, wxDouble y
);
184 void MoveToPoint( const wxPoint2DDouble
& p
);
186 // adds a straight line from the current point to (x,y)
187 virtual void AddLineToPoint( wxDouble x
, wxDouble y
);
188 void AddLineToPoint( const wxPoint2DDouble
& p
);
190 // adds a cubic Bezier curve from the current point, using two control points and an end point
191 virtual void AddCurveToPoint( wxDouble cx1
, wxDouble cy1
, wxDouble cx2
, wxDouble cy2
, wxDouble x
, wxDouble y
) ;
192 void AddCurveToPoint( const wxPoint2DDouble
& c1
, const wxPoint2DDouble
& c2
, const wxPoint2DDouble
& e
);
195 virtual void AddPath( const wxGraphicsPath
& path
);
197 // closes the current sub-path
198 virtual void CloseSubpath() ;
200 // gets the last point of the current path, (0,0) if not yet set
201 virtual void GetCurrentPoint( wxDouble
* x
, wxDouble
* y
) const;
202 wxPoint2DDouble
GetCurrentPoint() const;
204 // adds an arc of a circle centering at (x,y) with radius (r) from startAngle to endAngle
205 virtual void AddArc( wxDouble x
, wxDouble y
, wxDouble r
, wxDouble startAngle
, wxDouble endAngle
, bool clockwise
) ;
206 void AddArc( const wxPoint2DDouble
& c
, wxDouble r
, wxDouble startAngle
, wxDouble endAngle
, bool clockwise
);
209 // These are convenience functions which - if not available natively will be assembled
210 // using the primitives from above
213 // adds a quadratic Bezier curve from the current point, using a control point and an end point
214 virtual void AddQuadCurveToPoint( wxDouble cx
, wxDouble cy
, wxDouble x
, wxDouble y
);
216 // appends a rectangle as a new closed subpath
217 virtual void AddRectangle( wxDouble x
, wxDouble y
, wxDouble w
, wxDouble h
);
219 // appends an ellipsis as a new closed subpath fitting the passed rectangle
220 virtual void AddCircle( wxDouble x
, wxDouble y
, wxDouble r
);
222 // appends a an arc to two tangents connecting (current) to (x1,y1) and (x1,y1) to (x2,y2), also a straight line from (current) to (x1,y1)
223 virtual void AddArcToPoint( wxDouble x1
, wxDouble y1
, wxDouble x2
, wxDouble y2
, wxDouble r
) ;
225 // appends an ellipse
226 virtual void AddEllipse( wxDouble x
, wxDouble y
, wxDouble w
, wxDouble h
);
228 // appends a rounded rectangle
229 virtual void AddRoundedRectangle( wxDouble x
, wxDouble y
, wxDouble w
, wxDouble h
, wxDouble radius
);
231 // returns the native path
232 virtual void * GetNativePath() const;
234 // give the native path returned by GetNativePath() back (there might be some deallocations necessary)
235 virtual void UnGetNativePath(void *p
)const;
237 // transforms each point of this path by the matrix
238 virtual void Transform( const wxGraphicsMatrix
& matrix
);
240 // gets the bounding box enclosing all points (possibly including control points)
241 virtual void GetBox(wxDouble
*x
, wxDouble
*y
, wxDouble
*w
, wxDouble
*h
)const;
242 wxRect2DDouble
GetBox()const;
244 virtual bool Contains( wxDouble x
, wxDouble y
, int fillStyle
= wxODDEVEN_RULE
)const;
245 bool Contains( const wxPoint2DDouble
& c
, int fillStyle
= wxODDEVEN_RULE
)const;
247 const wxGraphicsPathData
* GetPathData() const
248 { return (const wxGraphicsPathData
*) GetRefData(); }
249 wxGraphicsPathData
* GetPathData()
250 { return (wxGraphicsPathData
*) GetRefData(); }
253 DECLARE_DYNAMIC_CLASS(wxGraphicsPath
)
256 extern WXDLLEXPORT_DATA(wxGraphicsPath
) wxNullGraphicsPath
;
259 class WXDLLIMPEXP_CORE wxGraphicsContext
: public wxGraphicsObject
262 wxGraphicsContext(wxGraphicsRenderer
* renderer
);
264 virtual ~wxGraphicsContext();
266 static wxGraphicsContext
* Create( const wxWindowDC
& dc
) ;
267 static wxGraphicsContext
* Create( const wxMemoryDC
& dc
) ;
269 static wxGraphicsContext
* CreateFromNative( void * context
) ;
271 static wxGraphicsContext
* CreateFromNativeWindow( void * window
) ;
273 static wxGraphicsContext
* Create( wxWindow
* window
) ;
275 // create a context that can be used for measuring texts only, no drawing allowed
276 static wxGraphicsContext
* Create();
278 // begin a new document (relevant only for printing / pdf etc) if there is a progress dialog, message will be shown
279 virtual bool StartDoc( const wxString
& message
) ;
281 // done with that document (relevant only for printing / pdf etc)
282 virtual void EndDoc();
284 // opens a new page (relevant only for printing / pdf etc) with the given size in points
285 // (if both are null the default page size will be used)
286 virtual void StartPage( wxDouble width
= 0, wxDouble height
= 0 );
288 // ends the current page (relevant only for printing / pdf etc)
289 virtual void EndPage();
291 // make sure that the current content of this context is immediately visible
292 virtual void Flush();
294 wxGraphicsPath
CreatePath() const;
296 virtual wxGraphicsPen
CreatePen(const wxPen
& pen
) const;
298 virtual wxGraphicsBrush
CreateBrush(const wxBrush
& brush
) const;
300 // sets the brush to a linear gradient, starting at (x1,y1) with color c1 to (x2,y2) with color c2
301 virtual wxGraphicsBrush
CreateLinearGradientBrush( wxDouble x1
, wxDouble y1
, wxDouble x2
, wxDouble y2
,
302 const wxColour
&c1
, const wxColour
&c2
) const;
304 // sets the brush to a radial gradient originating at (xo,yc) with color oColor and ends on a circle around (xc,yc)
305 // with radius r and color cColor
306 virtual wxGraphicsBrush
CreateRadialGradientBrush( wxDouble xo
, wxDouble yo
, wxDouble xc
, wxDouble yc
, wxDouble radius
,
307 const wxColour
&oColor
, const wxColour
&cColor
) const;
310 virtual wxGraphicsFont
CreateFont( const wxFont
&font
, const wxColour
&col
= *wxBLACK
) const;
312 // create a 'native' matrix corresponding to these values
313 virtual wxGraphicsMatrix
CreateMatrix( wxDouble a
=1.0, wxDouble b
=0.0, wxDouble c
=0.0, wxDouble d
=1.0,
314 wxDouble tx
=0.0, wxDouble ty
=0.0) const;
316 // push the current state of the context, ie the transformation matrix on a stack
317 virtual void PushState() = 0;
319 // pops a stored state from the stack
320 virtual void PopState() = 0;
322 // clips drawings to the region intersected with the current clipping region
323 virtual void Clip( const wxRegion
®ion
) = 0;
325 // clips drawings to the rect intersected with the current clipping region
326 virtual void Clip( wxDouble x
, wxDouble y
, wxDouble w
, wxDouble h
) = 0;
328 // resets the clipping to original extent
329 virtual void ResetClip() = 0 ;
331 // returns the native context
332 virtual void * GetNativeContext() = 0;
334 // returns the current logical function
335 virtual int GetLogicalFunction() const { return m_logicalFunction
; }
337 // sets the current logical function, returns true if it supported
338 virtual bool SetLogicalFunction(int function
) ;
340 // returns the size of the graphics context in device coordinates
341 virtual void GetSize( wxDouble
* width
, wxDouble
* height
);
343 // returns the resolution of the graphics context in device points per inch
344 virtual void GetDPI( wxDouble
* dpiX
, wxDouble
* dpiY
);
347 // sets the current alpha on this context
348 virtual void SetAlpha( wxDouble alpha
);
350 // returns the alpha on this context
351 virtual wxDouble
GetAlpha() const;
354 // transformation : changes the current transformation matrix CTM of the context
358 virtual void Translate( wxDouble dx
, wxDouble dy
) = 0;
361 virtual void Scale( wxDouble xScale
, wxDouble yScale
) = 0;
364 virtual void Rotate( wxDouble angle
) = 0;
366 // concatenates this transform with the current transform of this context
367 virtual void ConcatTransform( const wxGraphicsMatrix
& matrix
) = 0;
369 // sets the transform of this context
370 virtual void SetTransform( const wxGraphicsMatrix
& matrix
) = 0;
372 // gets the matrix of this context
373 virtual wxGraphicsMatrix
GetTransform() const = 0;
379 virtual void SetPen( const wxGraphicsPen
& pen
);
381 void SetPen( const wxPen
& pen
);
383 // sets the brush for filling
384 virtual void SetBrush( const wxGraphicsBrush
& brush
);
386 void SetBrush( const wxBrush
& brush
);
389 virtual void SetFont( const wxGraphicsFont
& font
);
391 void SetFont( const wxFont
& font
, const wxColour
& colour
);
394 // strokes along a path with the current pen
395 virtual void StrokePath( const wxGraphicsPath
& path
) = 0;
397 // fills a path with the current brush
398 virtual void FillPath( const wxGraphicsPath
& path
, int fillStyle
= wxODDEVEN_RULE
) = 0;
400 // draws a path by first filling and then stroking
401 virtual void DrawPath( const wxGraphicsPath
& path
, int fillStyle
= wxODDEVEN_RULE
);
407 virtual void DrawText( const wxString
&str
, wxDouble x
, wxDouble y
) = 0;
409 virtual void DrawText( const wxString
&str
, wxDouble x
, wxDouble y
, wxDouble angle
);
411 virtual void DrawText( const wxString
&str
, wxDouble x
, wxDouble y
, const wxGraphicsBrush
& backgroundBrush
) ;
413 virtual void DrawText( const wxString
&str
, wxDouble x
, wxDouble y
, wxDouble angle
, const wxGraphicsBrush
& backgroundBrush
);
415 virtual void GetTextExtent( const wxString
&text
, wxDouble
*width
, wxDouble
*height
,
416 wxDouble
*descent
, wxDouble
*externalLeading
) const = 0;
418 virtual void GetPartialTextExtents(const wxString
& text
, wxArrayDouble
& widths
) const = 0;
424 virtual void DrawBitmap( const wxBitmap
&bmp
, wxDouble x
, wxDouble y
, wxDouble w
, wxDouble h
) = 0;
426 virtual void DrawIcon( const wxIcon
&icon
, wxDouble x
, wxDouble y
, wxDouble w
, wxDouble h
) = 0;
429 // convenience methods
432 // strokes a single line
433 virtual void StrokeLine( wxDouble x1
, wxDouble y1
, wxDouble x2
, wxDouble y2
);
435 // stroke lines connecting each of the points
436 virtual void StrokeLines( size_t n
, const wxPoint2DDouble
*points
);
438 // stroke disconnected lines from begin to end points
439 virtual void StrokeLines( size_t n
, const wxPoint2DDouble
*beginPoints
, const wxPoint2DDouble
*endPoints
);
442 virtual void DrawLines( size_t n
, const wxPoint2DDouble
*points
, int fillStyle
= wxODDEVEN_RULE
);
445 virtual void DrawRectangle( wxDouble x
, wxDouble y
, wxDouble w
, wxDouble h
);
448 virtual void DrawEllipse( wxDouble x
, wxDouble y
, wxDouble w
, wxDouble h
);
450 // draws a rounded rectangle
451 virtual void DrawRoundedRectangle( wxDouble x
, wxDouble y
, wxDouble w
, wxDouble h
, wxDouble radius
);
453 // wrappers using wxPoint2DDouble TODO
455 // helper to determine if a 0.5 offset should be applied for the drawing operation
456 virtual bool ShouldOffset() const { return false; }
461 wxGraphicsBrush m_brush
;
462 wxGraphicsFont m_font
;
463 int m_logicalFunction
;
466 DECLARE_NO_COPY_CLASS(wxGraphicsContext
)
467 DECLARE_ABSTRACT_CLASS(wxGraphicsContext
)
473 // A graphics figure allows to cache path, pen etc creations, also will be a basis for layering/grouping elements
476 class WXDLLIMPEXP_CORE wxGraphicsFigure
: public wxGraphicsObject
479 wxGraphicsFigure(wxGraphicsRenderer
* renderer
) ;
481 virtual ~wxGraphicsFigure() ;
483 void SetPath( wxGraphicsMatrix
* matrix
);
485 void SetMatrix( wxGraphicsPath
* path
);
487 // draws this object on the context
488 virtual void Draw( wxGraphicsContext
* cg
);
490 // returns the path of this object
491 wxGraphicsPath
* GetPath() { return m_path
; }
493 // returns the transformation matrix of this object, may be null if there is no transformation necessary
494 wxGraphicsMatrix
* GetMatrix() { return m_matrix
; }
497 wxGraphicsMatrix
* m_matrix
;
498 wxGraphicsPath
* m_path
;
500 DECLARE_DYNAMIC_CLASS(wxGraphicsFigure
)
506 // The graphics renderer is the instance corresponding to the rendering engine used, eg there is ONE core graphics renderer
507 // instance on OSX. This instance is pointed back to by all objects created by it. Therefore you can create eg additional
508 // paths at any point from a given matrix etc.
511 class WXDLLIMPEXP_CORE wxGraphicsRenderer
: public wxObject
514 wxGraphicsRenderer() {}
516 virtual ~wxGraphicsRenderer() {}
518 static wxGraphicsRenderer
* GetDefaultRenderer();
522 virtual wxGraphicsContext
* CreateContext( const wxWindowDC
& dc
) = 0 ;
523 virtual wxGraphicsContext
* CreateContext( const wxMemoryDC
& dc
) = 0 ;
525 virtual wxGraphicsContext
* CreateContextFromNativeContext( void * context
) = 0;
527 virtual wxGraphicsContext
* CreateContextFromNativeWindow( void * window
) = 0;
529 virtual wxGraphicsContext
* CreateContext( wxWindow
* window
) = 0;
531 // create a context that can be used for measuring texts only, no drawing allowed
532 virtual wxGraphicsContext
* CreateMeasuringContext() = 0;
536 virtual wxGraphicsPath
CreatePath() = 0;
540 virtual wxGraphicsMatrix
CreateMatrix( wxDouble a
=1.0, wxDouble b
=0.0, wxDouble c
=0.0, wxDouble d
=1.0,
541 wxDouble tx
=0.0, wxDouble ty
=0.0) = 0;
545 virtual wxGraphicsPen
CreatePen(const wxPen
& pen
) = 0 ;
547 virtual wxGraphicsBrush
CreateBrush(const wxBrush
& brush
) = 0 ;
549 // sets the brush to a linear gradient, starting at (x1,y1) with color c1 to (x2,y2) with color c2
550 virtual wxGraphicsBrush
CreateLinearGradientBrush( wxDouble x1
, wxDouble y1
, wxDouble x2
, wxDouble y2
,
551 const wxColour
&c1
, const wxColour
&c2
) = 0;
553 // sets the brush to a radial gradient originating at (xo,yc) with color oColor and ends on a circle around (xc,yc)
554 // with radius r and color cColor
555 virtual wxGraphicsBrush
CreateRadialGradientBrush( wxDouble xo
, wxDouble yo
, wxDouble xc
, wxDouble yc
, wxDouble radius
,
556 const wxColour
&oColor
, const wxColour
&cColor
) = 0;
559 virtual wxGraphicsFont
CreateFont( const wxFont
&font
, const wxColour
&col
= *wxBLACK
) = 0;
562 DECLARE_NO_COPY_CLASS(wxGraphicsRenderer
)
563 DECLARE_ABSTRACT_CLASS(wxGraphicsRenderer
)
568 #endif // _WX_GRAPHICS_H_