ptolemy.plot
Class Plot

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.JPanel
                  extended by ptolemy.plot.PlotBox
                      extended by ptolemy.plot.Plot
All Implemented Interfaces:
java.awt.image.ImageObserver, java.awt.MenuContainer, java.awt.print.Printable, java.io.Serializable, javax.accessibility.Accessible
Direct Known Subclasses:
EditablePlot, PlotLive

public class Plot
extends PlotBox

A flexible signal plotter. The plot can be configured and data can be provided either through a file with commands or through direct invocation of the public methods of the class.

When calling the public methods, in most cases the changes will not be visible until paintComponent() is called. To request that this be done, call repaint(). One exception is addPoint(), which makes the new point visible immediately if the plot is visible on the screen and addPoint() is called from the event dispatching thread.

This base class supports a simple file syntax that has largely been replaced by the XML-based PlotML syntax. To read a file or a URL in this older syntax, use the read() method. This older syntax contains 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 those supported by the base class, plus a few more. The commands are case insensitive, but are usually capitalized. The number of data sets to be plotted does not need to be specified. Data sets are added as needed. Each dataset can be optionally identified with color (see the base class) or with unique marks. The style of marks used to denote a data point is defined by one of the following commands:

 Marks: none
 Marks: points
 Marks: bigdots
 Marks: dots
 Marks: various
 Marks: pixels
 
Here, "points" are small dots, while "dots" are larger. If "various" is specified, then unique marks are used for the first ten data sets, and then recycled. If "pixels" are specified, then each point is drawn as one pixel. Using no marks is useful when lines connect the points in a plot, which is done by default. However, if persistence is set, then you may want to choose "pixels" because the lines may overlap, resulting in annoying gaps in the drawn line. If the above directive appears before any DataSet directive, then it specifies the default for all data sets. If it appears after a DataSet directive, then it applies only to that data set.

To disable connecting lines, use:

 Lines: off
 
To reenable them, use
 Lines: on
 
You can control the line style on a per dataset basis by adding
 LineStyle: solid
 
Other supported line styles are "dotted", "dashed", "dotdashed" and "dotdotdashed". You can also specify "impulses", which are lines drawn from a plotted point down to the x axis. Plots with impulses are often called "stem plots." These are off by default, but can be turned on with the command:
 Impulses: on
 
or back off with the command
 Impulses: off
 
If that command appears before any DataSet directive, then the command applies to all data sets. Otherwise, it applies only to the current data set. To create a bar graph, turn off lines and use any of the following commands:
 Bars: on
 Bars: width
 Bars: width, offset
 
The width is a real number specifying the width of the bars in the units of the x axis. The offset is a real number specifying how much the bar of the ith data set is offset from the previous one. This allows bars to "peek out" from behind the ones in front. Note that the frontmost data set will be the first one. To turn off bars, use
 Bars: off
 
To specify data to be plotted, start a data set with the following command:
 DataSet: string
 
Here, string is a label that will appear in the legend. It is not necessary to enclose the string in quotation marks. To start a new dataset without giving it a name, use:
 DataSet:
 
In this case, no item will appear in the legend. New datasets are plotted behind the previous ones. If the following directive occurs:
 ReuseDataSets: on
 
Then datasets with the same name will be merged. This makes it easier to combine multiple datafiles that contain the same datasets into one file. By default, this capability is turned off, so datasets with the same name are not merged. The data itself is given by a sequence of commands with one of the following forms:
 x, y
 draw: x, y
 move: x, y
 x, y, yLowErrorBar, yHighErrorBar
 draw: x, y, yLowErrorBar, yHighErrorBar
 move: x, y, yLowErrorBar, yHighErrorBar
 
The "draw" command is optional, so the first two forms are equivalent. The "move" command causes a break in connected points, if lines are being drawn between points. The numbers x and y are arbitrary numbers as supported by the Double parser in Java. If there are four numbers, then the last two numbers are assumed to be the lower and upper values for error bars. The numbers can be separated by commas, spaces or tabs.

Some of the methods, such as those that add points a plot, are executed in the event thread, possibly some time after they are called. If they are called from a thread different from the event thread, then the order in which changes to the plot take effect may be surprising. We recommend that any code you write that changes the plot in visible ways be executed in the event thread. You can accomplish this using the following template:

 Runnable doAction = new Runnable() {
 public void run() {
 ... make changes here (e.g. setMarksStyle()) ...
 }
 };
 plot.deferIfNecessary(doAction);
 

This plotter has some limitations:

Since:
Ptolemy II 0.2
Version:
$Id: Plot.java 59167 2010-09-21 17:08:02Z cxh $
Author:
Edward A. Lee, Christopher Brooks, Contributor: Tom Peachey, Bert Rodiers
See Also:
Serialized Form
Accepted Rating:
Yellow (cxh)
Proposed Rating:
Yellow (cxh)

Nested Class Summary
private  class Plot.Bin
          A bin is represents a number of points that are all displayed on the same x position.
private static class Plot.Format
           
 
Nested classes/interfaces inherited from class ptolemy.plot.PlotBox
PlotBox.ButtonListener, PlotBox.CommandListener, PlotBox.DragListener, PlotBox.ZoomListener
 
