All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class ptolemy.plot.PlotBox

java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----java.awt.Panel
                           |
                           +----ptolemy.plot.PlotBox

public class PlotBox
extends Panel
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. Use the read() method to read a URL or a file.

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

The ASCII 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.

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
 
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.1, and hence if used in an applet, it can only be viewed by a browser that supports JDK 1.1.

Version:
$Id: PlotBox.java,v 1.116 1998/11/23 17:58:37 cxh Exp $
Author:
Edward A. Lee, Christopher Hylands

Variable Index

 o _background
 o _bottomPadding
 o _colors
 o _documentBase
 o _foreground
 o _grid
 o _height
 o _leftPadding
 o _LOG10SCALE
 o _lrx
 o _lry
 o _PADDING
 o _rightPadding
 o _topPadding
 o _ulx
 o _uly
 o _usecolor
 o _width
 o _xBottom
 o _xlog
 o _xMax
 o _xMin
 o _xRangeGiven
 o _xscale
 o _xTop
 o _yBottom
 o _ylog
 o _yMax
 o _yMin
 o _yRangeGiven
 o _yscale
 o _yTop

Constructor Index

 o PlotBox()

Method Index

 o _drawPlot(Graphics, boolean)
Draw the axes using the current range, label, and title information.
 o _drawPoint(Graphics, int, long, long, boolean)
Put a mark corresponding to the specified dataset at the specified x and y position.
 o _parseLine(String)
Parse a line that gives plotting information.
 o _setButtonsVisibility(boolean)
Set the visibility of the Fill button. Deprecated.
 o _write(PrintWriter)
Write plot information to the specified output stream.
 o _zoom(int, int)
 o _zoomBox(int, int)
 o _zoomStart(int, int)
 o addLegend(int, String)
Add a legend (displayed at the upper right) for the specified data set with the specified string.
 o addXTick(String, double)
Specify a tick mark for the X axis.
 o addYTick(String, double)
Specify a tick mark for the Y axis.
 o clear(boolean)
If the argument is true, clear the axes.
 o fillPlot()
Rescale so that the data that is currently plotted just fits.
 o getColorByName(String)
Convert a color name into a Color.
 o getDataurl()
Get the file specification that was given by setDataurl. Deprecated.
 o getDocumentBase()
Get the document base that was set by setDocumentBase. Deprecated.
 o getLegend(int)
Get the legend for a dataset, or null if there is none.
 o getMinimumSize()
Get the minimum size of this component.
 o getPreferredSize()
Get the preferred size of this component.
 o init()
Initialize the component, creating the fill button and parsing an input file, if one has been specified. Deprecated.
 o paint(Graphics)
Paint the component contents, which in this base class is only the axes.
 o parseFile(String)
Syntactic sugar for parseFile(filespec, documentBase). Deprecated.
 o parseFile(String, URL)
Open up the input file, which could be stdin, a URL, or a file. Deprecated.
 o read(InputStream)
Read commands and/or plot data from an input stream.
 o setBackground(Color)
Set the background color.
 o setBinary(boolean)
Set the binary flag to true if we are reading pxgraph format binary data. Deprecated.
 o setBounds(int, int, int, int)
Move and resize this component.
 o setButtons(boolean)
If the argument is true, make a fill button visible at the upper right.
 o setDataurl(String)
Set the file to read when init() is called. Deprecated.
 o setDocumentBase(URL)
Set the document base to used when init() is called to read a URL. Deprecated.
 o setForeground(Color)
Set the foreground color.
 o setGrid(boolean)
Control whether the grid is drawn.
 o setLabelFont(String)
Set the label font, which is used for axis labels and legend labels.
 o setSize(int, int)
Set the size of the plot.
 o setTitle(String)
Set the title of the graph.
 o setTitleFont(String)
Set the title font.
 o setXLabel(String)
Set the label for the X (horizontal) axis.
 o setXLog(boolean)
Specify whether the X axis is drawn with a logarithmic scale.
 o setXRange(double, double)
Set the X (horizontal) range of the plot.
 o setYLabel(String)
Set the label for the Y (vertical) axis.
 o setYLog(boolean)
