/* A live signal plotter.

 @Copyright (c) 1997-2014 The Regents of the University of California.
 All rights reserved.

 Permission is hereby granted, without written agreement and without
 license or royalty fees, to use, copy, modify, and distribute this
 software and its documentation for any purpose, provided that the
 above copyright notice and the following two paragraphs appear in all
 copies of this software.

 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGE.

 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
 ENHANCEMENTS, OR MODIFICATIONS.

 PT_COPYRIGHT_VERSION_2
 COPYRIGHTENDKEY
 */
package ptolemy.plot;

import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;

import javax.swing.JButton;

///////////////////////////////////////////////////////////////////
//// PlotLive

/**
 Plot signals dynamically, where points can be added at any time
 and the display will be updated.  This should be normally used
 with some finite persistence so that old points are erased as new
 points are added.  Unfortunately, the most efficient way to erase
 old points is to draw graphics using the "exclusive or" mode, which
 introduces quite a number of artifacts.  When lines are drawn
 between points, where they overlap the points the line becomes
 white. Moreover, if two lines or points overlap completely, they
 disappear.
 <p>
 This class is abstract, so it must be used by creating a derived
 class.  To use it, create a derived class with an
 addPoints() method. Your class may also set graph parameters like
 titles and axis labels in the constructor by calling
 methods in the Plot or PlotBox classes (both of which are base classes).
 The addPoints() method should call addPoint() of the Plot base
 class to dynamically add points to the plot.  This method is called
 within a thread separate from the applet thread, so the zooming
 mechanism and buttons remain live.

 @author Edward A. Lee, Christopher Brooks, Contributor: Jeff Lane
 @version $Id$
 @since Ptolemy II 0.2
 @Pt.ProposedRating Yellow (cxh)
 @Pt.AcceptedRating Yellow (cxh)
 */
@SuppressWarnings("serial")
public abstract class PlotLive extends Plot implements Runnable {
    ///////////////////////////////////////////////////////////////////
    ////                         public methods                    ////

    /** Redefine in derived classes to add points to the plot.
     *  Adding many points at once will make the plot somewhat faster
     *  because the thread yields between calls to this method.
     *  However, the plot will also be somewhat less responsive to user
     *  inputs such as zooming, filling, or stopping.  In the derived-class
     *  implementation, this method should probably be synchronized.
     *
     *  <p>Jeff Lane points out that if the derived class version of
     *  addPoints() does not return quickly, and it seems like then you
     *  may want to experiment with addPoints() to not being synchronized.
     */
    public abstract void addPoints();

    /** Make start and stop buttons.
     *  This method is deprecated.  Use setButtons() instead.
     *  @deprecated
     */
    @Deprecated
    public void makeButtons() {
        if (_startButton == null) {
            _startButton = new JButton("start");
            _startButton.addActionListener(new StartButtonListener());
            add(_startButton);
        }

        _startButton.setVisible(true);

        if (_stopButton == null) {
            _stopButton = new JButton("stop");
            _stopButton.addActionListener(new StopButtonListener());
            add(_stopButton);
        }

        _stopButton.setVisible(true);
        _stopButton.setEnabled(false);
        _startButton.setEnabled(true);
    }

    /** Pause the plot.  To resume, call start().
     */
    public void pause() {
        _paused = true;
        _plotting = false;
        _stopButton.setEnabled(false);
        _startButton.setEnabled(true);
    }

    /** This is the body of a thread that repeatedly calls addPoints()
     *  if the plot is active.  To make the plot active, call start().
     *  To pause the plot, call pause().  To stop the plot and destroy
     *  the thread, call stop().  The next time start() is called, a new
     *  thread will be started. Between calls to addPoints(), this method calls
     *  Thread.yield() so that the thread does not hog all
     *  the resources.  This somewhat slows down execution, so derived
     *  classes may wish to plot quite a few points in their
     *  addPoints() method, if possible.  However,
     *  plotting more points at once may also decrease the
     *  responsiveness of the user interface.
     */
    @Override
    public void run() {
        while (_plotting || _paused) {
            if (_plotting) {
                addPoints();

                // Give the event thread a chance.
                Thread.yield();
            } else if (_paused) {
                // NOTE: Cannot synchronize this entire method because then
                // the Thread.yield() call above does not yield to any
                // synchronized methods (like _drawPlot()).
                synchronized (this) {
                    try {
                        wait();
                    } catch (InterruptedException e) {
                    }
                }
            }
        }
    }

    /** If the argument is true, make a start, stop, and fill button
     *  visible at the upper right.  Otherwise, make the buttons invisible.
     *  NOTE: The buttons may infringe on the title space,
     *  if the title is long.  In an application, it is preferable to provide
     *  a menu with the commands.  This way, when printing the plot,
     *  the printed plot will not have spurious buttons.  Thus, this method
     *  should be used only by applets, which normally do not have menus.
     */
    @Override
    public void setButtons(boolean visible) {
        super.setButtons(visible);

        if (_startButton == null) {
            _startButton = new JButton("start");
            _startButton.addActionListener(new StartButtonListener());
            add(_startButton);
        }

        _startButton.setVisible(visible);

        if (_stopButton == null) {
            _stopButton = new JButton("stop");
            _stopButton.addActionListener(new StopButtonListener());
            add(_stopButton);
        }

        _stopButton.setVisible(visible);

        if (visible) {
            _stopButton.setEnabled(false);
            _startButton.setEnabled(true);
        }
    }

    /** Make the plot active.  Start a new thread if necessary.
     */
    public synchronized void start() {
        _plotting = true;
        _paused = false;
        if (_stopButton != null) {
            _stopButton.setEnabled(true);
        }
        if (_startButton != null) {
            _startButton.setEnabled(false);
        }
        if (_plotLiveThread == null) {
            _plotLiveThread = new Thread(this, "PlotLive Thread");
            _plotLiveThread.start();
        } else {
            // synchronized (this) { is useless since the method is already
            // synchronized.
            // synchronized (this) {
            notifyAll();
            //}
        }
    }

    /** Stop the plot.  The plot thread exits.  This should be called by
     *  an applet's stop() method.
     */
    public void stop() {
        _plotting = false;
        _paused = false;

        // FindBugs: [M M IS] Inconsistent synchronization [IS2_INCONSISTENT_SYNC]
        // Actually this is not an issue, since once the thread has been created this
        // member is not accessed until its destruction.
        _plotLiveThread = null;
    }

    ///////////////////////////////////////////////////////////////////
    ////                         private variables                 ////

    /** @serial Thread of this plotter */
    private Thread _plotLiveThread = null;

    /** @serial True if we are actually plotting. */
    private boolean _plotting = false;

    /** @serial True if we are paused. */
    private boolean _paused = false;

    /** @serial Start and Stop Buttons. */
    private JButton _startButton;

    /** @serial Start and Stop Buttons. */
    private JButton _stopButton;

    ///////////////////////////////////////////////////////////////////
    ////                         inner classes                     ////
    class StartButtonListener implements ActionListener {
        @Override
        public void actionPerformed(ActionEvent event) {
            start();
        }
    }

    // Despite the name, the stop button calls pause.
    class StopButtonListener implements ActionListener {
        @Override
        public void actionPerformed(ActionEvent event) {
            pause();
        }
    }
}