Nested classes/interfaces inherited from class javax.swing.JPanel
javax.swing.JPanel.AccessibleJPanel
 
Nested classes/interfaces inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
private  double _barOffset
           
private  boolean _bars
           
private  double _barWidth
           
private  java.util.ArrayList<java.util.ArrayList<Plot.Bin>> _bins
          An arraylist of the bins in the plot.
private  boolean _connected
           
protected  int _currentdataset
          The current dataset.
private static float _DEFAULT_WIDTH
          The initial default width.
private  int _diameter
           
private static int _ERRORBAR_LEG_LENGTH
           
private  boolean _firstInSet
           
private  java.util.ArrayList<Plot.Format> _formats
           
private  java.awt.Graphics _graphics
          Cached copy of graphics, needed to reset when we are exporting to EPS.
private  boolean _impulses
           
private static java.lang.Long _INITIAL_PREVIOUS_VALUE
          Initial value for elements in _prevx and _prevy that indicate we have not yet seen data.
private  java.util.HashMap<java.lang.Integer,PlotPoint> _lastPointWithExtraDot
           
private static java.awt.BasicStroke _LINE_STROKE1
           
private static java.awt.BasicStroke _LINE_STROKE2
           
private static java.lang.String[] _LINE_STYLES_ARRAY
          True if different line styles should be used.
private  boolean _lineStyles
          True if different line styles should be used.
private  boolean _markDisconnections
          True when disconnections should be marked.
protected  int _marks
          An indicator of the marks style.
private static int _MAX_MARKS
           
private  int _maxDataset
           
private  boolean _needBinRedraw
           
private  boolean _needPlotRefill
           
private  java.util.ArrayList<java.lang.Integer> _pointInBinOffset
          Points in bins have an absolute index within the virtual array of all points that once existed in Plot.
protected  java.util.ArrayList<java.util.ArrayList<PlotPoint>> _points
          A vector of datasets.
private  int _pointsPersistence
           
private  java.util.ArrayList<java.lang.Long> _prevErasedxpos
           
private  java.util.ArrayList<java.lang.Long> _prevErasedypos
           
private  java.util.ArrayList<java.lang.Long> _prevxpos
           
private  java.util.ArrayList<java.lang.Long> _prevypos
           
private  int _radius
           
private  boolean _reuseDatasets
           
private  boolean _sawFirstDataSet
           
private  java.util.ArrayList<java.lang.Integer> _scheduledBinsToAdd
           
private  java.util.ArrayList<java.lang.Integer> _scheduledBinsToErase
           
private  boolean _showing
           
private  float _width
          The width of the current stroke.
private  double _xPersistence
           
private  boolean _xyInvalid
           
 
Fields inherited from class ptolemy.plot.PlotBox
_background, _bottomPadding, _colors, _documentBase, _foreground, _grid, _height, _leftPadding, _LOG10SCALE, _lrx, _lry, _originalXhigh, _originalXlow, _originalXRangeGiven, _originalYhigh, _originalYlow, _originalYRangeGiven, _padding, _plotImage, _preferredHeight, _preferredWidth, _rangesGivenByZooming, _rightPadding, _specifiedPlotRectangle, _topPadding, _ulx, _uly, _usecolor, _wrap, _wrapHigh, _wrapLow, _xBottom, _xhighgiven, _xlog, _xlowgiven, _xMax, _xMin, _xRangeGiven, _xscale, _xTop, _yBottom, _yhighgiven, _ylog, _ylowgiven, _yMax, _yMin, _yRangeGiven, _yscale, _yTop, PTPLOT_RELEASE
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.print.Printable
NO_SUCH_PAGE, PAGE_EXISTS
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
Plot()
           
 
Method Summary
private  boolean _addLegendIfNecessary(boolean connected)
           
private  void _addPoint(int dataset, double x, double y, double yLowEB, double yHighEB, boolean connected, boolean errorBar)
           
private  void _addPointToBin(int dataset, PlotPoint point, int pointIndex)
          Add point to the corresponding Bin.
protected  void _checkDatasetIndex(int dataset)
          Check the argument to ensure that it is a valid data set index.
private  void _clear(boolean format)
           
private  void _clear(int dataset)
          Clear the plot of data points in the specified dataset.
private  void _dividePointsIntoBins()
          Subdivide all points into different bins.
protected  void _drawBar(java.awt.Graphics graphics, int dataset, long xpos, long ypos, boolean clip)
          Draw bar from the specified point to the y axis.
private  void _drawBin(java.awt.Graphics graphics, int dataset, int binIndex)
           
protected  void _drawErrorBar(java.awt.Graphics graphics, int dataset, long xpos, long yLowEBPos, long yHighEBPos, boolean clip)
          Draw an error bar for the specified yLowEB and yHighEB values.
protected  void _drawImpulse(java.awt.Graphics graphics, long xpos, long ypos, boolean clip)
          Draw a line from the specified point to the y axis.
protected  void _drawLine(java.awt.Graphics graphics, int dataset, long startx, long starty, long endx, long endy, boolean clip)
          Draw a line from the specified starting point to the specified ending point.
