package jas.util;
import java.awt.Container;
import java.awt.event.KeyEvent;
import java.awt.event.KeyListener;

import javax.swing.JPanel;

/**
 * Extend this class to create a page for the JASWizard.  Implement the
 * interface HasNextPages if you want there to be pages following this
 * page, and implement the Finishable interface if you want this to be
 * the final page.  You may implement one or both, but implementing
 * neither would be silly because then neither the "Next" nor "Finish"
 * button will enable and your page will be a "dead end".  Implement
 * HasHelpPage if you want your page to link to a help topic.  Override
 * the methods <code>getNextEnabled()</code> and <code>getFinishEnabled()</code>
 * to control how the "Next" and "Finish" buttons enable.
 * <p>
 * This class is a KeyListener and has implemented the interface
 * with non-final methods.  If you do not override these
 * methods, <code>doEnable()</code> will be called when a key
 * is released on components registered as KeyListeners.
 * This implementation is designed for when the buttons
 * enable when text is added to them.  For example, if you page had<br>
 * <code>
 * m_text = new JASTextField();<br>
 * text.addKeyListener(this);<br>
 * </code><br>
 * then the "Next" and "Finish" buttons would enable each time a key is released
 * in the field <code>text</code>.  You might define <code>getNextEnabled()</code>
 * as follows:<br>
 * <pre>
 * protected boolean getNextEnabled()
 * {
 *		final String s = m_text.getText();
 *		return s != null && s.length() > 0;
 * }
 * </pre>
 *  @author Jonas Gifford
 *  @see JASWizard
 *  @see HasNextPages
 *  @see Finishable
 *  @see HasHelpPage
 */
public abstract class JASWizardPage extends JPanel implements KeyListener
{
	/**
	 * Supply a layout manager for the panel to use.  See Sun's notes on
	 * <a href="http://www.javasoft.com/docs/books/tutorial/ui/layout/using.html">using
	 * layout managers</a>.  In the constructor of your subclass, add components
	 * to the page as you would add components to a regular container, using the
	 * <code>add(..)</code> methods.  It is not a good idea to use AWT components
	 * here because those heavy-weight components do not mix well with swing's
	 * light-weight components.  You should use only
	 * <a href="http://java.sun.com/products/jfc/swingdoc-api/packages.html">swing components</a>.
	 * The jas.util package has a number of
	 * <a href="http://www-sldnt.slac.stanford.edu/jas/Documentation/JASUtilClasses.htm">utility
	 * components</a> that may be useful for these pages.
	 * @param lm the layout manager to use for this page.
	 * @see java.awt.LayoutManager
	 */
	public JASWizardPage(final java.awt.LayoutManager lm)
	{
		super(lm);

		m_isFinishable = (this instanceof Finishable);
		m_hasNextPages = (this instanceof HasNextPages);
	}
	final JASWizardPage getPrev()
	{
		return m_prev;
	}
	final void addTo(final Container c, final JASWizard wizard, final JASWizardPage prev)
	{
		c.add(m_number = String.valueOf(pageNumber++), this);
		if (m_hasNextPages)
		{
			m_nextWizardPages = ((HasNextPages) this).getNextWizardPages();
			if (m_nextWizardPages != null)
				for (int i = 0; i < m_nextWizardPages.length; i++)
					if (m_nextWizardPages[i] != null)
						m_nextWizardPages[i].addTo(c, wizard, this);
		}
		m_wizard = wizard;
		m_prev = prev;
	}

	/**
	 * Override to provide customized behaviour for enabling the "Next" button.  By
	 * default, this method returns whether the page implements HasNextPages.  If
	 * your page does not implement that interface, the "Next" button will never
	 * enable.  Call <code>doEnable()</code> to call this method, or add your
	 * page as a key listener to a component, and then <code>doEnable()</code> will
	 * be called each time a key is released in that component.
	 *  @see JASWizardPage#doEnable()
	 *  @see HasNextPages
	 *  @return whether to enable the "Next" button
	 */
	protected boolean getNextEnabled()
	{
		return m_hasNextPages;
	}

