/**
 * Copyright 2010, 2011 Jingjing Li.
 *
 * This file is part of jplot2d.
 *
 * jplot2d 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 3 of the
 * License, or any later version.
 *
 * jplot2d 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 General Lesser Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with jplot2d. If not, see .
 */
package org.jplot2d.layout;

import java.awt.geom.Dimension2D;

import org.jplot2d.element.impl.PlotEx;

/**
 * The interface to layout a plot. All methods of LayoutDirector will be called inside the plot
 * engine. User should never call them directly. Every plot should have its own LayoutDirector.
 * Re-using a LayoutDirector among multiple plot is not recommended. Re-using a LayoutDirector by
 * plots in different environment will fail due to thread problem.
 * 

 * A plot's subplots are laid out in the content area. All layers in a plot are stacked over and
 * have the same size of the content area.
 * 

 * The axis is a special component. Its length can be set when laid out, but its height is fixed and
 * derived from its internal status, such as tick height and labels.
 * 

 * The layout director has 2 working mode.
 * 

 * 
For root plot, the size is known, and the content size will be decided by layout director
 * 
For subplot, the content constraint has been set by its container's layout director. The
 * content size will be the constraint, and size is calculated by layout director
 * 
 * 
 * @author Jingjing Li
 * 
 */
public interface LayoutDirector {

	/**
	 * Returns the constraint for the given plot.
	 * 
	 * @param plot
	 *            The plot
	 * @return The constraint
	 */
	public Object getConstraint(PlotEx plot);

	/**
	 * Sets the constraint for the given plot.
	 * 
	 * @param plot
	 * @param constraint
	 */
	public void setConstraint(PlotEx plot, Object constraint);

	/**
	 * Removes the given child from this layout.
	 * 
	 * @param plot
	 */
	public void remove(PlotEx plot);

	/**
	 * Invalidates the layout, indicating that if the layout manager has cached information it
	 * should be discarded.
	 * 
	 * @param plot
	 *            the plot has been invalidate.
	 */
	public void invalidateLayout(PlotEx plot);

	/**
	 * Layout the plot. Normally the plot contents size is calculated by subtracting margin from
	 * plot size. If the plot has contents size constraint, the plot size is calculated by adding
	 * margin to plot content size.
	 */
	public void layout(PlotEx plot);

	/**
	 * Returns the preferred size of the given plot.
	 * 
	 * @param plot
	 *            The plot
	 * @return The preferred size
	 */
	public Dimension2D getPreferredSize(PlotEx plot);

	public Dimension2D getPreferredContentSize(PlotEx plot);

}