|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--java.awt.Component | +--java.awt.Container | +--java.awt.Panel | +--ptolemy.plot.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 paint() has been called. To request that this be done, call repaint().
A small set of key bindings are provided for convenience. They are:
At this time, the two export commands produce encapsulated postscript tuned for black-and-white printers. In the future, more formats may supported. Also at this time (jdk 1.2), Java's interface the clipboard does not work, so Cntr-c might not accomplish anything. 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 Sun's 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: stringThese 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, maxThe 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.14159Tick 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: onThe 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: offIt can be turned back on with
Grid: onAlso, 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: offIt can be turned back on with
Color: onFinally, the rather specialized command
Wrap: onenables 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.1, and hence if used in an applet, it can only be viewed by a browser that supports JDK 1.1.
Inner Class Summary | |
class |
PlotBox.DragListener
|
class |
PlotBox.ZoomListener
|
Field Summary | |
protected java.awt.Color |
_background
|
protected int |
_bottomPadding
|
protected static java.awt.Color[] |
_colors
|
java.net.URL |
_documentBase
|
protected java.awt.Color |
_foreground
|
protected boolean |
_grid
|
protected int |
_height
|
protected int |
_leftPadding
|
protected static double |
_LOG10SCALE
|
protected int |
_lrx
|
protected int |
_lry
|
protected static double |
_PADDING
|
protected boolean |
_rangesGivenByZooming
|
protected int |
_rightPadding
|
protected int |
_topPadding
|
protected int |
_ulx
|
protected int |
_uly
|
protected boolean |
_usecolor
|
protected int |
_width
|
protected boolean |
_wrap
|
protected double |
_xBottom
|
protected double |
_xhighgiven
|
protected boolean |
_xlog
|
protected double |
_xlowgiven
|
protected double |
_xMax
|
protected double |
_xMin
|
protected boolean |
_xRangeGiven
|
protected double |
_xscale
|
protected double |
_xTop
|
protected double |
_yBottom
|
protected double |
_yhighgiven
|
protected boolean |
_ylog
|
protected double |
_ylowgiven
|
protected double |
_yMax
|
protected double |
_yMin
|
protected boolean |
_yRangeGiven
|
protected double |
_yscale
|
protected double |
_yTop
|
Fields inherited from class java.awt.Component |
BOTTOM_ALIGNMENT,
CENTER_ALIGNMENT,
LEFT_ALIGNMENT,
RIGHT_ALIGNMENT,
TOP_ALIGNMENT |
Constructor Summary | |
PlotBox()
Construct a plot box with a default configuration. |
Method Summary | |
protected void |
_drawPlot(java.awt.Graphics graphics,
boolean clearfirst)
Draw the axes using the current range, label, and title information. |
protected void |
_drawPoint(java.awt.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. |
protected void |
_help()
Display basic information in its own window. |
protected boolean |
_parseLine(java.lang.String line)
Parse a line that gives plotting information. |
protected void |
_setButtonsVisibility(boolean vis)
Deprecated. |
protected void |
_write(java.io.PrintWriter output)
Write plot information to the specified output stream in PlotML. |
protected void |
_writeOldSyntax(java.io.PrintWriter output)
Deprecated. |
void |
addLegend(int dataset,
java.lang.String legend)
Add a legend (displayed at the upper right) for the specified data set with the specified string. |
void |
addXTick(java.lang.String label,
double position)
Specify a tick mark for the X axis. |
void |
addYTick(java.lang.String label,
double position)
Specify a tick mark for the Y axis. |
void |
clear(boolean axes)
If the argument is true, clear the axes. |
void |
export(java.io.OutputStream out)
Export a description of the plot. |
void |
fillPlot()
Rescale so that the data that is currently plotted just fits. |
boolean |
getColor()
Return whether the plot uses color. |
static java.awt.Color |
getColorByName(java.lang.String name)
Convert a color name into a Color. |
java.lang.String |
getDataurl()
Deprecated. |
java.net.URL |
getDocumentBase()
Deprecated. |
boolean |
getGrid()
Return whether the grid is drawn. |
java.lang.String |
getLegend(int dataset)
Get the legend for a dataset, or null if there is none. |
java.awt.Dimension |
getMinimumSize()
Get the minimum size of this component. |
java.awt.Dimension |
getPreferredSize()
Get the preferred size of this component. |
java.lang.String |
getTitle()
Get the title of the graph, or an empty string if there is none. |
java.lang.String |
getXLabel()
Get the label for the X (horizontal) axis, or null if none has been set. |
boolean |
getXLog()
Return whether the X axis is drawn with a logarithmic scale. |
double[] |
getXRange()
Get the X range. |
java.util.Vector[] |
getXTicks()
Get the X ticks that have been specified, or null if none. |
java.lang.String |
getYLabel()
Get the label for the Y (vertical) axis, or null if none has been set. |
boolean |
getYLog()
Return whether the Y axis is drawn with a logarithmic scale. |
double[] |
getYRange()
Get the Y range. |
java.util.Vector[] |
getYTicks()
Get the Y ticks that have been specified, or null if none. |
void |
init()
Deprecated. |
void |
paint(java.awt.Graphics graphics)
Paint the component contents, which in this base class is only the axes. |
void |
parseFile(java.lang.String filespec)
Deprecated. |
void |
parseFile(java.lang.String filespec,
java.net.URL documentBase)
Deprecated. This method is deprecated. Use read() instead. |
void |
read(java.io.InputStream in)
Read commands and/or plot data from an input stream in the old (non-XML) file syntax. |
void |
read(java.lang.String command)
Read a single line command provided as a string. |
void |
samplePlot()
Do nothing in this base class. |
void |
setBackground(java.awt.Color background)
Set the background color. |
void |
setBounds(int x,
int y,
int width,
int height)
Move and resize this component. |
void |
setButtons(boolean visible)
If the argument is true, make a fill button visible at the upper right. |
void |
setColor(boolean useColor)
If the argument is false, draw the plot without using color (in black and white). |
void |
setDataurl(java.lang.String filespec)
Deprecated. |
void |
setDocumentBase(java.net.URL documentBase)
Deprecated. |
void |
setForeground(java.awt.Color foreground)
Set the foreground color. |
void |
setGrid(boolean grid)
Control whether the grid is drawn. |
void |
setLabelFont(java.lang.String name)
Set the label font, which is used for axis labels and legend labels. |
void |
setSize(int width,
int height)
Set the size of the plot. |
void |
setTitle(java.lang.String title)
Set the title of the graph. |
void |
setTitleFont(java.lang.String name)
Set the title font. |
void |
setWrap(boolean wrap)
Control whether the X axis is wrapped. |
void |
setXLabel(java.lang.String label)
Set the label for the X (horizontal) axis. |
void |
setXLog(boolean xlog)
Specify whether the X axis is drawn with a logarithmic scale. |
void |
setXRange(double min,
double max)
Set the X (horizontal) range of the plot. |
void |
setYLabel(java.lang.String label)
Set the label for the Y (vertical) axis. |
void |
setYLog(boolean ylog)
Specify whether the Y axis is drawn with a logarithmic scale. |
void |
setYRange(double min,
double max)
Set the Y (vertical) range of the plot. |
void |
update(java.awt.Graphics g)
Override update so that it doesn't clear the plot. |
void |
write(java.io.OutputStream out)
Write the current data and plot configuration to the specified stream in PlotML syntax. |
void |
write(java.io.OutputStream out,
java.lang.String dtd)
Write the current data and plot configuration to the specified stream in PlotML syntax. |
void |
writeOldSyntax(java.io.OutputStream out)
Deprecated. |
void |
zoom(double lowx,
double lowy,
double highx,
double highy)
Zoom in or out to the specified rectangle. |
Methods inherited from class java.awt.Panel |
addNotify |
Methods inherited from class java.awt.Container |
add,
add,
add,
add,
add,
addContainerListener,
addImpl,
countComponents,
deliverEvent,
doLayout,
findComponentAt,
findComponentAt,
getAlignmentX,
getAlignmentY,
getComponent,
getComponentAt,
getComponentAt,
getComponentCount,
getComponents,
getInsets,
getLayout,
getMaximumSize,
insets,
invalidate,
isAncestorOf,
layout,
list,
list,
locate,
minimumSize,
paintComponents,
paramString,
preferredSize,
print,
printComponents,
processContainerEvent,
processEvent,
remove,
remove,
removeAll,
removeContainerListener,
removeNotify,
setCursor,
setFont,
setLayout,
validate,
validateTree |
Methods inherited from class java.awt.Component |
action,
add,
addComponentListener,
addFocusListener,
addInputMethodListener,
addKeyListener,
addMouseListener,
addMouseMotionListener,
addPropertyChangeListener,
addPropertyChangeListener,
bounds,
checkImage,
checkImage,
coalesceEvents,
contains,
contains,
createImage,
createImage,
disable,
disableEvents,
dispatchEvent,
enable,
enable,
enableEvents,
enableInputMethods,
firePropertyChange,
getBackground,
getBounds,
getBounds,
getColorModel,
getComponentOrientation,
getCursor,
getDropTarget,
getFont,
getFontMetrics,
getForeground,
getGraphics,
getHeight,
getInputContext,
getInputMethodRequests,
getLocale,
getLocation,
getLocation,
getLocationOnScreen,
getName,
getParent,
getPeer,
getSize,
getSize,
getToolkit,
getTreeLock,
getWidth,
getX,
getY,
gotFocus,
handleEvent,
hasFocus,
hide,
imageUpdate,
inside,
isDisplayable,
isDoubleBuffered,
isEnabled,
isFocusTraversable,
isLightweight,
isOpaque,
isShowing,
isValid,
isVisible,
keyDown,
keyUp,
list,
list,
list,
location,
lostFocus,
mouseDown,
mouseDrag,
mouseEnter,
mouseExit,
mouseMove,
mouseUp,
move,
nextFocus,
paintAll,
postEvent,
prepareImage,
prepareImage,
printAll,
processComponentEvent,
processFocusEvent,
processInputMethodEvent,
processKeyEvent,
processMouseEvent,
processMouseMotionEvent,
remove,
removeComponentListener,
removeFocusListener,
removeInputMethodListener,
removeKeyListener,
removeMouseListener,
removeMouseMotionListener,
removePropertyChangeListener,
removePropertyChangeListener,
repaint,
repaint,
repaint,
repaint,
requestFocus,
reshape,
resize,
resize,
setBounds,
setComponentOrientation,
setDropTarget,
setEnabled,
setLocale,
setLocation,
setLocation,
setName,
setSize,
setVisible,
show,
show,
size,
toString,
transferFocus |
Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
wait,
wait,
wait |
Field Detail |
protected transient double _yMax
protected transient double _yMin
protected transient double _xMax
protected transient double _xMin
protected static final transient double _PADDING
protected transient boolean _xRangeGiven
protected transient boolean _yRangeGiven
protected transient boolean _rangesGivenByZooming
protected double _xlowgiven
protected double _xhighgiven
protected double _ylowgiven
protected double _yhighgiven
protected double _xBottom
protected double _xTop
protected double _yBottom
protected double _yTop
protected boolean _xlog
protected boolean _ylog
protected static final double _LOG10SCALE
protected boolean _grid
protected boolean _wrap
protected java.awt.Color _background
protected java.awt.Color _foreground
protected int _topPadding
protected int _bottomPadding
protected int _rightPadding
protected int _leftPadding
protected int _ulx
protected int _uly
protected int _lrx
protected int _lry
protected double _yscale
protected double _xscale
protected boolean _usecolor
protected static java.awt.Color[] _colors
protected int _width
protected int _height
public java.net.URL _documentBase
Constructor Detail |
public PlotBox()
Method Detail |
public void addLegend(int dataset, java.lang.String legend)
dataset
- The dataset index.legend
- The label for the dataset.public void addXTick(java.lang.String label, double position)
label
- The label for the tick mark.position
- The position on the X axis.public void addYTick(java.lang.String label, double position)
label
- The label for the tick mark.position
- The position on the Y axis.public void clear(boolean axes)
axes
- If true, clear the axes parameters.public void export(java.io.OutputStream out)
System.out
as an argument.file
- A file writer to which to send the description.public void fillPlot()
public boolean getColor()
public static java.awt.Color getColorByName(java.lang.String name)
name
- A color name, or null if not found.public java.lang.String getDataurl()
public java.net.URL getDocumentBase()
public boolean getGrid()
public java.lang.String getLegend(int dataset)
dataset
- The dataset index.public java.awt.Dimension getMinimumSize()
public java.awt.Dimension getPreferredSize()
public java.lang.String getTitle()
public java.lang.String getXLabel()
public boolean getXLog()
public double[] getXRange()
public java.util.Vector[] getXTicks()
public java.lang.String getYLabel()
public boolean getYLog()
public double[] getYRange()
public java.util.Vector[] getYTicks()
public void init()
public void paint(java.awt.Graphics graphics)
graphics
- The graphics context.public void parseFile(java.lang.String filespec)
public void parseFile(java.lang.String filespec, java.net.URL documentBase)
public void read(java.io.InputStream in) throws java.io.IOException
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));
in
- The input stream.public void read(java.lang.String command)
command
- A command.public void samplePlot()
public void setBackground(java.awt.Color background)
background
- The background color.public void setBounds(int x, int y, int width, int height)
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.public void setButtons(boolean visible)
public void setColor(boolean useColor)
useColor
- False to draw in back and white.public void setDataurl(java.lang.String filespec)
public void setDocumentBase(java.net.URL documentBase)
public void setForeground(java.awt.Color foreground)
foreground
- The foreground color.public void setGrid(boolean grid)
grid
- If true, a grid is drawn.public void setLabelFont(java.lang.String name)
name
- A font name.public void setSize(int width, int height)
width
- The width, in pixels.height
- The height, in pixels.public void setTitle(java.lang.String title)
title
- The title.public void setTitleFont(java.lang.String name)
name
- A font name.public void setWrap(boolean wrap)
wrap
- If true, wrapping of the X axis is enabled.public void setXLabel(java.lang.String label)
label
- The label.public void setXLog(boolean xlog)
xlog
- If true, logarithmic axis is used.public void setXRange(double min, double max)
min
- The left extent of the range.max
- The right extent of the range.public void setYLabel(java.lang.String label)
label
- The label.public void setYLog(boolean ylog)
ylog
- If true, logarithmic axis is used.public void setYRange(double min, double max)
min
- The bottom extent of the range.max
- The top extent of the range.public void update(java.awt.Graphics g)
public void write(java.io.OutputStream out)
out
- An output stream.public void write(java.io.OutputStream out, java.lang.String dtd)
out
- An output stream.dtd
- The reference (URL) for the DTD.public void writeOldSyntax(java.io.OutputStream out)
out
- An output stream.public void zoom(double lowx, double lowy, double highx, double highy)
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.protected void _drawPlot(java.awt.Graphics graphics, boolean clearfirst)
graphics
- The graphics context.clearfirst
- If true, clear the plot before proceeding.protected void _drawPoint(java.awt.Graphics graphics, int dataset, long xpos, long ypos, boolean clip)
true
, states
that the point should not be drawn if
it is out of range.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.protected void _help()
protected boolean _parseLine(java.lang.String line)
line
- A line of text.protected void _setButtonsVisibility(boolean vis)
protected void _write(java.io.PrintWriter output)
output
- A buffered print writer.protected void _writeOldSyntax(java.io.PrintWriter output)
output
- A buffered print writer.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |