package require Plotchart::xyplotContainer
set container Plotchart::xyPlotContainer name | %AUTO% -canvas widget ?option...?
$container methodname ...
Plotchart is a pure Tcl package that provides support for a powerful set of plotting primitives. Plotchart itself is documented at Activestate at: http://docs.activestate.com/activetcl/8.5/tklib/plotchart/plotchart.html .
Plotchart was not initially intended for interactive, or dynamic graphics, however the author has recently added and improved support for these capabilities. Nonetheless, there are operations which require plots to be generated from scratch. The Plotchart::xyPlotContainer snit::type encapsulates a number of the Plotchart plot types in a wrapper that knows when and how to regenerate a plot and when not to.
Plotchart::xyPlotContainer requires that the
plot it encapsulates be one of the plot types that supports plotcharts
xyplot methods. By default, the container
encapsulates an xyplot but the -plottype option can be
used to modify the plot created and encapsulated by the container.
Note as well that since often a series of method calls and option modifications will all require plot regeneration, the actual regeneration is scheduled in order to perform the needed regeneration only once.
-xmin floating-valueSets the X axis minimum value. This will schedule a plot regeneration. Data to the left of this value will be clipped from the plot.
-xmax floating-valueSets the X axis maximum value. This will schedule a plot regeneration. Data to the right of this value will be clipped fromt he plot.
-ymin floating-valueSets the Y axis minimum value. Data below this value will be clipped from the plot. Setting this value schedules a plot regeneration.
-ymax floating-valueSets the Y axis maximum value. Data above this value are clipped from the plot. Setting this value schedules a plot regeneration.
-plottype plot-creation-base-commandProvides the command keyword used to create a new plot. This defaults to ::Plotchart::creteXYPlot Modifying this option value will schedule a plot regeneration.
-title title-textModifies the title text for the plot. The defafult text is an empty string, indicating you do not wish to display a title on the plot.
-xtitle title-textModifies the X-axis title text for the plot. The default text is the empty string, indicating you do not wish to display a title on the plot.
-ytitle title-textModifies the default Y axis title text for the plot. The default text is the empty string, which indicates that you do not want to display a Y axis title. Since the display of rotated text on canvases is not supported in Tk 8.5, the text is displayed at the top of the Y axis.
-showkey booleanDetermines if the plot key should be displayed. The plot key shows the correspondence between colors and series names. By default this option is true
-grid booleanEnables or disables the display of a grid on the plot. By default this is disabled.
-plotidThis is a readonly option which returns the id of the plot. The id of a plot is the plotchart base command for performing raw method calls on the plot as documented in the Plotchart manpage.
-canvasAt construction time this option is required and provides the canvas on which the plot is drawn. After construction, this option is readonly and will return that canvas.
The Plotchart::xycontainer
snit::type has several methods. These
break down into the following categories:
Plot functions - functions that affect the plot as a whole
Series functions - functions that manipulate data series.
Marker management - functions that manipulate plot markers.
worldToCanvas x yPlots live in a canvas and impose a world coordinate system on an underlying Tk canvas. Sometimes it's useful to be able to draw something on the underlying canvas that has some relationship to the plot.
This method takes a point defined by x
and y in plot (world) coordinates
and converts it into a position on the underlying canvas.
The method returns a two element list whose values are
in order the corresponding x and y coordinates on the
canvas.
It is not an error to request world coordinates taht are outside the limits of the canvas.
canvasToWorld x y
See worldToCanvas above for the
background discussion. This method transforms a
point on the canvas defined by
x and y
into the corresponding coordinate on the canvas.
This can be used, for example, to relate the
coordinates of an event to the plot.
The return value is a two element list containing the in order the x and y world coordinates corresponding to the parameters.
resize width height
Resizes the canvas containing the plot and schedules a
regeneration of the plot to fit properly in the new
size of the canvas. The new dimensions of the
canvas are in pixels and given by
width and
height.
getPlotLimitsReturns a list containing the current world coordinate plotting limits. The elements in order are the minimum X, the maximum X, the minimum Y and the maximum Y coordinates.
Data plotted on a Plotchart plot are organized as series. A series
is comprised of a name, a set of points to draw and a color in which
to draw them. If you do not want to use the default drawing method
for a series, you can obtain the plot id and use the
Plotchart dataconfig method to reconfigure
how a series is displayed.
series name xcoords ycoords color
Creates or modifies a series. name
is the name of the series. If a series by this name
does not yet exist it is created.
xcoords and ycoords
are the coordinates of the points in the series.
color is the color in which
the series is drawn. color
is optional and defaults to black.
Colors can be described using any of the
valid color descriptions of Tk.
Valid color descriptions are either named colors as listed in http://www.tcl.tk/man/tcl8.5/TkCmd/colors.htm , or RGB triplets of the form #rrggbb where e.g. rr is a hexadecimal red color intensity from 00 to ff. For example, the HotPink named color can also be specified as #ff69b4
deleteSeries name
Destroys the series name and
removes it from the plot. Note that to move the
data in a series it is only necessary to invoke
series.
getSeriesReturns a Tcl list containing the names of the currently known series.
getSeriesColor name
Returns the color specification for the series
name as it was most recently
supplied. Thus if the series was specified
with a color of HotPink that
string is returned. If, on the other hand, it was
specified as #ff69b4 that
string is returned.
The intent of this function is to allow you to draw other canvas elements in colors that match the color of a series.
setSeriesPointLimit name n
Sets a limit on the number of points that will be allowed for a series.
This is most useful in strip charts. When the number of points in a
series exceeds this limit, the series will be trimmed.
name specifies the series name and
n is the number of points a series can have.
The default for n if this method is not
called to override it is 2000000
When a series is to be trimmed, every other point in the oldest 25% of the points is discarded. In this way, a sense for the entire history of the data is retained, however at lower resolution for older data.
getSeriesMinMax left right
For all series in a plot returns information about
the minimum and maximum values of the the series
within the world coordinate X positions given by
left and right.
The intent of this is to allow you to determine new
reasonable scales after an expansion in X is done as
a result of e.g. a mouse event.
The method returns a dict with the following keys:
series - A list of series names.
mins - A list of the series Y coordinate minima in the range in order corresponding to the list of series names above.
maxes - A list of the series Y coordinate minima in order correspnding to the list of series names above.
xmax - list of X coordinates at which the maxes occur.
xmin - list of X coordinates at which the mins occur.
addSeriesPoint name x y
Adds a new point defined by the
x and y
coordinates to the series named name.
Note that no effort is made to sort series points by
X coordinates so, depending on what you are trying to
plot you may not get what you want if the points are
not added monotonically in X.
clearSeries name
Removes all data points from the
series name.
Markers are isoceles filled triangles that can be drawn, and moved on the plot in world coordinates. Markers have a name, a facing (for the 'point' of the triangle) and a coordinate of the 'pont' of the triangle. The methods below manipulate the markers that are drawn on the plot.
Markers are intended to provide a mechanism to highlight features of the plot. Marker modification never requires a plot regeneration as they are simply canvas items. Regeneration of the plot also regenerates the markers at their last known world coordinates.
marker name x y faces color
If the marker name does not
yet exist, it is created and drawn as described.
If the marker does exist, then it is redrawn as described.
x and y
are the world coordinates of the point fo the marker.
faces determines which direction
the maker points and can be one of the strings:
up, down,
left or right.
color determines the color in
which the marker is drawn (the outline and fill color).
See the series command
for information about how to specify colors.
markerMove name newx newy
Changes only the location of the point of the marker
name to the world coordinates
specified by newx and newy.
deleteMarker name
Destroys the marker name.
name is no longer drawn on the
plot.
deleteAllMarkersDestroys all markers. The plot will no longer have any markers displayed.
markersReturns a list of dicts, one for each defined marker. Each dict has the keys:
name - The name of a marker.
marker - The marker object. See marker for more information about the marker object and what it can do.