protected  void _drawLine(java.awt.Graphics graphics, int dataset, long startx, long starty, long endx, long endy, boolean clip, float width)
          Draw a line from the specified starting point to the specified ending point.
protected  void _drawPlot(java.awt.Graphics graphics, boolean clearfirst, java.awt.Rectangle drawRectangle)
          Draw the axes and then plot all points.
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.
private  void _drawPoint(java.awt.Graphics graphics, int dataset, long xpos, long ypos, boolean clip, int marks)
          Put a mark corresponding to the specified dataset at the specified x and y position.
private  void _eraseFirstBin(int dataset)
           
private  void _erasePoint(int dataset, int index)
           
private  void _fillPlot()
           
private  boolean _isConnected(int dataset)
           
protected  boolean _parseLine(java.lang.String line)
          Parse a line that gives plotting information.
private  void _resetColorForDrawing(java.awt.Graphics graphics, boolean forceExorWithBackground)
          Reset the color for drawing.
protected  void _resetScheduledTasks()
          Reset a scheduled redraw tasks.
private  void _scheduleBinRedrawAdd(int dataset, boolean binAdded)
          Schedule a bin to be (re)drawn due to the addition of bin.
private  void _scheduleBinRedrawRemove(int dataset, int nbrOfElementsToErase)
          Schedule a bin to be (re)drawn due to the removal of a bin.
protected  void _scheduledRedraw()
          Perform a scheduled redraw.
private  void _setColorForDrawing(java.awt.Graphics graphics, int dataset, boolean forceExorWithBackground)
          Set the color for drawing.
protected  void _setWidth(java.awt.Graphics graphics, float width)
          If the graphics argument is an instance of Graphics2D, then set the current stroke to the specified width.
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 addPoint(int dataset, double x, double y, boolean connected)
          In the specified data set, add the specified x, y point to the plot.
 void addPointWithErrorBars(int dataset, double x, double y, double yLowEB, double yHighEB, boolean connected)
          In the specified data set, add the specified x, y point to the plot with error bars.
 void clear(boolean format)
          Clear the plot of all data points.
 void clear(int dataset)
          Clear the plot of data points in the specified dataset.
 void erasePoint(int dataset, int index)
          Erase the point at the given index in the given dataset.
 void fillPlot()
          Rescale so that the data that is currently plotted just fits.
 boolean getConnected()
          Return whether the default is to connect subsequent points with a line.
 boolean getImpulses()
          Return whether a line will be drawn from any plotted point down to the x axis.
 boolean getLineStyles()
          Return false if setLineStyles() has not yet been called or if setLineStyles(false) has been called, which signifies that different line styles are not to be used.
 java.lang.String getMarksStyle()
          Get the marks style, which is one of "none", "points", "dots", or "various".
 int getMaxDataSets()
          Deprecated.  
 int getNumDataSets()
          Return the actual number of data sets.
 boolean getReuseDatasets()
          Return false if setReuseDatasets() has not yet been called or if setReuseDatasets(false) has been called.
 void markDisconnections(boolean value)
          Mark the disconnections with a Dot in case value equals true, otherwise these points are not marked.
 void parseFile(java.lang.String filespec, java.net.URL documentBase)
          Deprecated.  
 void read(java.io.InputStream inputStream)
          Read a file with the old syntax (non-XML).
 void samplePlot()
          Create a sample plot.
 void setBars(boolean on)
          Turn bars on or off (for bar charts).
 void setBars(double width, double offset)
          Turn bars on and set the width and offset.
 void setConnected(boolean on)
          If the argument is true, then the default is to connect subsequent points with a line.
 void setConnected(boolean on, int dataset)
          If the first argument is true, then by default for the specified dataset, points will be connected by a line.
 void setImpulses(boolean on)
          If the argument is true, then a line will be drawn from any plotted point down to the x axis.
 void setImpulses(boolean on, int dataset)
          If the first argument is true, then a line will be drawn from any plotted point in the specified dataset down to the x axis.
 void setLineStyle(java.lang.String styleString, int dataset)
          Set the style of the lines joining marks.
 void setLineStyles(boolean lineStyles)
          If the argument is true, draw the data sets with different line styles.
 void setMarksStyle(java.lang.String style)
          Set the marks style to "none", "points", "dots", or "various".
 void setMarksStyle(java.lang.String style, int dataset)
          Set the marks style to "none", "points", "dots", "various", or "pixels" for the specified dataset.
 void setNumSets(int numSets)
          Deprecated.  
 void setPointsPersistence(int persistence)
          Calling this method with a positive argument sets the persistence of the plot to the given number of points.
 void setReuseDatasets(boolean on)
          If the argument is true, then datasets with the same name are merged into a single dataset.
 void setXPersistence(double persistence)
          Calling this method with a positive argument sets the persistence of the plot to the given width in units of the horizontal axis.
 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, an XML scheme.
 
