Package ptolemy.plot
Interface PlotBoxInterface
-
- All Known Subinterfaces:
PlotInterface
- All Known Implementing Classes:
EditablePlot
,Histogram
,Plot
,PlotBox
,PlotLive
,PlotLiveDemo
public interface PlotBoxInterface
Definitions for an object that contains a plotter.- Since:
- Ptolemy II 10.0
- Version:
- $Id$
- Author:
- ahuseyno
- Pt.AcceptedRating:
- Red (cxh)
- Pt.ProposedRating:
- Red (cxh)
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description void
addCaptionLine(java.lang.String captionLine)
Add a line to the caption (displayed at below graph) .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
clearCaptions()
Clear all the captions.void
clearLegends()
Clear all legends.void
deferIfNecessary(java.lang.Runnable action)
If this method is called in the event thread, then simply execute the specified action.void
destroy()
Destroy the plotter.void
fillPlot()
Rescale so that the data that is currently plotted just fits.java.util.Vector
getCaptions()
Get the captions.boolean
getColor()
Return whether the plot uses color.java.lang.Object[]
getColors()
Get the point colors.java.lang.String
getDataurl()
Deprecated.Use read() instead.java.net.URL
getDocumentBase()
Deprecated.Use read() instead.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.int
getLegendDataset(java.lang.String legend)
Given a legend string, return the corresponding dataset or -1 if no legend was added with that legend string The legend would have been set by addLegend().java.lang.Object
getPlotRectangle()
Get the current plot rectangle.java.lang.String
getTitle()
Get the title of the graph, or an empty string if there is none.double[]
getXAutoRange()
Get the range for X values of the data points registered so far.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.double[]
getYAutoRange()
Get the range for Y values of the data points registered so far.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
parseFile(java.lang.String filespec)
Deprecated.Use read() to read the old file format, or use one of the classes in the plotml package to read the XML-based file format.void
parseFile(java.lang.String filespec, java.net.URL documentBase)
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
removeLegend(int dataset)
Remove the legend (displayed at the upper right) for the specified data set.void
renameLegend(int dataset, java.lang.String newName)
Rename a legend.void
repaint()
Repaint the object.void
resetAxes()
Reset the X and Y axes to the ranges that were first specified using setXRange() and setYRange().void
samplePlot()
Do nothing in this base class.void
setAutomaticRescale(boolean automaticRescale)
Set automatic rescale.void
setBackground(java.lang.Object background)
Set the background color.void
setButtons(boolean visible)
If the argument is true, make a fill button visible at the upper right.void
setCaptions(java.util.Vector captionStrings)
Set the strings of the caption.void
setColor(boolean useColor)
If the argument is false, draw the plot without using color (in black and white).void
setColors(java.lang.Object[] colors)
Set the point colors.void
setDataurl(java.lang.String filespec)
Deprecated.Use read() instead.void
setDocumentBase(java.net.URL documentBase)
Deprecated.Use read() instead.void
setForeground(java.lang.Object 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
setPlotRectangle(java.lang.Object rectangle)
Set the plot rectangle inside the axes.void
setSize(int width, int height)
Set the size of the plot.void
setTimedRepaint(boolean timedRepaint)
Set repainting with a certain fixed refresh rate.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)
Specify 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
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
write(java.io.Writer out, java.lang.String dtd)
Write the current data and plot configuration to the specified stream in PlotML syntax.void
writeData(java.io.PrintWriter output)
Write plot data information to the specified output stream in PlotML.void
writeFormat(java.io.PrintWriter output)
Write plot format information to the specified output stream in PlotML.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.
-
-
-
Method Detail
-
addCaptionLine
void addCaptionLine(java.lang.String captionLine)
Add a line to the caption (displayed at below graph) .- Parameters:
captionLine
- The string to be added.- See Also:
getCaptions()
-
addLegend
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. Short strings generally fit better than long strings. If the string is empty, or the argument is null, then no legend is added.- Parameters:
dataset
- The dataset index.legend
- The label for the dataset.- See Also:
renameLegend(int, String)
-
addXTick
void addXTick(java.lang.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.Note that if
setXLog(boolean)
has been called, then the position value should be in log units. So, addXTick("1K", 3) will display the string1K
at the 1000 mark.- Parameters:
label
- The label for the tick mark.position
- The position on the X axis.
-
addYTick
void addYTick(java.lang.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.Note that if
setYLog(boolean)
has been called, then the position value should be in log units. So, addYTick("1K", 3) will display the string1K
at the 1000 mark.- Parameters:
label
- The label for the tick mark.position
- The position on the Y axis.
-
clear
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.
-
clearCaptions
void clearCaptions()
Clear all the captions. For the change to take effect, call repaint().- See Also:
setCaptions(Vector)
-
clearLegends
void clearLegends()
Clear all legends. This will show up on the next redraw.
-
deferIfNecessary
void deferIfNecessary(java.lang.Runnable action)
If this method is called in the event thread, then simply execute the specified action. Otherwise, if there are already deferred actions, then add the specified one to the list. Otherwise, create a list of deferred actions, if necessary, and request that the list be processed in the event dispatch thread. Note that it does not work nearly as well to simply schedule the action yourself on the event thread because if there are a large number of actions, then the event thread will not be able to keep up. By grouping these actions, we avoid this problem. This method is not , so the caller should be.- Parameters:
action
- The Runnable object to execute.
-
destroy
void destroy()
Destroy the plotter. This method is usually called by PlotApplet.destroy(). It does various cleanups to reduce memory usage.
-
fillPlot
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.
-
getCaptions
java.util.Vector getCaptions()
Get the captions.- Returns:
- the captions
- See Also:
addCaptionLine(String)
,setCaptions(Vector)
-
getColor
boolean getColor()
Return whether the plot uses color.- Returns:
- True if the plot uses color.
- See Also:
setColor(boolean)
-
getColors
java.lang.Object[] getColors()
Get the point colors.- Returns:
- Array of colors
- See Also:
setColors(Object[])
-
getDataurl
@Deprecated java.lang.String getDataurl()
Deprecated.Use read() instead.Get the file specification that was given by setDataurl().- Returns:
- the file specification
- See Also:
setDataurl(String)
-
getDocumentBase
@Deprecated java.net.URL getDocumentBase()
Deprecated.Use read() instead.Get the document base that was set by setDocumentBase().- Returns:
- the document base.
- See Also:
setDocumentBase(URL)
-
getGrid
boolean getGrid()
Return whether the grid is drawn.- Returns:
- True if a grid is drawn.
- See Also:
setGrid(boolean)
-
getLegend
java.lang.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.
-
getLegendDataset
int getLegendDataset(java.lang.String legend)
Given a legend string, return the corresponding dataset or -1 if no legend was added with that legend string The legend would have been set by addLegend().- Parameters:
legend
- The String naming the legend- Returns:
- The legend dataset, or -1 if not found.
- Since:
- Ptolemy II 10.0
-
getPlotRectangle
java.lang.Object getPlotRectangle()
Get the current plot rectangle. Note that in PlotBox, the Rectangle returned by this method is calculated from the values of _ulx _uly, _lrx and _lry. The value passed in by setPlotRectangle() is not directly used, thus calling getPlotRectangle() may not return the same rectangle that was passed in with setPlotRectangle().- Returns:
- Rectangle
- See Also:
setPlotRectangle(Object)
-
getTitle
java.lang.String getTitle()
Get the title of the graph, or an empty string if there is none.- Returns:
- The title.
- See Also:
setTitle(String)
-
getXAutoRange
double[] getXAutoRange()
Get the range for X values of the data points registered so far. Usually, derived classes handle managing the range by checking each new point against the current range.- Returns:
- An array of two doubles where the first element is the minimum and the second element is the maximum.
- See Also:
getXRange()
-
getXLabel
java.lang.String getXLabel()
Get the label for the X (horizontal) axis, or null if none has been set.- Returns:
- The X label.
- See Also:
setXLabel(String)
-
getXLog
boolean getXLog()
Return whether the X axis is drawn with a logarithmic scale.- Returns:
- True if the X axis is logarithmic.
- See Also:
setXLog(boolean)
-
getXRange
double[] getXRange()
Get the X range. IfsetXRange(double, double)
has been called, then this method returns the values passed in as arguments to setXRange(double, double). If setXRange(double, double) has not been called, then this method returns the range of the data to be plotted, which might not be all of the data due to zooming.- Returns:
- An array of two doubles where the first element is the minimum and the second element is the maximum.
- See Also:
getXAutoRange()
,setXRange(double, double)
-
getXTicks
java.util.Vector[] getXTicks()
Get the X ticks that have been specified, or null if none. The return value is an array with two vectors, the first of which specifies the X tick locations (as instances of Double), and the second of which specifies the corresponding labels.- Returns:
- The X ticks.
-
getYAutoRange
double[] getYAutoRange()
Get the range for Y values of the data points registered so far. Usually, derived classes handle managing the range by checking each new point against the range.- Returns:
- An array of two doubles where the first element is the minimum and the second element is the maximum.
- See Also:
getYRange()
-
getYLabel
java.lang.String getYLabel()
Get the label for the Y (vertical) axis, or null if none has been set.- Returns:
- The Y label.
- See Also:
setYLabel(String)
-
getYLog
boolean getYLog()
Return whether the Y axis is drawn with a logarithmic scale.- Returns:
- True if the Y axis is logarithmic.
- See Also:
setYLog(boolean)
-
getYRange
double[] getYRange()
Get the Y range. IfsetYRange(double, double)
has been called, then this method returns the values passed in as arguments to setYRange(double, double). If setYRange(double, double) has not been called, then this method returns the range of the data to be plotted, which might not be all of the data due to zooming.- Returns:
- An array of two doubles where the first element is the minimum and the second element is the maximum.
- See Also:
getYAutoRange()
,setYRange(double, double)
-
getYTicks
java.util.Vector[] getYTicks()
Get the Y ticks that have been specified, or null if none. The return value is an array with two vectors, the first of which specifies the Y tick locations (as instances of Double), and the second of which specifies the corresponding labels.- Returns:
- The Y ticks.
-
init
@Deprecated void init()
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.
-
parseFile
@Deprecated void parseFile(java.lang.String filespec)
Deprecated.Use read() to read the old file format, or use one of the classes in the plotml package to read the XML-based file format.Syntactic sugar for parseFile(filespec, documentBase).- Parameters:
filespec
- The file to be read.
-
parseFile
@Deprecated void parseFile(java.lang.String filespec, java.net.URL documentBase)
Deprecated.Use read() instead.Open up the input file, which could be stdin, a URL, or a file.- Parameters:
filespec
- The file to be read.documentBase
- The base of the URL
-
read
void read(java.io.InputStream in) throws java.io.IOException
Read commands and/or plot data from an input stream in the old (non-XML) file syntax. 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));
- Parameters:
in
- The input stream.- Throws:
java.io.IOException
- If the stream cannot be read.
-
read
void read(java.lang.String command)
Read a single line command provided as a string. The commands can be any of those in the ASCII file format.- Parameters:
command
- A command.
-
removeLegend
void removeLegend(int dataset)
Remove the legend (displayed at the upper right) for the specified data set. If the dataset is not found, nothing will occur. The PlotBox must be repainted in order for this to take effect.- Parameters:
dataset
- The dataset index.
-
renameLegend
void renameLegend(int dataset, java.lang.String newName)
Rename a legend.- Parameters:
dataset
- The dataset of the legend to be renamed. If there is no dataset with this value, then nothing happens.newName
- The new name of legend.- See Also:
addLegend(int, String)
-
repaint
void repaint()
Repaint the object.
-
resetAxes
void resetAxes()
Reset the X and Y axes to the ranges that were first specified using setXRange() and setYRange(). If these methods have not been called, then reset to the default ranges. This method calls repaint(), which eventually causes the display to be updated.
-
samplePlot
void samplePlot()
Do nothing in this base class. Derived classes might want to override this class to give an example of their use.
-
setAutomaticRescale
void setAutomaticRescale(boolean automaticRescale)
Set automatic rescale. Automatic rescaling is enabled when automaticRescale equals true and disabled when automaticRescale equals false.- Parameters:
automaticRescale
- The boolean that specifies whether plots should be automatic rescaled.
-
setBackground
void setBackground(java.lang.Object background)
Set the background color.- Parameters:
background
- The background color.
-
setButtons
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. This method should only be called from within the event dispatch thread, since it interacts with swing.- Parameters:
visible
- If true, make the fill button appear.- See Also:
destroy()
-
setCaptions
void setCaptions(java.util.Vector captionStrings)
Set the strings of the caption.- Parameters:
captionStrings
- A Vector where each element contains a String that is one line of the caption.- See Also:
getCaptions()
,clearCaptions()
-
setColor
void setColor(boolean useColor)
If the argument is false, draw the plot without using color (in black and white). Otherwise, draw it in color (the default).- Parameters:
useColor
- False to draw in back and white.- See Also:
getColor()
-
setColors
void setColors(java.lang.Object[] colors)
Set the point colors. Note that the default colors have been carefully selected to maximize readability and that it is easy to use colors that result in a very ugly plot.- Parameters:
colors
- Array of colors to use in succession for data sets.- See Also:
getColors()
-
setDataurl
@Deprecated void setDataurl(java.lang.String filespec)
Deprecated.Use read() instead.Set the file to read when init() is called.- Parameters:
filespec
- the file to be read- See Also:
getDataurl()
-
setDocumentBase
@Deprecated void setDocumentBase(java.net.URL documentBase)
Deprecated.Use read() instead.Set the document base to used when init() is called to read a URL.- Parameters:
documentBase
- The document base to be used.- See Also:
getDocumentBase()
-
setForeground
void setForeground(java.lang.Object foreground)
Set the foreground color.- Parameters:
foreground
- The foreground color.
-
setGrid
void setGrid(boolean grid)
Control whether the grid is drawn.- Parameters:
grid
- If true, a grid is drawn.- See Also:
getGrid()
-
setLabelFont
void setLabelFont(java.lang.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.
-
setPlotRectangle
void setPlotRectangle(java.lang.Object rectangle)
Set the plot rectangle inside the axes. This method can be used to create two plots that share the same axes.- Parameters:
rectangle
- Rectangle space inside axes.- See Also:
getPlotRectangle()
-
setSize
void setSize(int width, int height)
Set the size of the plot. This overrides the base class to make it work. In particular, it records the specified size so that getMinimumSize() and getPreferredSize() return the specified value. However, it only works if the plot is placed in its own JPanel. This is because the JPanel asks the contained component for its preferred size before determining the size of the panel. If the plot is placed directly in the content pane of a JApplet, then, mysteriously, this method has no effect.- Parameters:
width
- The width, in pixels.height
- The height, in pixels.
-
setTimedRepaint
void setTimedRepaint(boolean timedRepaint)
Set repainting with a certain fixed refresh rate. This timed repainting is enabled when timedRepaint equals true and disabled when timedRepaint equals false.- Parameters:
timedRepaint
- The boolean that specifies whether repainting should happen with a certain fixed refresh rate.
-
setTitle
void setTitle(java.lang.String title)
Set the title of the graph.- Parameters:
title
- The title.- See Also:
getTitle()
-
setTitleFont
void setTitleFont(java.lang.String name)
Set the title font. The font names understood are those understood by java.awt.Font.decode().- Parameters:
name
- A font name.
-
setWrap
void setWrap(boolean wrap)
Specify whether the X axis is wrapped. If it is, then X values that are out of range are remapped to be in range using modulo arithmetic. The X range is determined by the most recent call to setXRange() (or the most recent zoom). If the X range has not been set, then use the default X range, or if data has been plotted, then the current fill range.- Parameters:
wrap
- If true, wrapping of the X axis is enabled.
-
setXLabel
void setXLabel(java.lang.String label)
Set the label for the X (horizontal) axis.- Parameters:
label
- The label.- See Also:
getXLabel()
-
setXLog
void setXLog(boolean xlog)
Specify whether the X axis is drawn with a logarithmic scale. If you would like to have the X axis drawn with a logarithmic axis, then setXLog(true) should be called before adding any data points.- Parameters:
xlog
- If true, logarithmic axis is used.- See Also:
getXLog()
-
setXRange
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.Note that if
setXLog(boolean)
has been called, then the min and max values should be in log units.- Parameters:
min
- The left extent of the range.max
- The right extent of the range.- See Also:
getXRange()
-
setYLabel
void setYLabel(java.lang.String label)
Set the label for the Y (vertical) axis.- Parameters:
label
- The label.- See Also:
getYLabel()
-
setYLog
void setYLog(boolean ylog)
Specify whether the Y axis is drawn with a logarithmic scale. If you would like to have the Y axis drawn with a logarithmic axis, then setYLog(true) should be called before adding any data points.- Parameters:
ylog
- If true, logarithmic axis is used.- See Also:
getYLog()
-
setYRange
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.Note that if
setYLog(boolean)
has been called, then the min and max values should be in log units.- Parameters:
min
- The bottom extent of the range.max
- The top extent of the range.- See Also:
getYRange()
-
write
void write(java.io.OutputStream out)
Write the current data and plot configuration to the specified stream in PlotML syntax. PlotML is an XML extension for plot data. The written information is standalone, in that it includes the DTD (document type definition). This makes is somewhat verbose. To get smaller files, use the two argument version of write(). The output is buffered, and is flushed and closed before exiting. Derived classes should override writeFormat and writeData rather than this method.- Parameters:
out
- An output stream.
-
write
void write(java.io.OutputStream out, java.lang.String dtd)
Write the current data and plot configuration to the specified stream in PlotML syntax. PlotML is an XML scheme for plot data. The URL (relative or absolute) for the DTD is given as the second argument. If that argument is null, then the PlotML PUBLIC DTD is referenced, resulting in a file that can be read by a PlotML parser without any external file references, as long as that parser has local access to the DTD. The output is buffered, and is flushed and closed before exiting. Derived classes should override writeFormat and writeData rather than this method.- Parameters:
out
- An output stream.dtd
- The reference (URL) for the DTD, or null to use the PUBLIC DTD.
-
write
void write(java.io.Writer out, java.lang.String dtd)
Write the current data and plot configuration to the specified stream in PlotML syntax. PlotML is an XML scheme for plot data. The URL (relative or absolute) for the DTD is given as the second argument. If that argument is null, then the PlotML PUBLIC DTD is referenced, resulting in a file that can be read by a PlotML parser without any external file references, as long as that parser has local access to the DTD. The output is buffered, and is flushed before exiting.- Parameters:
out
- An output writer.dtd
- The reference (URL) for the DTD, or null to use the PUBLIC DTD.
-
writeData
void writeData(java.io.PrintWriter output)
Write plot data information to the specified output stream in PlotML. In this base class, there is no data to write, so this method returns without doing anything.- Parameters:
output
- A buffered print writer.
-
writeFormat
void writeFormat(java.io.PrintWriter output)
Write plot format information to the specified output stream in PlotML. Derived classes should override this method to first call the parent class method, then add whatever additional format information they wish to add to the stream.- Parameters:
output
- A buffered print writer.
-
writeOldSyntax
@Deprecated void writeOldSyntax(java.io.OutputStream out)
Deprecated.Write the current data and plot configuration to the specified stream in the old PtPlot syntax. The output is buffered, and is flushed and closed before exiting. Derived classes should override _writeOldSyntax() rather than this method.- Parameters:
out
- An output stream.
-
zoom
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.
-
-