plotcontainer

Name

plotcontainer -- Plotchart XY plot wrapper

Synopsis

package require Plotchart::xyplotContainer

set container Plotchart::xyPlotContainer name | %AUTO% -canvas widget ?option...?

$container methodname ...

DESCRIPTION

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.

OPTIONS

-xmin floating-value

Sets 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-value

Sets 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-value

Sets the Y axis minimum value. Data below this value will be clipped from the plot. Setting this value schedules a plot regeneration.

-ymax floating-value

Sets 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-command

Provides 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-text

Modifies 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-text

Modifies 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-text

Modifies 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 boolean

Determines 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 boolean

Enables or disables the display of a grid on the plot. By default this is disabled.

-plotid

This 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.

-canvas

At 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.

METHODS

The Plotchart::xycontainer snit::type has several methods. These break down into the following categories:

Plot methods

worldToCanvas x y

Plots 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.

getPlotLimits

Returns 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.

Series methods

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.

getSeries

Returns 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.

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.

Marker methods

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.

deleteAllMarkers

Destroys all markers. The plot will no longer have any markers displayed.

markers

Returns 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.