	/**
	 * Override to provide customized behaviour for enabling the "Finish" button.  By
	 * default, this method returns whether the page implements Finishable.  If
	 * your page does not implement that interface, the "Finish" button will never
	 * enable.  Call <code>doEnable()</code> to call this method, or add your
	 * page as a key listener to a component, and then <code>doEnable()</code> will
	 * be called each time a key is released in that component.
	 *  @see JASWizardPage#doEnable()
	 *  @see Finishable
	 *  @return whether to enable the "Finish" button
	 */
	protected boolean getFinishEnabled()
	{
		return m_isFinishable;
	}

	/**
	 * Forces the wizard to call <code>getNextEnabled()</code> and <code>getFinishEnabled()</code> to enable the
	 * buttons on the wizard.  This method is called by the <code>keyReleased(KeyEvent)</code> method
	 * if you add this class as a KeyListener to a text field.
	 *  @see JASWizardPage#getNextEnabled()
	 *  @see JASWizardPage#getFinishEnabled()
	 *  @see JASWizardPage#keyReleased(KeyEvent)
	 *  @see java.awt.event.KeyEvent
	 *  @see java.awt.event.KeyListener
	 */
	protected void doEnable()
	{
//		if (m_wizard == null) return;
		m_wizard.setNextEnabled(getNextEnabled());
		m_wizard.setFinishEnabled(getFinishEnabled());
		m_wizard.doPrevEnabled();
		if (m_isFinishable && m_hasNextPages) m_wizard.setDefaultButton();
	}
	final void clear()
	{
		if (m_hasNextPages)
		{
			for (int i = 0; i < m_nextWizardPages.length; i++)
				if (m_nextWizardPages[i] != null)
					m_nextWizardPages[i].clear();
			m_nextWizardPages = null;
		}
		m_prev = null;
		m_wizard = null;
	}

	/** This method is public as an implementation side effect; do not call. */
	public String toString()
	{
		return m_number;
	}

	/** Call to dispose the wizard (i.e., to have it close). */
	protected void dispose()
	{
		m_wizard.dispose();
	}
	final void doCancel() // preorder tree trversal
	{
		if (m_nextWizardPages != null)
			for (int i = 0; i < m_nextWizardPages.length; i++)
				if (m_nextWizardPages[i] != null)
					m_nextWizardPages[i].doCancel();
		onCancel();
	}

	/**
	 * This method is called if the user has canceled the wizard.  By default it does nothing,
	 * but you can override it to perform cleanup if necessary.  The wizard follows a preorder
	 * tree traversal, so the <code>onCancel()</code> methods are called starting from the bottom
	 * and working up each branch separately to the root.
	 */
	public void onCancel()
	{
	}

	/** Override this to provide your own behaviour for key events; does nothing by default. */
	public void keyPressed(final KeyEvent e) {}

	/**
	 * If you add this class as a KeyListener and don't override this method then
	 * the buttons will be enabled on every key event in the definition for this method.
	 */
	public void keyReleased(final KeyEvent e)
	{
		if (e.getKeyCode() != KeyEvent.VK_ENTER) doEnable();
	}
	final boolean isFinishable()
	{
		return m_isFinishable;
	}
	final boolean hasNextPages()
	{
		return m_hasNextPages;
	}

	/**
	 * This method is called just before the page is brought to the screen.  By default, it
	 * does nothing but you can override it to do some last-minute setup on your page.
	 */
	public void beforeShowing()
	{
	}
	public void doBusy(Runnable run)
	{
		m_wizard.setToWaitCursor();
		try
		{
			run.run();
		}
		finally 
		{
			m_wizard.setToDefaultCursor();
		}
	}
	protected void handleError(String message, Throwable t)
   {
      m_wizard.handleError(message,t);
   }
	/** Override this to provide your own behaviour for key events; does nothing by default. */
	public void keyTyped(final KeyEvent e) {}
	private JASWizardPage m_prev = null;
	private JASWizard m_wizard;
	private JASWizardPage[] m_nextWizardPages = null;
	private final boolean m_isFinishable, m_hasNextPages;
	static int pageNumber = 0;
	private String m_number;
}