Specify whether the Y axis is drawn with a logarithmic scale.
 o setYRange(double, double)
Set the Y (vertical) range of the plot.
 o write(OutputStream)
Write the current data and plot configuration to the specified stream.
 o zoom(double, double, double, double)
Zoom in or out to the specified rectangle.

Variables

 o _yMax
 protected transient double _yMax
 o _yMin
 protected transient double _yMin
 o _xMax
 protected transient double _xMax
 o _xMin
 protected transient double _xMin
 o _PADDING
 protected static final transient double _PADDING
 o _xRangeGiven
 protected transient boolean _xRangeGiven
 o _yRangeGiven
 protected transient boolean _yRangeGiven
 o _xBottom
 protected double _xBottom
 o _xTop
 protected double _xTop
 o _yBottom
 protected double _yBottom
 o _yTop
 protected double _yTop
 o _xlog
 protected boolean _xlog
 o _ylog
 protected boolean _ylog
 o _LOG10SCALE
 protected static final double _LOG10SCALE
 o _grid
 protected boolean _grid
 o _background
 protected Color _background
 o _foreground
 protected Color _foreground
 o _topPadding
 protected int _topPadding
 o _bottomPadding
 protected int _bottomPadding
 o _rightPadding
 protected int _rightPadding
 o _leftPadding
 protected int _leftPadding
 o _ulx
 protected int _ulx
 o _uly
 protected int _uly
 o _lrx
 protected int _lrx
 o _lry
 protected int _lry
 o _yscale
 protected double _yscale
 o _xscale
 protected double _xscale
 o _usecolor
 protected boolean _usecolor
 o _colors
 protected static Color _colors[]
 o _width
 protected int _width
 o _height
 protected int _height
 o _documentBase
 protected URL _documentBase

Constructors

 o PlotBox
 public PlotBox()

Methods

 o addLegend
 public void addLegend(int dataset,
                       String legend)
Add a legend (displayed at the upper right) for the specified data set with the specified string. Short strings generally fit better than long strings.

Parameters:
dataset - The dataset index.
legend - The label for the dataset.
 o addXTick
 public void addXTick(String label,
                      double position)
Specify a tick mark for the X axis. The label given is placed on the axis at the position given by position. If this is called once or more, automatic generation of tick marks is disabled. The tick mark will appear only if it is within the X range.

Parameters:
label - The label for the tick mark.
position - The position on the X axis.
 o addYTick
 public void addYTick(String label,
                      double position)
Specify a tick mark for the Y axis. The label given is placed on the axis at the position given by position. If this is called once or more, automatic generation of tick marks is disabled. The tick mark will appear only if it is within the Y range.

Parameters:
label - The label for the tick mark.
position - The position on the Y axis.
 o clear
 public synchronized void clear(boolean axes)
If the argument is true, clear the axes. I.e., set all parameters controlling the axes to their initial conditions. For the change to take effect, call repaint(). If the argument is false, do nothing.

Parameters:
axes - If true, clear the axes parameters.
 o fillPlot
 public synchronized void fillPlot()
Rescale so that the data that is currently plotted just fits. This is done based on the protected variables _xBottom, _xTop, _yBottom, and _yTop. It is up to derived classes to ensure that variables are valid. This method calls repaint(), which eventually causes the display to be updated.

 o getColorByName
 public static Color getColorByName(String name)
Convert a color name into a Color. Currently, only a very limited set of color names is supported: black, white, red, green, and blue.

Parameters:
name - A color name, or null if not found.
Returns:
An instance of Color.
 o getDataurl
 public String getDataurl()
Note: getDataurl() is deprecated.

Get the file specification that was given by setDataurl. This method is deprecated. Use read() instead.

 o getDocumentBase
 public URL getDocumentBase()
Note: getDocumentBase() is deprecated.

Get the document base that was set by setDocumentBase. This method is deprecated. Use read() instead.

 o getLegend
 public String getLegend(int dataset)
Get the legend for a dataset, or null if there is none. The legend would have been set by addLegend().

Parameters:
dataset - The dataset index.
Returns:
The legend label, or null if there is none.
 o getMinimumSize
 public Dimension getMinimumSize()
