/*
 *  IRangePolicy.java of project jchart2d. Interface for viewport policies. 
 *  Copyright (C) 2004 - 2011 Achim Westermann.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 * 
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 * 
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 *
 *  If you modify or optimize the code in a useful way please let me know.
 *  Achim.Westermann@gmx.de
 *
 */
package info.monitorenter.gui.chart;

import info.monitorenter.util.Range;

import java.beans.PropertyChangeListener;
import java.io.Serializable;

/**
 * An interface that allows an axis to be plugged with a range policy.
 * <p>
 * Implementations may limit the range of the underlying Chart2D's data
 * (clipping / zooming), increase it (void space offset), guarantee a minimum
 * viewport... .
 * <p>
 * 
 * <h3>Property Change events</h3>
 * <p>
 * <table border="0">
 * <tr>
 * <th><code>property</code></th>
 * <th><code>oldValue</code></th>
 * <th><code>newValue</code></th>
 * <th>occurrence</th>
 * </tr>
 * <tr>
 * <td><code>{@link #PROPERTY_RANGE}</code></td>
 * <td><code>{@link info.monitorenter.util.Range}</code> that changed</td>
 * <td><code>{@link info.monitorenter.util.Range}</code>, the new value</td>
 * <td>Fired if any bound of the range changed (min or max).</td>
 * </tr>
 * <tr>
 * <tr>
 * <td><code>{@link #PROPERTY_RANGE_MAX}</code></td>
 * <td><code>{@link java.lang.Double}</code>, the old max value of the
 * range. </td>
 * <td><code>{@link info.monitorenter.util.Range}</code>, the new max value
 * of the range. </td>
 * <td></td>
 * </tr>
 * <tr>
 * <td><code>{@link #PROPERTY_RANGE_MIN}</code></td>
 * <td><code>{@link java.lang.Double}</code>, the old min value of the
 * range. </td>
 * <td><code>{@link info.monitorenter.util.Range}</code>, the new min value
 * of the range. </td>
 * <td></td>
 * </tr>
 * </table>
 * <p>
 * 
 * @author <a href="mailto:Achim.Westermann@gmx.de">Achim Westermann </a>
 * 
 * @version $Revision: 1.9 $
 * 
 * @see info.monitorenter.gui.chart.axis.AAxis
 */
public interface IRangePolicy extends Serializable {
  /**
   * The property key defining a change of the <code>min</code> or the
   * <code>max</code> property.
   * <p>
   * Use in combination with
   * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
   * <p>
   */
  public static final String PROPERTY_RANGE = "IRangePolicy.PROPERTY_RANGE";

  /**
   * The property key defining the <code>max</code> property.
   * <p>
   * Use in combination with
   * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
   * <p>
   */
  public static final String PROPERTY_RANGE_MAX = "IRangePolicy.PROPERTY_RANGE";

  /**
   * The property key defining the <code>min</code> property.
   * <p>
   * Use in combination with
   * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
   * <p>
   */
  public static final String PROPERTY_RANGE_MIN = "IRangePolicy.PROPERTY_RANGE";

  /**
   * Registers a property change listener that will be informed about changes of
   * the property identified by the given <code>propertyName</code>.
   * <p>
   * 
   * @param propertyName
   *          the name of the property the listener is interested in
   * 
   * @param listener
   *          a listener that will only be informed if the property identified
   *          by the argument <code>propertyName</code> changes
   * 
   * 
   */
  public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener);

  /**
   * Define the upper bound of the Chart2D's value range. Depends on the
   * {@link info.monitorenter.gui.chart.axis.AAxis} this instance is bound to.
   * 
   * @param chartMin
   *          the minimum value of the connected Chart2D that may / should be
   *          taken into account.
   * 
   * @param chartMax
   *          the maximum value of the connected Chart2D that may / should be
   *          taken into account.
   * 
   * @return the maximum value (upper bound) for the Chart2D to display.
   * 
   */
  public double getMax(double chartMin, double chartMax);

  /**
   * Define the lower bound of the Chart2D's value range. Depends on the
   * {@link info.monitorenter.gui.chart.axis.AAxis} this instance is bound to.
   * 
   * @param chartMin
   *          the minimum value of the connected Chart2D that may / should be
   *          taken into account.
   * 
   * @param chartMax
   *          the maximum value of the connected Chart2D that may / should be
   *          taken into account.
   * 
   * @return the minimum value (lower bound) for the Chart2D to display.
   * 
   */
  public double getMin(double chartMin, double chartMax);

  /**
   * <p>
   * Returns all property change listeners for the given property.
   * </p>
   * 
   * @param property
   *          one of the constants with teh <code>PROPERTY_</code> prefix
   *          defined in this class or subclasses.
   * 
   * @return the property change listeners for the given property.
   */
  public PropertyChangeListener[] getPropertyChangeListeners(String property);

  /**
   * Get the range of this range policy.
   * <p>
   * 
   * @return he range of this range policy
   */
  public Range getRange();

  /**
   * Deregisters a property change listener that has been registerd for
   * listening on the given property.
   * <p>
   * 
   * @param listener
   *          a listener that will only be informed if the property identified
   *          by the argument <code>propertyName</code> changes
   * 
   * @param property
   *          the property the listener was registered to.
   */
  public void removePropertyChangeListener(PropertyChangeListener listener, final String property);

  /**
   * <p>
   * Removes a property change listener for listening on the given property.
   * </p>
   * 
   * @param property
   *          one of the constants with teh <code>PROPERTY_</code> prefix
   *          defined in this class or subclasses.
   * 
   * @param listener
   *          the listener for this property change.
   */
  public void removePropertyChangeListener(String property, PropertyChangeListener listener);

  /**
   * Set the range of this RangePolicy.
   * <p>
   * 
   * @param range
   *          the Range for the range policy.
   */
  public void setRange(Range range);
}