Methods inherited from class ptolemy.plot.PlotBox
_automaticRescale, _drawPlot, _help, _setButtonsVisibility, _setPadding, _timedRepaint, _zoom, _zoomBox, _zoomStart, addCaptionLine, addXTick, addYTick, clearCaptions, clearLegends, deferIfNecessary, destroy, export, exportImage, exportImage, exportImage, exportImage, getCaptions, getColor, getColorByName, getColors, getDataurl, getDocumentBase, getGrid, getLegend, getLegendDataset, getPlotRectangle, getPreferredSize, getTitle, getXAutoRange, getXLabel, getXLog, getXRange, getXTicks, getYAutoRange, getYLabel, getYLog, getYRange, getYTicks, init, paintComponent, parseFile, print, read, removeLegend, renameLegend, resetAxes, setAutomaticRescale, setBackground, setBounds, setButtons, setCaptions, setColor, setColors, setDataurl, setDocumentBase, setForeground, setGrid, setLabelFont, setPlotRectangle, setSize, setTimedRepaint, setTitle, setTitleFont, setWrap, setXLabel, setXLog, setXRange, setYLabel, setYLog, setYRange, write, write, write, writeOldSyntax, zoom
 
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_currentdataset

protected int _currentdataset
The current dataset.


_marks

protected volatile int _marks
An indicator of the marks style. See _parseLine method for interpretation.


_points

protected java.util.ArrayList<java.util.ArrayList<PlotPoint>> _points
A vector of datasets.


_markDisconnections

private boolean _markDisconnections
True when disconnections should be marked.


_barOffset

private volatile double _barOffset

_bars

private boolean _bars

_barWidth

private volatile double _barWidth

_bins

private java.util.ArrayList<java.util.ArrayList<Plot.Bin>> _bins
An arraylist of the bins in the plot. A bin is represents a number of points that are all displayed on the same x position. A bin is meant to avoid superfluous drawings of lines. So instaed of having to draw a line between each point, you can draw a line between the minimum and maximum and maximum position.


_connected

private boolean _connected

_diameter

private int _diameter

_DEFAULT_WIDTH

private static final float _DEFAULT_WIDTH
The initial default width.

See Also:
Constant Field Values

_ERRORBAR_LEG_LENGTH

private static final int _ERRORBAR_LEG_LENGTH
See Also:
Constant Field Values

_firstInSet

private boolean _firstInSet

_formats

private java.util.ArrayList<Plot.Format> _formats

_graphics

private java.awt.Graphics _graphics
Cached copy of graphics, needed to reset when we are exporting to EPS.


_impulses

private boolean _impulses

_INITIAL_PREVIOUS_VALUE

private static final java.lang.Long _INITIAL_PREVIOUS_VALUE
Initial value for elements in _prevx and _prevy that indicate we have not yet seen data.


_lastPointWithExtraDot

private java.util.HashMap<java.lang.Integer,PlotPoint> _lastPointWithExtraDot

_LINE_STROKE1

private static final java.awt.BasicStroke _LINE_STROKE1

_LINE_STROKE2

private static final java.awt.BasicStroke _LINE_STROKE2

_lineStyles

private boolean _lineStyles
True if different line styles should be used.


_LINE_STYLES_ARRAY

private static java.lang.String[] _LINE_STYLES_ARRAY
True if different line styles should be used.


_maxDataset

private int _maxDataset

_MAX_MARKS

private static final int _MAX_MARKS
See Also:
Constant Field Values

_needBinRedraw

private boolean _needBinRedraw

_needPlotRefill

private boolean _needPlotRefill

_pointInBinOffset

private java.util.ArrayList<java.lang.Integer> _pointInBinOffset
Points in bins have an absolute index within the virtual array of all points that once existed in Plot. This is done to avoid having to change all bins when points in the beginning are removed. The offset _pointInBinOffset is a positive number that denotes the difference between the index of the point in the current point arraylist and the virtual one containing all points.


_pointsPersistence

private int _pointsPersistence

_prevxpos

private java.util.ArrayList<java.lang.Long> _prevxpos

_prevypos

private java.util.ArrayList<java.lang.Long> _prevypos

_prevErasedxpos

private java.util.ArrayList<java.lang.Long> _prevErasedxpos

_prevErasedypos

private java.util.ArrayList<java.lang.Long> _prevErasedypos

_radius

private int _radius

_reuseDatasets

private boolean _reuseDatasets

_sawFirstDataSet

private boolean _sawFirstDataSet

_scheduledBinsToAdd

private java.util.ArrayList<java.lang.Integer> _scheduledBinsToAdd

_scheduledBinsToErase

private java.util.ArrayList<java.lang.Integer> _scheduledBinsToErase

_showing

private boolean _showing

_xPersistence

private double _xPersistence

_xyInvalid

private boolean _xyInvalid

_width

private float _width
The width of the current stroke. Only effective if the Graphics is a Graphics2D.

Constructor Detail

Plot

public Plot()
Method Detail

addLegend

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

Overrides:
addLegend in class PlotBox
Parameters:
dataset - The dataset index.
legend - The label for the dataset.
See Also:
PlotBox.renameLegend(int, String)

addPoint

public void addPoint(int dataset,
                     double x,
                     double y,
                     boolean connected)
In the specified data set, add the specified x, y point to the plot. Data set indices begin with zero. If the data set does not exist, create it. The fourth argument indicates whether the point should be connected by a line to the previous point. Regardless of the value of this argument, a line will not drawn if either there has been no previous point for this dataset or setConnected() has been called with a false argument.

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the point will not be added immediately (unless you call this method from within the event dispatch thread). All the methods that do this deferring coordinate so that they are executed in the order that you called them.

