/*******************************************************************************
 * Copyright (c) 2000, 2013 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.debug.ui;


import org.eclipse.debug.core.ILaunch;
import org.eclipse.debug.core.ILaunchConfiguration;
import org.eclipse.debug.core.ILaunchConfigurationWorkingCopy;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;

/**
 * A launch configuration tab is used to edit/view attributes
 * of a specific type of launch configuration. Launch
 * configurations are presented in a dialog, with a tab folder.
 * Each tab manipulates one ore more attributes of a launch
 * configuration.
 * <p>
 * A tab has the following lifecycle methods:
 * <ul>
 * <li><code>setLaunchConfigurationDialog(ILaunchConfigurationDialog)</code> -
 *  this is the first method called on a tab after it is instantiated.</li>
 * <li><code>initializeFrom(ILaunchConfiguration)</code> - called when a
 *  launch configuration is selected to be displayed.</li>
 * <li><code>activated(ILaunchConfigurationWorkingCopy)</code> - called when
 *  a tab is entered.</li>
 * <li><code>deactivated(ILaunchConfigurationWorkingCopy)</code> - called when
 *  a tab is exited.</li>
 * <li><code>performApply(ILaunchConfigurationWorkingCopy)</code> - called when
 *  a tab is to write its values to a launch configuration.</li>
 * <li><code>dispose()</code> - the last method called on a tab, when it is
 *  to perform any required cleanup. Note that a tab can be disposed before its control
 * has been created.</li>
 * </ul>
 * The method <code>setDefaults(ILaunchConfigurationWorkingCopy)</code>
 * can be called before a tab's controls are created.
 * <p>
 * The launch tab framework was originally designed to handle inter tab
 * communication by applying attributes from the active tab to a launch configuration
 * being edited, when a tab is exited, and by initializing a tab when activated.
 * In 3.0, the addition of the methods <code>activated</code> and <code>deactivated</code>
 * allow tabs to determine the appropriate course of action. The default implementation
 * in <code>AbstractLaunchConfigurationTab</code> is to call the old methods
 * (<code>initializeFrom</code> and <code>performApply</code>). Tabs should override
 * the new methods as required.
 * </p>
 * <p>
 * This interface is intended to be implemented by clients.
 * </p>
 * @see org.eclipse.debug.core.ILaunchConfigurationType
 * @see org.eclipse.debug.core.ILaunchConfiguration
 * @since 2.0
 */
public interface ILaunchConfigurationTab {

	/**
	 * Creates the top level control for this launch configuration
	 * tab under the given parent composite.  This method is called once on
	 * tab creation, after <code>setLaunchConfigurationDialog</code>
	 * is called.
	 * <p>
	 * Implementors are responsible for ensuring that
	 * the created control can be accessed via <code>getControl</code>
	 * </p>
	 *
	 * @param parent the parent composite
	 */
	public void createControl(Composite parent);

	/**
	 * Returns the top level control for this tab.
	 * <p>
	 * May return <code>null</code> if the control
	 * has not been created yet.
	 * </p>
	 *
	 * @return the top level control or <code>null</code>
	 */
	public Control getControl();

	/**
	 * Initializes the given launch configuration with
	 * default values for this tab. This method
	 * is called when a new launch configuration is created
	 * such that the configuration can be initialized with
	 * meaningful values. This method may be called before this
	 * tab's control is created.
	 *
	 * @param configuration launch configuration
	 */
	public void setDefaults(ILaunchConfigurationWorkingCopy configuration);

	/**
	 * Initializes this tab's controls with values from the given
	 * launch configuration. This method is called when
	 * a configuration is selected to view or edit, after this
	 * tab's control has been created.
	 *
	 * @param configuration launch configuration
	 */
	public void initializeFrom(ILaunchConfiguration configuration);

	/**
	 * Notifies this launch configuration tab that it has
	 * been disposed. Marks the end of this tab's lifecycle,
	 * allowing this tab to perform any cleanup required.
	 */
	public void dispose();

	/**
	 * Copies values from this tab into the given
	 * launch configuration.
	 *
	 * @param configuration launch configuration
	 */
	public void performApply(ILaunchConfigurationWorkingCopy configuration);

	/**
	 * Returns the current error message for this tab.
	 * May be <code>null</code> to indicate no error message.
	 * <p>
	 * An error message should describe some error state,
	 * as opposed to a message which may simply provide instruction
	 * or information to the user.
	 * </p>
	 *
	 * @return the error message, or <code>null</code> if none
	 */
	public String getErrorMessage();

	/**
	 * Returns the current message for this tab.
	 * <p>
	 * A message provides instruction or information to the
	 * user, as opposed to an error message which should
	 * describe some error state.
	 * </p>
	 *
	 * @return the message, or <code>null</code> if none
	 */
	public String getMessage();

	/**
	 * Returns whether this tab is in a valid state in the context of the specified launch configuration.
	 * <p>
	 * This information is typically used by the launch configuration
	 * dialog to decide when it is okay to launch.
	 * </p>
	 *
	 * @param launchConfig launch configuration which provides context for validating this tab.
	 *         This value must not be <code>null</code>.
	 *
	 * @return whether this tab is in a valid state
	 */
	public boolean isValid(ILaunchConfiguration launchConfig);

	/**
	 * Returns whether this tab is in a state that allows the launch configuration whose values
	 * this tab is showing to be saved.  This differs from <code>isValid()</code> in that <code>canSave()</code>
	 * determines if this tab prevents the current launch configuration from being saved, whereas
	 * <code>isValid()</code> determines if this tab prevents the current launch configuration from
	 * being launched.
	 *
	 * <p>
	 * This information is typically used by the launch configuration
	 * dialog to decide when it is okay to save a launch configuration.
	 * </p>
	 *
	 * @return whether this tab is in a state that allows the current launch configuration to be saved
	 */
	public boolean canSave();

	/**
	 * Sets the launch configuration dialog that hosts this tab.
	 * This is the first method called on a launch configuration
	 * tab, and marks the beginning of this tab's lifecycle.
	 *
	 * @param dialog launch configuration dialog
	 */
	public void setLaunchConfigurationDialog(ILaunchConfigurationDialog dialog);

	/**
	 * Notifies this tab that the specified configuration has been
	 * launched, resulting in the given launch. This method can be
	 * called when a tab's control does not exist, to support single-click
	 * launching.
	 *
	 * @param launch the result of launching the current
	 *  launch configuration
	 * @deprecated As of R3.0, this method is no longer called by the launch
	 *  framework. Since tabs do not exist when launching is performed elsewhere
	 *  than the launch dialog, this method cannot be relied upon for launching
	 *  functionality.
	 */
	@Deprecated
	public void launched(ILaunch launch);

	/**
	 * Returns the name of this tab.
	 *
	 * @return the name of this tab
	 */
	public String getName();

	/**
	 * Returns the image for this tab, or <code>null</code> if none
	 *
	 * @return the image for this tab, or <code>null</code> if none
	 */
	public Image getImage();

	/**
	 * Notification that this tab has become the active tab in the launch
	 * configuration dialog.
	 *
	 * @param workingCopy the launch configuration being edited
	 * @since 3.0
	 */
	public void activated(ILaunchConfigurationWorkingCopy workingCopy);

	/**
	 * Notification that this tab is no longer the active tab in the launch
	 * configuration dialog.
	 *
	 * @param workingCopy the launch configuration being edited
	 * @since 3.0
	 */
	public void deactivated(ILaunchConfigurationWorkingCopy workingCopy);
}