/*
 *  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.
 * 

 * Implementations may limit the range of the underlying Chart2D's data
 * (clipping / zooming), increase it (void space offset), guarantee a minimum
 * viewport... .
 * 

 * 
 * 
Property Change events
 * 

 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
property
oldValue
newValue
occurrence
{@link #PROPERTY_RANGE}
{@link info.monitorenter.util.Range} that changed
{@link info.monitorenter.util.Range}, the new value
Fired if any bound of the range changed (min or max).
{@link #PROPERTY_RANGE_MAX}
{@link java.lang.Double}, the old max value of the
 * range. 
{@link info.monitorenter.util.Range}, the new max value
 * of the range. 
{@link #PROPERTY_RANGE_MIN}
{@link java.lang.Double}, the old min value of the
 * range. 
{@link info.monitorenter.util.Range}, the new min value
 * of the range. 

 * 

 * 
 * @author Achim Westermann 
 * 
 * @version $Revision: 1.9 $
 * 
 * @see info.monitorenter.gui.chart.axis.AAxis
 */
public interface IRangePolicy extends Serializable {
  /**
   * The property key defining a change of the min or the
   * max property.
   * 

   * Use in combination with
   * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
   * 

   */
  public static final String PROPERTY_RANGE = "IRangePolicy.PROPERTY_RANGE";

  /**
   * The property key defining the max property.
   * 

   * Use in combination with
   * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
   * 

   */
  public static final String PROPERTY_RANGE_MAX = "IRangePolicy.PROPERTY_RANGE";

  /**
   * The property key defining the min property.
   * 

   * Use in combination with
   * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
   * 

   */
  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 propertyName.
   * 

   * 
   * @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 propertyName 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);

  /**
   * 

   * Returns all property change listeners for the given property.
   * 
   * 
   * @param property
   *          one of the constants with teh PROPERTY_ 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.
   * 

   * 
   * @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.
   * 

   * 
   * @param listener
   *          a listener that will only be informed if the property identified
   *          by the argument propertyName changes
   * 
   * @param property
   *          the property the listener was registered to.
   */
  public void removePropertyChangeListener(PropertyChangeListener listener, final String property);

  /**
   * 

   * Removes a property change listener for listening on the given property.
   * 
   * 
   * @param property
   *          one of the constants with teh PROPERTY_ 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.
   * 

   * 
   * @param range
   *          the Range for the range policy.
   */
  public void setRange(Range range);
}