Parameters:
dataset - The data set index.
x - The X position of the new point.
y - The Y position of the new point.
connected - If true, a line is drawn to connect to the previous point.

addPointWithErrorBars

public void addPointWithErrorBars(int dataset,
                                  double x,
                                  double y,
                                  double yLowEB,
                                  double yHighEB,
                                  boolean connected)
In the specified data set, add the specified x, y point to the plot with error bars. Data set indices begin with zero. If the dataset does not exist, create it. yLowEB and yHighEB are the lower and upper error bars. The sixth argument indicates whether the point should be connected by a line to the previous point. The new point will be made visible if the plot is visible on the screen. Otherwise, it will be drawn the next time the plot is drawn on the screen. This method is based on a suggestion by Michael Altmann (michael@email.labmed.umn.edu).

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the point will not be added immediately (unless you call this method from within the event dispatch thread). All the methods that do this deferring coordinate so that they are executed in the order that you called them.

Parameters:
dataset - The data set index.
x - The X position of the new point.
y - The Y position of the new point.
yLowEB - The low point of the error bar.
yHighEB - The high point of the error bar.
connected - If true, a line is drawn to connect to the previous point.

clear

public void clear(boolean format)
Clear the plot of all data points. If the argument is true, then reset all parameters to their initial conditions, including the persistence, plotting format, and axes formats. For the change to take effect, you must call repaint().

Overrides:
clear in class PlotBox
Parameters:
format - If true, clear the format controls as well.

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the clear will not be executed immediately (unless you call this method from within the event dispatch thread). All the methods that do this deferring coordinate so that they are executed in the order that you called them.


clear

public void clear(int dataset)
Clear the plot of data points in the specified dataset. This calls repaint() to request an update of the display.

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the point will not be added immediately (unless you call this method from within the event dispatch thread). If you call this method, the addPoint() method, and the erasePoint() method in any order, they are assured of being processed in the order that you called them.

Parameters:
dataset - The dataset to clear.

erasePoint

public void erasePoint(int dataset,
                       int index)
Erase the point at the given index in the given dataset. If lines are being drawn, these lines are erased and if necessary new ones will be drawn. The point is not checked to see whether it is in range, so care must be taken by the caller to ensure that it is.

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the point will not be erased immediately (unless you call this method from within the event dispatch thread). All the methods that do this deferring coordinate so that they are executed in the order that you called them.

Parameters:
dataset - The data set index.
index - The index of the point to erase.

fillPlot

public void fillPlot()
Rescale so that the data that is currently plotted just fits. This overrides the base class method to ensure that the protected variables _xBottom, _xTop, _yBottom, and _yTop are valid. This method calls repaint(), which eventually causes the display to be updated.

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the fill will not occur immediately (unless you call this method from within the event dispatch thread). All the methods that do this deferring coordinate so that they are executed in the order that you called them.

Overrides:
fillPlot in class PlotBox

getConnected

public boolean getConnected()
Return whether the default is to connect subsequent points with a line. If the result is false, then points are not connected. When points are by default connected, individual points can be not connected by giving the appropriate argument to addPoint(). Also, a different default can be set for each dataset, overriding this global default.

Returns:
True if points will be connected by default
See Also:
setConnected(boolean)

getImpulses

public boolean getImpulses()
Return whether a line will be drawn from any plotted point down to the x axis. A plot with such lines is also known as a stem plot.

Returns:
True if this is an impulse plot
See Also:
setImpulses(boolean)

getLineStyles

public boolean getLineStyles()
Return false if setLineStyles() has not yet been called or if setLineStyles(false) has been called, which signifies that different line styles are not to be used. Otherwise, return true.

Returns:
True if line styles are to be used.
See Also:
setLineStyles(boolean)

getMarksStyle

public java.lang.String getMarksStyle()
Get the marks style, which is one of "none", "points", "dots", or "various".

Returns:
A string specifying the style for points.
See Also:
setMarksStyle(java.lang.String)

getMaxDataSets

@Deprecated
public int getMaxDataSets()
Deprecated. 

Return the maximum number of data sets. This method is deprecated, since there is no longer an upper bound.

Returns:
The maximum number of data sets

getNumDataSets

public int getNumDataSets()
Return the actual number of data sets.

Returns:
The number of data sets that have been created.

getReuseDatasets

public boolean getReuseDatasets()
Return false if setReuseDatasets() has not yet been called or if setReuseDatasets(false) has been called.

Returns:
false if setReuseDatasets() has not yet been called or if setReuseDatasets(false) has been called.
Since:
Ptplot 5.3
See Also:
setReuseDatasets(boolean)

parseFile

@Deprecated
public void parseFile(java.lang.String filespec,
                                 java.net.URL documentBase)
Deprecated. 

Override the base class to indicate that a new data set is being read. This method is deprecated. Use read() instead (to read the old file format) or one of the classes in the plotml package to read the new (XML) file format.

Overrides:
parseFile in class PlotBox

markDisconnections

