View source for Clip to PlotArea

[[category:OnGraphDraw annotations library functions]]
''New to [[Analytica 5.2]]''

Use this function when writing drawing code inside [[OnGraphDraw]] when you want your drawn content to clip to the plot area rectangle only.

== Clip_to_PlotArea( canv, info ) ==

This is a utility function that you might find useful when creating your own annotation code or functions for use in [[OnGraphDraw]]. 

Returns a drawing canvas clipped to the plot area of the graph. Called from [[OnGraphDraw]], where «canv» and «info» are the local values <code>canv</code> and <canv>info</canv> provided by the graphing engine to [[OnGraphDraw]].

== Library ==

To use this function ,you must add the '''''OnGraphDraw annotations.ana''''' library to your model.

:Use '''File &rarr; Add Library...''' to add this library.


== Examples ==

Given values x0 and y0, in data coordinates (i.e., x0 is in the coordinates of the variable depicted on the X-axis, y0 is in the coordinates of the variable depicted on the y-axis), and given a radius rx and ry, the following draws an ellipse centered at (x0, y0) with the radii (rx, ry):
<code>
:[[Local]] (x1,y1) := [[GraphToCanvasCoord]]( info, roles, x0-rx, y0-ry );
:[[Local]] (x2,y2) := [[GraphToCanvasCoord]]( info, roles, x0+rx, y0+ry );
:[[CanvasDrawEllipse]]( canv, x1, y1, width:x2-x1, height: y2-y1, fillColor:'LightBlue' )
</code>

The problem is that this drawn ellipse might extend outside the plot area, as seen here:
:[[image:Plot without clip.png|500px]]
In this screenshot, the ellipse was contained within the data's axes when both axes were autoscaled, but once zoomed (i.e., manually scaled), the ellipse extends beyond the depicted axis ranges.

Use the [[Clip_to_PlotArea]] function to limit your drawing to the rectangle contained within the axes. The above example is modified as follows.
<code>
:[[Local]] (x1,y1) := [[GraphToCanvasCoord]]( info, roles, x0-rx, y0-ry );
:[[Local]] (x2,y2) := [[GraphToCanvasCoord]]( info, roles, x0+rx, y0+ry );
:<span style="background-color:yellow">[[Local]] clip := [[Clip_to_PlotArea]](canv,info);</span>
:[[CanvasDrawEllipse]]( <span style="background-color:yellow">clip</span>, x1, y1, width:x2-x1, height: y2-y1, fillColor:'LightBlue' )
</code>

:[[image:Plot with clip.png|500px]]

== See Also ==
* [[OnGraphDraw]]
* [[Drawing images]]
* [[CanvasContext]]