/*******************************************************************************
 * Copyright (c) 2000, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.wizard;

import org.eclipse.jface.operation.IRunnableContext;
import org.eclipse.swt.widgets.Shell;

/**
 * Interface for containers that can host a wizard. It displays
 * wizard pages, at most one of which is considered
 * the current page. <code>getCurrentPage</code> returns the
 * current page; <code>showPage</code> programmatically changes the
 * the current page. Note that the pages need not all belong
 * to the same wizard.
 * <p>
 * The class <code>WizardDialog</code> provides a fully functional
 * implementation of this interface which will meet the needs of
 * most clients. However, clients are also free to implement this
 * interface if <code>WizardDialog</code> does not suit their needs.
 * </p>
 * <p>
 * Implementors are responsible for disposing of their wizards.
 * </p>
 *
 * @see org.eclipse.jface.wizard.IWizardContainer2
 */
public interface IWizardContainer extends IRunnableContext {
	/**
	 * Returns the current wizard page for this container.
	 *
	 * @return the current wizard page, or <code>null</code> if the container
	 *   is not yet showing the wizard
	 * @see #showPage
	 */
	public IWizardPage getCurrentPage();

	/**
	 * Returns the shell for this wizard container.
	 *
	 * @return the shell, or <code>null</code> if this wizard
	 *   container does not have a shell
	 */
	public Shell getShell();

	/**
	 * Makes the given page visible.
	 * <p>
	 * This method should not be use for normal page
	 * sequencing (back, next) which is handled by the
	 * container itself. It may, however, be used to
	 * move to another page in response to some custom
	 * action such as double clicking in a list.
	 * </p>
	 *
	 * @param page the page to show
	 * @see #getCurrentPage
	 */
	public void showPage(IWizardPage page);

	/**
	 * Adjusts the enable state of the Back, Next, and Finish
	 * buttons to reflect the state of the currently active
	 * page in this container.
	 * <p>
	 * This method is called by the container itself
	 * when its wizard page changes and may be called
	 * by the page at other times to force a button state
	 * update.
	 * </p>
	 */
	public void updateButtons();

	/**
	 * Updates the message (or error message) shown in the message line to
	 * reflect the state of the currently active page in this container.
	 * <p>
	 * This method is called by the container itself
	 * when its wizard page changes and may be called
	 * by the page at other times to force a message
	 * update.
	 * </p>
	 */
	public void updateMessage();

	/**
	 * Updates the title bar (title, description, and image) to
	 * reflect the state of the currently active page in this container.
	 * <p>
	 * This method is called by the container itself
	 * when its wizard page changes and may be called
	 * by the page at other times to force a title bar
	 * update.
	 * </p>
	 */
	public void updateTitleBar();

	/**
	 * Updates the window title to reflect the state of the current wizard.
	 * <p>
	 * This method is called by the container itself
	 * when its wizard changes and may be called
	 * by the wizard at other times to force a window
	 * title change.
	 * </p>
	 */
	public void updateWindowTitle();
}