public void markDisconnections(boolean value)
Mark the disconnections with a Dot in case value equals true, otherwise these points are not marked.

Parameters:
value - True when disconnections should be marked.

read

public void read(java.io.InputStream inputStream)
          throws java.io.IOException
Read a file with the old syntax (non-XML). Override the base class to register that we are reading a new data set.

Overrides:
read in class PlotBox
Parameters:
inputStream - The input stream.
Throws:
java.io.IOException - If the stream cannot be read.

samplePlot

public void samplePlot()
Create a sample plot. This is not actually done immediately unless the calling thread is the event dispatch thread. Instead, it is deferred to the event dispatch thread. It is important that the calling thread not hold a synchronize lock on the Plot object, or deadlock will result (unless the calling thread is the event dispatch thread).

Overrides:
samplePlot in class PlotBox

setBars

public void setBars(boolean on)
Turn bars on or off (for bar charts). Note that this is a global property, not per dataset.

Parameters:
on - If true, turn bars on.

setBars

public void setBars(double width,
                    double offset)
Turn bars on and set the width and offset. Both are specified in units of the x axis. The offset is the amount by which the i th data set is shifted to the right, so that it peeks out from behind the earlier data sets.

Parameters:
width - The width of the bars.
offset - The offset per data set.

setConnected

public void setConnected(boolean on)
If the argument is true, then the default is to connect subsequent points with a line. If the argument is false, then points are not connected. When points are by default connected, individual points can be not connected by giving the appropriate argument to addPoint(). Also, a different default can be set for each dataset, overriding this global default. setConnected will also change the behavior of points that were already drawn if the graph is redrawn. If it isn't the points are not touched. If you change back the setConnected state, the again see what was visible before.

Parameters:
on - If true, draw lines between points.
See Also:
setConnected(boolean, int), getConnected()

setConnected

public void setConnected(boolean on,
                         int dataset)
If the first argument is true, then by default for the specified dataset, points will be connected by a line. Otherwise, the points will not be connected. When points are by default connected, individual points can be not connected by giving the appropriate argument to addPoint(). Note that this method should be called before adding any points. Note further that this method should probably be called from the event thread.

Parameters:
on - If true, draw lines between points.
dataset - The dataset to which this should apply.
See Also:
setConnected(boolean), getConnected()

setImpulses

public void setImpulses(boolean on)
If the argument is true, then a line will be drawn from any plotted point down to the x axis. Otherwise, this feature is disabled. A plot with such lines is also known as a stem plot.

Parameters:
on - If true, draw a stem plot.
See Also:
getImpulses()

setImpulses

public void setImpulses(boolean on,
                        int dataset)
If the first argument is true, then a line will be drawn from any plotted point in the specified dataset down to the x axis. Otherwise, this feature is disabled. A plot with such lines is also known as a stem plot.

Parameters:
on - If true, draw a stem plot.
dataset - The dataset to which this should apply.

setLineStyle

public void setLineStyle(java.lang.String styleString,
                         int dataset)
Set the style of the lines joining marks.

Parameters:
styleString - A string specifying the color for points. The following styles are permitted: "solid", "dotted", "dashed", "dotdashed", "dotdotdashed".
dataset - The data set index.

setLineStyles

public void setLineStyles(boolean lineStyles)
If the argument is true, draw the data sets with different line styles. Otherwise, use one line style.

Parameters:
lineStyles - True if the data sets are to be drawn in different line styles.
See Also:
getLineStyles()

setMarksStyle

public void setMarksStyle(java.lang.String style)
Set the marks style to "none", "points", "dots", or "various". In the last case, unique marks are used for the first ten data sets, then recycled. This method should be called only from the event dispatch thread.

Parameters:
style - A string specifying the style for points.
See Also:
getMarksStyle()

setMarksStyle

public void setMarksStyle(java.lang.String style,
                          int dataset)
Set the marks style to "none", "points", "dots", "various", or "pixels" for the specified dataset. In the last case, unique marks are used for the first ten data sets, then recycled.

Parameters:
style - A string specifying the style for points.
dataset - The dataset to which this should apply.
See Also:
getMarksStyle()

setNumSets

@Deprecated
public void setNumSets(int numSets)
Deprecated. 

Specify the number of data sets to be plotted together. This method is deprecated, since it is no longer necessary to specify the number of data sets ahead of time.

Parameters:
numSets - The number of data sets.

setPointsPersistence

public void setPointsPersistence(int persistence)
Calling this method with a positive argument sets the persistence of the plot to the given number of points. Calling with a zero argument turns off this feature, reverting to infinite memory (unless sweeps persistence is set). If both sweeps and points persistence are set then sweeps take precedence.

Setting the persistence greater than zero forces the plot to be drawn in XOR mode, which allows points to be quickly and efficiently erased. However, there is a bug in Java (as of version 1.3), where XOR mode does not work correctly with double buffering. Thus, if you call this with an argument greater than zero, then we turn off double buffering for this panel and all of its parents. This actually happens on the next call to addPoint().

Parameters:
persistence - Number of points to persist for.

setReuseDatasets

public void setReuseDatasets(boolean on)
If the argument is true, then datasets with the same name are merged into a single dataset.

