/******************************************************************************* * Copyright (c) 2000, 2017 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.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. *
* A tab has the following lifecycle methods: *
setLaunchConfigurationDialog(ILaunchConfigurationDialog)
-
* this is the first method called on a tab after it is instantiated.initializeFrom(ILaunchConfiguration)
- called when a
* launch configuration is selected to be displayed.activated(ILaunchConfigurationWorkingCopy)
- called when
* a tab is entered.deactivated(ILaunchConfigurationWorkingCopy)
- called when
* a tab is exited.performApply(ILaunchConfigurationWorkingCopy)
- called when
* a tab is to write its values to a launch configuration.dispose()
- 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.setDefaults(ILaunchConfigurationWorkingCopy)
* can be called before a tab's controls are created.
*
* 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 activated
and deactivated
* allow tabs to determine the appropriate course of action. The default implementation
* in AbstractLaunchConfigurationTab
is to call the old methods
* (initializeFrom
and performApply
). Tabs should override
* the new methods as required.
*
* This interface is intended to be implemented by clients. *
* @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, aftersetLaunchConfigurationDialog
* is called.
*
* Implementors are responsible for ensuring that
* the created control can be accessed via getControl
*
* May return null
if the control
* has not been created yet.
*
null
*/
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
*/
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
*/
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.
*/
void dispose();
/**
* Copies values from this tab into the given
* launch configuration.
*
* @param configuration launch configuration
*/
void performApply(ILaunchConfigurationWorkingCopy configuration);
/**
* Returns the current error message for this tab.
* May be null
to indicate no error message.
* * An error message should describe some error state, * as opposed to a message which may simply provide instruction * or information to the user. *
* * @return the error message, ornull
if none
*/
String getErrorMessage();
/**
* Returns the current message for this tab.
* * A message provides instruction or information to the * user, as opposed to an error message which should * describe some error state. *
* * @return the message, ornull
if none
*/
String getMessage();
/**
* Returns whether this tab is in a valid state in the context of the specified launch configuration.
* * This information is typically used by the launch configuration * dialog to decide when it is okay to launch. *
* * @param launchConfig launch configuration which provides context for validating this tab. * This value must not benull
.
*
* @return whether this tab is in a valid state
*/
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 isValid()
in that canSave()
* determines if this tab prevents the current launch configuration from being saved, whereas
* isValid()
determines if this tab prevents the current launch configuration from
* being launched.
*
* * This information is typically used by the launch configuration * dialog to decide when it is okay to save a launch configuration. *
* * @return whether this tab is in a state that allows the current launch configuration to be saved */ 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 */ 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 void launched(ILaunch launch); /** * Returns the name of this tab. * * @return the name of this tab */ String getName(); /** * Returns the image for this tab, ornull
if none
*
* @return the image for this tab, or null
if none
*/
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
*/
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
*/
void deactivated(ILaunchConfigurationWorkingCopy workingCopy);
/**
* Checks if it is OK to leave the Tab.
*
* @return true
if OK to leave the tab or false
* @since 3.12
*/
default boolean OkToLeaveTab() {
return true;
}
/**
* Perform the changes after apply.
*
* @since 3.12
*/
default void postApply() {
}
}