Examples of PlotBox

This class provides a labeled box within which to place a data plot. A title, X and Y axis labels, tick marks, and a legend are all supported. Zooming in and out is supported. To zoom in, drag the mouse downwards to draw a box. To zoom out, drag the mouse upward.

The box can be configured either through a file with commands or through direct invocation of the public methods of the class.

When calling the methods, in most cases the changes will not be visible until paintComponent() has been called. To request that this be done, call repaint().

A small set of key bindings are provided for convenience. They are:

Cntrl-c: Export the plot to the clipboard (in PlotML).
D: Dump the plot to standard output (in PlotML).
E: Export the plot to standard output in EPS format.
F: Fill the plot.
H or ?: Display a simple help message.
Cntrl-D or Q: quit

These commands are provided in a menu by the PlotFrame class. Note that exporting to the clipboard is not allowed in applets (it used to be), so this will result in an error message.

At this time, the two export commands produce encapsulated postscript tuned for black-and-white printers. In the future, more formats may supported. Exporting to the clipboard and to standard output, in theory, is allowed for applets, unlike writing to a file. Thus, these key bindings provide a simple mechanism to obtain a high-resolution image of the plot from an applet, suitable for incorporation in a document. However, in some browsers, exporting to standard out triggers a security violation. You can use the JDK appletviewer instead.

To read commands from a file or URL, the preferred technique is to use one of the classes in the plotml package. That package supports both PlotML, an XML extension for plots, and a historical file format specific to ptplot. The historical file format is understood by the read() method in this class. The syntax of the historical format, documented below, is rudimentary, and will probably not be extended as ptplot evolves. Nonetheless, we document it here since it is directly supported by this class.

The historical format for the file allows any number commands, one per line. Unrecognized commands and commands with syntax errors are ignored. Comments are denoted by a line starting with a pound sign "#". The recognized commands include:

 TitleText: string XLabel: string YLabel: string

These commands provide a title and labels for the X (horizontal) and Y (vertical) axes. A string is simply a sequence of characters, possibly including spaces. There is no need here to surround them with quotation marks, and in fact, if you do, the quotation marks will be included in the labels.

The ranges of the X and Y axes can be optionally given by commands like:

 XRange: min, max YRange: min, max

The arguments min and max are numbers, possibly including a sign and a decimal point. If they are not specified, then the ranges are computed automatically from the data and padded slightly so that datapoints are not plotted on the axes.

The tick marks for the axes are usually computed automatically from the ranges. Every attempt is made to choose reasonable positions for the tick marks regardless of the data ranges (powers of ten multiplied by 1, 2, or 5 are used). However, they can also be specified explicitly using commands like:

 XTicks: label position, label position, ... YTicks: label position, label position, ...

A label is a string that must be surrounded by quotation marks if it contains any spaces. A position is a number giving the location of the tick mark along the axis. For example, a horizontal axis for a frequency domain plot might have tick marks as follows:

 XTicks: -PI -3.14159, -PI/2 -1.570795, 0 0, PI/2 1.570795, PI 3.14159

Tick marks could also denote years, months, days of the week, etc.

The X and Y axes can use a logarithmic scale with the following commands:

 XLog: on YLog: on

The grid labels represent powers of 10. Note that if a logarithmic scale is used, then the values must be positive. Non-positive values will be silently dropped. Note further that when using logarithmic axes that the log of input data is taken as the data is added to the plot. This means that

XLog: on

YLog: on

should appear before any data. Also, the value of the XTicks, YTicks, XRange or YRange directives should be in log units. So,

XTicks: 1K 3

will display the string

1K

at the 1000 mark.

By default, tick marks are connected by a light grey background grid. This grid can be turned off with the following command:

 Grid: off

It can be turned back on with

 Grid: on

Also, by default, the first ten data sets are shown each in a unique color. The use of color can be turned off with the command:

 Color: off

It can be turned back on with

 Color: on

Finally, the rather specialized command

 Wrap: on

enables wrapping of the X (horizontal) axis, which means that if a point is added with X out of range, its X value will be modified modulo the range so that it lies in range. This command only has an effect if the X range has been set explicitly. It is designed specifically to support oscilloscope-like behavior, where the X value of points is increasing, but the display wraps it around to left. A point that lands on the right edge of the X range is repeated on the left edge to give a better sense of continuity. The feature works best when points do land precisely on the edge, and are plotted from left to right, increasing in X.

All of the above commands can also be invoked directly by calling the the corresponding public methods from some Java procedure.

This class uses features of JDK 1.2, and hence if used in an applet, it can only be viewed by a browser that supports JDK 1.2, or a plugin. @author Edward A. Lee, Christopher Brooks, Contributors: Jun Wu (jwu@inin.com.au), William Wu, Robert Kroeger @version $Id: PlotBox.java,v 1.283.4.3 2008/04/01 01:19:02 cxh Exp $ @since Ptolemy II 0.2 @Pt.ProposedRating Yellow (cxh) @Pt.AcceptedRating Yellow (cxh)

Examples of ptolemy.plot.PlotBox