Parameters:
on - If true, then merge datasets.
See Also:
getReuseDatasets()

setXPersistence

public void setXPersistence(double persistence)
Calling this method with a positive argument sets the persistence of the plot to the given width in units of the horizontal axis. Calling with a zero argument turns off this feature, reverting to infinite memory (unless points persistence is set). If both X and points persistence are set then both are applied, meaning that points that are old by either criterion will be erased.

Setting the X persistence greater than zero forces the plot to be drawn in XOR mode, which allows points to be quickly and efficiently erased. However, there is a bug in Java (as of version 1.3), where XOR mode does not work correctly with double buffering. Thus, if you call this with an argument greater than zero, then we turn off double buffering for this panel and all of its parents. This actually happens on the next call to addPoint().

Parameters:
persistence - Persistence in units of the horizontal axis.

writeData

public void writeData(java.io.PrintWriter output)
Write plot data information to the specified output stream in PlotML.

Overrides:
writeData in class PlotBox
Parameters:
output - A buffered print writer.

writeFormat

public void writeFormat(java.io.PrintWriter output)
Write plot format information to the specified output stream in PlotML, an XML scheme.

Overrides:
writeFormat in class PlotBox
Parameters:
output - A buffered print writer.

_checkDatasetIndex

protected void _checkDatasetIndex(int dataset)
Check the argument to ensure that it is a valid data set index. If it is less than zero, throw an IllegalArgumentException (which is a runtime exception). If it does not refer to an existing data set, then fill out the _points Vector so that it does refer to an existing data set. All other dataset-related vectors are similarly filled out.

Parameters:
dataset - The data set index.

_drawBar

protected void _drawBar(java.awt.Graphics graphics,
                        int dataset,
                        long xpos,
                        long ypos,
                        boolean clip)
Draw bar from the specified point to the y axis. If the specified point is below the y axis or outside the x range, do nothing. If the clip argument is true, then do not draw above the y range. Note that paintComponent() should be called before calling this method so that _xscale and _yscale are properly set. This method should be called only from the event dispatch thread. It is not synchronized, so its caller should be.

Parameters:
graphics - The graphics context.
dataset - The index of the dataset.
xpos - The x position.
ypos - The y position.
clip - If true, then do not draw outside the range.

_drawErrorBar

protected void _drawErrorBar(java.awt.Graphics graphics,
                             int dataset,
                             long xpos,
                             long yLowEBPos,
                             long yHighEBPos,
                             boolean clip)
Draw an error bar for the specified yLowEB and yHighEB values. If the specified point is below the y axis or outside the x range, do nothing. If the clip argument is true, then do not draw above the y range. This method should be called only from the event dispatch thread. It is not synchronized, so its caller should be.

Parameters:
graphics - The graphics context.
dataset - The index of the dataset.
xpos - The x position.
yLowEBPos - The lower y position of the error bar.
yHighEBPos - The upper y position of the error bar.
clip - If true, then do not draw above the range.

_drawImpulse

protected void _drawImpulse(java.awt.Graphics graphics,
                            long xpos,
                            long ypos,
                            boolean clip)
Draw a line from the specified point to the y axis. If the specified point is below the y axis or outside the x range, do nothing. If the clip argument is true, then do not draw above the y range. This method should be called only from the event dispatch thread. It is not synchronized, so its caller should be.

Parameters:
graphics - The graphics context.
xpos - The x position.
ypos - The y position.
clip - If true, then do not draw outside the range.

_drawLine

protected void _drawLine(java.awt.Graphics graphics,
                         int dataset,
                         long startx,
                         long starty,
                         long endx,
                         long endy,
                         boolean clip)
Draw a line from the specified starting point to the specified ending point. The current color is used. If the clip argument is true, then draw only that portion of the line that lies within the plotting rectangle. This method draws a line one pixel wide. This method should be called only from the event dispatch thread. It is not synchronized, so its caller should be.

Parameters:
graphics - The graphics context.
dataset - The index of the dataset.
startx - The starting x position.
starty - The starting y position.
endx - The ending x position.
endy - The ending y position.
clip - If true, then do not draw outside the range.

_drawLine

protected void _drawLine(java.awt.Graphics graphics,
                         int dataset,
                         long startx,
                         long starty,
                         long endx,
                         long endy,
                         boolean clip,
                         float width)
Draw a line from the specified starting point to the specified ending point. The current color is used. If the clip argument is true, then draw only that portion of the line that lies within the plotting rectangle. The width argument is ignored if the graphics argument is not an instance of Graphics2D. This method should be called only from the event dispatch thread. It is not synchronized, so its caller should be.

Parameters:
graphics - The graphics context.
dataset - The index of the dataset.
startx - The starting x position.
starty - The starting y position.
endx - The ending x position.
endy - The ending y position.
clip - If true, then do not draw outside the range.
width - The thickness of the line.

_drawPlot

protected void _drawPlot(java.awt.Graphics graphics,
                         boolean clearfirst,
                         java.awt.Rectangle drawRectangle)
Draw the axes and then plot all points. If the second argument is true, clear the display first. This method is called by paintComponent(). To cause it to be called you would normally call repaint(), which eventually causes paintComponent() to be called.