Get the minimum size of this component. This is simply the dimensions specified by setBounds() or setSize().

Returns:
The minimum size.
Overrides:
getMinimumSize in class Container
 o getPreferredSize
 public Dimension getPreferredSize()
Get the preferred size of this component. This is simply the dimensions specified by setBounds() or setSize().

Returns:
The preferred size.
Overrides:
getPreferredSize in class Container
 o init
 public void init()
Note: init() is deprecated.

Initialize the component, creating the fill button and parsing an input file, if one has been specified. This is deprecated. Call setButtons() and read() instead.

 o paint
 public void paint(Graphics graphics)
Paint the component contents, which in this base class is only the axes.

Parameters:
graphics - The graphics context.
Overrides:
paint in class Container
 o parseFile
 public void parseFile(String filespec)
Note: parseFile() is deprecated.

Syntactic sugar for parseFile(filespec, documentBase). This method is deprecated. Use read(). Note that this method no longer supports pxgraph binary files. Use readPxgraph() in the derived class Plot instead.

 o parseFile
 public void parseFile(String filespec,
                       URL documentBase)
Note: parseFile() is deprecated.

Open up the input file, which could be stdin, a URL, or a file. This method is deprecated. Use read() instead.

 o read
 public void read(InputStream in) throws IOException
Read commands and/or plot data from an input stream. To update the display, call repaint(), or make the plot visible with setVisible(true).

To read from standard input, use:

     read(System.in);
  
To read from a url, use:
     read(url.openStream());
  
To read a URL from within an applet, use:
     URL url = new URL(getDocumentBase(), urlSpec);
     read(url.openStream());
  
Within an application, if you have an absolute URL, use:
     URL url = new URL(urlSpec);
     read(url.openStream());
  
To read from a file, use:
     read(new FileInputStream(filename));
  
The input stream currently must be in ASCII format, although a binary format will be supported eventually.

Parameters:
in - The input stream.
 o setBounds
 public void setBounds(int x,
                       int y,
                       int width,
                       int height)
Move and resize this component. The new location of the top-left corner is specified by x and y, and the new size is specified by width and height. This overrides the base class method to make a record of the new size.

Parameters:
x - The new x-coordinate of this component.
y - The new y-coordinate of this component.
width - The new width of this component.
height - The new height of this component.
Overrides:
setBounds in class Component
 o setButtons
 public void setButtons(boolean visible)
If the argument is true, make a fill button visible at the upper right. This button auto-scales the plot. NOTE: The button may infringe on the title space, if the title is long. In an application, it is preferable to provide a menu with the fill command. This way, when printing the plot, the printed plot will not have a spurious button. Thus, this method should be used only by applets, which normally do not have menus.

 o setSize
 public void setSize(int width,
                     int height)
Set the size of the plot.

Parameters:
width - The width, in pixels.
height - The height, in pixels.
Overrides:
setSize in class Component
 o setBackground
 public void setBackground(Color background)
Set the background color.

Parameters:
background - The background color.
Overrides:
setBackground in class Component
 o setForeground
 public void setForeground(Color foreground)
Set the foreground color.

Parameters:
foreground - The foreground color.
Overrides:
setForeground in class Component
 o setBinary
 public void setBinary(boolean binary)
Note: setBinary() is deprecated.

Set the binary flag to true if we are reading pxgraph format binary data. This method is deprecated. Use read() instead, which recognizes binary files. To read pxgraph binary files, use readPxgraph() in the derived class Plot.

 o setDataurl
 public void setDataurl(String filespec)
Note: setDataurl() is deprecated.

Set the file to read when init() is called. This method is deprecated. Use read() instead.

 o setDocumentBase
 public void setDocumentBase(URL documentBase)
Note: setDocumentBase() is deprecated.

Set the document base to used when init() is called to read a URL. This method is deprecated. Use read() instead.

 o setGrid
 public void setGrid(boolean grid)
Control whether the grid is drawn.

Parameters:
grid - If true, a grid is drawn.
 o setLabelFont
 public void setLabelFont(String name)
Set the label font, which is used for axis labels and legend labels. The font names understood are those understood by java.awt.Font.decode().

