1 /******************************************************************************* 2 * Copyright (c) 2000, 2013 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.debug.ui; 15 16 17 import org.eclipse.debug.core.ILaunch; 18 import org.eclipse.debug.core.ILaunchConfiguration; 19 import org.eclipse.debug.core.ILaunchConfigurationWorkingCopy; 20 21 /** 22 * A launch configuration tab group is used to edit/view attributes of a 23 * specific type of launch configuration. Launch configurations are presented in 24 * a dialog, with a tab folder. Each tab manipulates one or more attributes of a 25 * launch configuration. The tab group controls which tabs are displayed for a 26 * specific type of launch configuration, and provides a mechanism for 27 * overriding configuration initialization performed by tabs. 28 * <p> 29 * A tab group has the following lifecycle methods: 30 * </p> 31 * <ul> 32 * <li><code>createTabs(ILaunchConfigurationDialog, String)</code> - this is the 33 * first method called on a tab group after it is instantiated.</li> 34 * <li><code>initializeFrom(ILaunchConfiguration)</code> - called when a launch 35 * configuration is selected to be displayed.</li> 36 * <li><code>performApply(ILaunchConfigurationWorkingCopy)</code> - called when 37 * a tab group's values are to be written to a launch configuration.</li> 38 * <li><code>dispose()</code> - the last method called on a tab group, when it 39 * is to perform any required cleanup. Note that a tab can be disposed before 40 * its control has been created.</li> 41 * </ul> 42 * <p> 43 * The method <code>setDefaults(ILaunchConfigurationWorkingCopy)</code> can be 44 * called before a tab's controls are created. 45 * </p> 46 * <p> 47 * The launch tab framework was originally designed to handle inter tab 48 * communication by applying attributes from the active tab to a launch 49 * configuration being edited, when a tab is exited, and by initializing a tab 50 * when activated. In 3.0, the addition of the methods <code>activated</code> 51 * and <code>deactivated</code> allow tabs to determine the appropriate course 52 * of action. The default implementation in 53 * <code>AbstractLaunchConfigurationTab</code> is to call the old methods 54 * (<code>initializeFrom</code> and <code>performApply</code>). Tabs should 55 * override the new methods as required. 56 * </p> 57 * <p> 58 * A launch configuration group extension is defined in <code>plugin.xml</code>. 59 * Following is an example definition of a launch configuration group extension. 60 * </p> 61 * 62 * <pre> 63 * <extension point="org.eclipse.debug.ui.launchConfigurationTabGroups"> 64 * <launchConfigurationTabGroup 65 * id="com.example.ExampleTabGroup" 66 * type="com.example.ExampleLaunchConfigurationTypeIdentifier" 67 * class="com.example.ExampleLaunchConfigurationTabGroupClass"> 68 * </launchConfigurationTabGroup> 69 * </extension> 70 * </pre> 71 * 72 * The attributes are specified as follows: 73 * <ul> 74 * <li><code>id</code> specifies a unique identifier for this launch 75 * configuration tab group.</li> 76 * <li><code>type</code> specifies launch configuration type that this tab group 77 * is applicable to (corresponds to the id of a launch configuration type 78 * extension).</li> 79 * <li><code>class</code> specifies a fully qualified name of a Java class that 80 * implements <code>ILaunchConfigurationTabGroup</code>.</li> 81 * </ul> 82 * <p> 83 * This interface is intended to be implemented by clients. 84 * </p> 85 * 86 * @see org.eclipse.debug.core.ILaunchConfigurationType 87 * @see org.eclipse.debug.core.ILaunchConfiguration 88 * @see org.eclipse.debug.ui.ILaunchConfigurationTab 89 * @since 2.0 90 */ 91 public interface ILaunchConfigurationTabGroup { 92 93 /** 94 * Creates the tabs contained in this tab group for the specified 95 * launch mode. The tabs control's are not created. This is the 96 * fist method called in the lifecycle of a tab group. 97 * 98 * @param dialog the launch configuration dialog this tab group 99 * is contained in 100 * @param mode the mode the launch configuration dialog was 101 * opened in 102 */ createTabs(ILaunchConfigurationDialog dialog, String mode)103 void createTabs(ILaunchConfigurationDialog dialog, String mode); 104 105 /** 106 * Returns the tabs contained in this tab group. 107 * 108 * @return the tabs contained in this tab group 109 */ getTabs()110 ILaunchConfigurationTab[] getTabs(); 111 112 /** 113 * Notifies this launch configuration tab group that it has 114 * been disposed, and disposes this group's tabs. Marks the end 115 * of this tab group's lifecycle, allowing this tab group to 116 * perform any cleanup required. 117 */ dispose()118 void dispose(); 119 120 /** 121 * Initializes the given launch configuration with 122 * default values for this tab group. This method 123 * is called when a new launch configuration is created 124 * such that the configuration can be initialized with 125 * meaningful values. This method may be called before 126 * tab controls are created. 127 * 128 * @param configuration launch configuration 129 */ setDefaults(ILaunchConfigurationWorkingCopy configuration)130 void setDefaults(ILaunchConfigurationWorkingCopy configuration); 131 132 /** 133 * Initializes this group's tab controls with values from the given 134 * launch configuration. This method is called when 135 * a configuration is selected to view or edit. 136 * 137 * @param configuration launch configuration 138 */ initializeFrom(ILaunchConfiguration configuration)139 void initializeFrom(ILaunchConfiguration configuration); 140 141 /** 142 * Copies values from this group's tabs into the given 143 * launch configuration. 144 * 145 * @param configuration launch configuration 146 */ performApply(ILaunchConfigurationWorkingCopy configuration)147 void performApply(ILaunchConfigurationWorkingCopy configuration); 148 149 /** 150 * Notifies this tab that a configuration has been 151 * launched, resulting in the given launch. This method can be 152 * called when a tab's control does not exist, to support single-click 153 * launching. 154 * 155 * @param launch the result of launching the current 156 * launch configuration 157 * @deprecated As of R3.0, this method is no longer called by the launch 158 * framework. Since tabs do not exist when launching is performed elsewhere 159 * than the launch dialog, this method cannot be relied upon for launching 160 * functionality. 161 */ launched(ILaunch launch)162 @Deprecated void launched(ILaunch launch); 163 } 164 165