Note that this is synchronized so that points are not added by other threads while the drawing is occurring. This method should be called only from the event dispatch thread, consistent with swing policy.

Overrides:
_drawPlot in class PlotBox
Parameters:
graphics - The graphics context.
clearfirst - If true, clear the plot before proceeding.
drawRectangle - The Rectangle to draw in.

_drawPoint

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. The mark is drawn in the current color. What kind of mark is drawn depends on the _marks variable and the dataset argument. If the fourth argument is true, then check the range and plot only points that are in range. This method should be called only from the event dispatch thread. It is not synchronized, so its caller should be.

Overrides:
_drawPoint in class PlotBox
Parameters:
graphics - The graphics context.
dataset - The index of the dataset.
xpos - The x position.
ypos - The y position.
clip - If true, then do not draw outside the range.

_parseLine

protected boolean _parseLine(java.lang.String line)
Parse a line that gives plotting information. Return true if the line is recognized. Lines with syntax errors are ignored. It is not synchronized, so its caller should be.

Overrides:
_parseLine in class PlotBox
Parameters:
line - A command line.
Returns:
True if the line is recognized.

_resetScheduledTasks

protected void _resetScheduledTasks()
Reset a scheduled redraw tasks.

Overrides:
_resetScheduledTasks in class PlotBox

_scheduledRedraw

protected void _scheduledRedraw()
Perform a scheduled redraw.

Overrides:
_scheduledRedraw in class PlotBox

_setWidth

protected void _setWidth(java.awt.Graphics graphics,
                         float width)
If the graphics argument is an instance of Graphics2D, then set the current stroke to the specified width. Otherwise, do nothing.

Parameters:
graphics - The graphics object.
width - The width.

_writeOldSyntax

@Deprecated
protected void _writeOldSyntax(java.io.PrintWriter output)
Deprecated. 

Write plot information to the specified output stream in the "old syntax," which predates PlotML. 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. It is not synchronized, so its caller should be.

Overrides:
_writeOldSyntax in class PlotBox
Parameters:
output - A buffered print writer.

_addLegendIfNecessary

private boolean _addLegendIfNecessary(boolean connected)

_addPoint

private void _addPoint(int dataset,
                       double x,
                       double y,
                       double yLowEB,
                       double yHighEB,
                       boolean connected,
                       boolean errorBar)

_addPointToBin

private void _addPointToBin(int dataset,
                            PlotPoint point,
                            int pointIndex)
Add point to the corresponding Bin. If the point fits into the last bin (the same xpos) it will be added to this one, otherwise a new bin will be created


_clear

private void _clear(boolean format)

_clear

private void _clear(int dataset)
Clear the plot of data points in the specified dataset. This calls repaint() to request an update of the display. This is not synchronized, so the caller should be. Moreover, this should only be called in the event dispatch thread. It should only be called via deferIfNecessary().


_dividePointsIntoBins

private void _dividePointsIntoBins()
Subdivide all points into different bins. A bin is represents a number of points that are all displayed on the same x position. When calling this function all existing bins will first be cleared.


_drawBin

private void _drawBin(java.awt.Graphics graphics,
                      int dataset,
                      int binIndex)

_drawPoint

private void _drawPoint(java.awt.Graphics graphics,
                        int dataset,
                        long xpos,
                        long ypos,
                        boolean clip,
                        int marks)
Put a mark corresponding to the specified dataset at the specified x and y position. The mark is drawn in the current color. What kind of mark is drawn depends on the marks argument and the dataset argument. If the fourth argument is true, then check the range and plot only points that are in range. This method should be called only from the event dispatch thread. It is not synchronized, so its caller should be.

Parameters:
graphics - The graphics context.
dataset - The index of the dataset.
xpos - The x position.
ypos - The y position.
clip - If true, then do not draw outside the range.
marks - The marks that have to be used for plotting the point.

_eraseFirstBin

private void _eraseFirstBin(int dataset)

_erasePoint

private void _erasePoint(int dataset,
                         int index)

_fillPlot

private void _fillPlot()

_isConnected

private boolean _isConnected(int dataset)

_resetColorForDrawing

private void _resetColorForDrawing(java.awt.Graphics graphics,
                                   boolean forceExorWithBackground)
Reset the color for drawing. This typically needs to happen after having drawn a bin or erasing one.

Parameters:
graphics - The graphics context.
forceExorWithBackground - Restore the paint made back from exor mode

_scheduleBinRedrawAdd

private void _scheduleBinRedrawAdd(int dataset,
                                   boolean binAdded)
Schedule a bin to be (re)drawn due to the addition of bin.


_scheduleBinRedrawRemove

private void _scheduleBinRedrawRemove(int dataset,
                                      int nbrOfElementsToErase)
Schedule a bin to be (re)drawn due to the removal of a bin.


_setColorForDrawing

private void _setColorForDrawing(java.awt.Graphics graphics,
                                 int dataset,
                                 boolean forceExorWithBackground)
Set the color for drawing. This typically needs to happen before drawing a bin or erasing one.

Parameters:
graphics - The graphics context.
dataset - The index of the dataset.
forceExorWithBackground - Force to go into exor mode.