Parameters:
name - A font name.
 o setTitle
 public void setTitle(String title)
Set the title of the graph.

Parameters:
title - The title.
 o setTitleFont
 public void setTitleFont(String name)
Set the title font. The font names understood are those understood by java.awt.Font.decode().

Parameters:
name - A font name.
 o setXLabel
 public void setXLabel(String label)
Set the label for the X (horizontal) axis.

Parameters:
label - The label.
 o setXLog
 public void setXLog(boolean xlog)
Specify whether the X axis is drawn with a logarithmic scale.

Parameters:
xlog - If true, logarithmic axis is used.
 o setXRange
 public void setXRange(double min,
                       double max)
Set the X (horizontal) range of the plot. If this is not done explicitly, then the range is computed automatically from data available when the plot is drawn. If min and max are identical, then the range is arbitrarily spread by 1.

Parameters:
min - The left extent of the range.
max - The right extent of the range.
 o setYLabel
 public void setYLabel(String label)
Set the label for the Y (vertical) axis.

Parameters:
label - The label.
 o setYLog
 public void setYLog(boolean ylog)
Specify whether the Y axis is drawn with a logarithmic scale.

Parameters:
ylog - If true, logarithmic axis is used.
 o setYRange
 public void setYRange(double min,
                       double max)
Set the Y (vertical) range of the plot. If this is not done explicitly, then the range is computed automatically from data available when the plot is drawn. If min and max are identical, then the range is arbitrarily spread by 0.1.

Parameters:
min - The bottom extent of the range.
max - The top extent of the range.
 o write
 public void write(OutputStream out)
Write the current data and plot configuration to the specified stream. The output is buffered, and is flushed and closed before exiting. Derived classes should override _write() rather than this method.

Parameters:
out - An output stream.
 o zoom
 public synchronized void zoom(double lowx,
                               double lowy,
                               double highx,
                               double highy)
Zoom in or out to the specified rectangle. This method calls repaint().

Parameters:
lowx - The low end of the new X range.
lowy - The low end of the new Y range.
highx - The high end of the new X range.
highy - The high end of the new Y range.
 o _drawPlot
 protected synchronized void _drawPlot(Graphics graphics,
                                       boolean clearfirst)
Draw the axes using the current range, label, and title information. If the second argument is true, clear the display before redrawing. This method is called by paint(). To cause it to be called you would normally call repaint(), which eventually causes paint() to be called.

Parameters:
graphics - The graphics context.
clearfirst - If true, clear the plot before proceeding.
 o _drawPoint
 protected void _drawPoint(Graphics graphics,
                           int dataset,
                           long xpos,
                           long ypos,
                           boolean clip)
Put a mark corresponding to the specified dataset at the specified x and y position. The mark is drawn in the current color. In this base class, a point is a filled rectangle 6 pixels across. Note that marks greater than about 6 pixels in size will not look very good since they will overlap axis labels and may not fit well in the legend. The clip argument, if true, states that the point should not be drawn if it is out of range.

Parameters:
graphics - The graphics context.
dataset - The index of the data set.
xpos - The X position.
ypos - The Y position.
clip - If true, do not draw if out of range.
 o _parseLine
 protected boolean _parseLine(String line)
Parse a line that gives plotting information. In this base class, only lines pertaining to the title and labels are processed. Everything else is ignored. Return true if the line is recognized.

Parameters:
line - A line of text.
 o _setButtonsVisibility
 protected void _setButtonsVisibility(boolean vis)
Note: _setButtonsVisibility() is deprecated.

Set the visibility of the Fill button. This is deprecated. Use setButtons().

 o _write
 protected void _write(PrintWriter output)
Write plot information to the specified output stream. Derived classes should override this method to first call the parent class method, then add whatever additional information they wish to add to the stream.

Parameters:
output - A buffered print writer.
 o _zoom
 public synchronized void _zoom(int x,
                                int y)
 o _zoomBox
 public synchronized void _zoomBox(int x,
                                   int y)
 o _zoomStart
 public synchronized void _zoomStart(int x,
                                     int y)

All Packages  Class Hierarchy  This Package  Previous  Next  Index