ILaunchConfigurationTab


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.debug.ui;
12  
13  
14  import org.eclipse.debug.core.ILaunch;
15  import org.eclipse.debug.core.ILaunchConfiguration;
16  import org.eclipse.debug.core.ILaunchConfigurationWorkingCopy;
17  import org.eclipse.swt.graphics.Image;
18  import org.eclipse.swt.widgets.Composite;
19  import org.eclipse.swt.widgets.Control;
20   
21  /**
22   * A launch configuration tab is used to edit/view attributes
23   * of a specific type of launch configuration. Launch
24   * configurations are presented in a dialog, with a tab folder.
25   * Each tab manipulates one ore more attributes of a launch
26   * configuration. 
27   * <p>
28   * A tab has the following lifecycle methods:
29   * <ul>
30   * <li><code>setLaunchConfigurationDialog(ILaunchConfigurationDialog)</code> - 
31   *  this is the first method called on a tab after it is instantiated.</li>
32   * <li><code>initializeFrom(ILaunchConfiguration)</code> - called when a 
33   *  launch configuration is selected to be displayed.</li>
34   * <li><code>activated(ILaunchConfigurationWorkingCopy)</code> - called when
35   *  a tab is entered.</li>
36   * <li><code>deactivated(ILaunchConfigurationWorkingCopy)</code> - called when
37   *  a tab is exited.</li>
38   * <li><code>performApply(ILaunchConfigurationWorkingCopy)</code> - called when
39   *  a tab is to write its values to a launch configuration.</li>
40   * <li><code>dispose()</code> - the last method called on a tab, when it is
41   *  to perform any required cleanup. Note that a tab can be disposed before its control
42   * has been created.</li>
43   * </ul>
44   * The method <code>setDefaults(ILaunchConfigurationWorkingCopy)</code>
45   * can be called before a tab's controls are created.
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 configuration
49   * being edited, when a tab is exited, and by initializing a tab when activated.
50   * In 3.0, the addition of the methods <code>activated</code> and <code>deactivated</code>
51   * allow tabs to determine the appropriate course of action. The default implementation
52   * in <code>AbstractLaunchConfigurationTab</code> is to call the old methods
53   * (<code>initializeFrom</code> and <code>performApply</code>). Tabs should override
54   * the new methods as required.
55   * </p>
56   * <p>
57   * This interface is intended to be implemented by clients.
58   * </p>
59   * @see org.eclipse.debug.core.ILaunchConfigurationType
60   * @see org.eclipse.debug.core.ILaunchConfiguration
61   * @since 2.0
62   */
63  public interface ILaunchConfigurationTab {
64  
65      /**
66       * Creates the top level control for this launch configuration
67       * tab under the given parent composite.  This method is called once on
68       * tab creation, after <code>setLaunchConfigurationDialog</code>
69       * is called.
70       * <p>
71       * Implementors are responsible for ensuring that
72       * the created control can be accessed via <code>getControl</code>
73       * </p>
74       *
75       * @param parent the parent composite
76       */
77      public void createControl(Composite parent);
78      
79      /**
80       * Returns the top level control for this tab.
81       * <p>
82       * May return <code>null</code> if the control
83       * has not been created yet.
84       * </p>
85       *
86       * @return the top level control or <code>null</code>
87       */
88      public Control getControl();    
89      
90      /**
91       * Initializes the given launch configuration with
92       * default values for this tab. This method
93       * is called when a new launch configuration is created
94       * such that the configuration can be initialized with
95       * meaningful values. This method may be called before this
96       * tab's control is created.
97       * 
98       * @param configuration launch configuration
99       */
100     public void setDefaults(ILaunchConfigurationWorkingCopy configuration); 
101     
102     /**
103      * Initializes this tab's controls with values from the given
104      * launch configuration. This method is called when
105      * a configuration is selected to view or edit, after this
106      * tab's control has been created.
107      * 
108      * @param configuration launch configuration
109      */
110     public void initializeFrom(ILaunchConfiguration configuration);     
111     
112     /**
113      * Notifies this launch configuration tab that it has
114      * been disposed. Marks the end of this tab's lifecycle,
115      * allowing this tab to perform any cleanup required.
116      */
117     public void dispose();
118     
119     /**
120      * Copies values from this tab into the given 
121      * launch configuration.
122      * 
123      * @param configuration launch configuration
124      */
125     public void performApply(ILaunchConfigurationWorkingCopy configuration);
126     
127     /**
128      * Returns the current error message for this tab.
129      * May be <code>null</code> to indicate no error message.
130      * <p>
131      * An error message should describe some error state,
132      * as opposed to a message which may simply provide instruction
133      * or information to the user.
134      * </p>
135      * 
136      * @return the error message, or <code>null</code> if none
137      */
138     public String   getErrorMessage();
139     
140     /**
141      * Returns the current message for this tab.
142      * <p>
143      * A message provides instruction or information to the 
144      * user, as opposed to an error message which should 
145      * describe some error state.
146      * </p>
147      * 
148      * @return the message, or <code>null</code> if none
149      */
150     public String   getMessage(); 
151     
152     /**
153      * Returns whether this tab is in a valid state in the context of the specified launch configuration.
154      * <p>
155      * This information is typically used by the launch configuration
156      * dialog to decide when it is okay to launch.
157      * </p>
158      *
159      * @param launchConfig launch configuration which provides context for validating this tab.
160      *         This value must not be <code>null</code>.
161      *
162      * @return whether this tab is in a valid state
163      */
164     public boolean isValid(ILaunchConfiguration launchConfig);
165     
166     /**
167      * Returns whether this tab is in a state that allows the launch configuration whose values
168      * this tab is showing to be saved.  This differs from <code>isValid()</code> in that <code>canSave()</code>
169      * determines if this tab prevents the current launch configuration from being saved, whereas
170      * <code>isValid()</code> determines if this tab prevents the current launch configuration from
171      * being launched.
172      * 
173      * <p>
174      * This information is typically used by the launch configuration
175      * dialog to decide when it is okay to save a launch configuration.
176      * </p>
177      * 
178      * @return whether this tab is in a state that allows the current launch configuration to be saved
179      */
180     public boolean canSave();
181     
182     /**
183      * Sets the launch configuration dialog that hosts this tab.
184      * This is the first method called on a launch configuration
185      * tab, and marks the beginning of this tab's lifecycle.
186      * 
187      * @param dialog launch configuration dialog
188      */
189     public void setLaunchConfigurationDialog(ILaunchConfigurationDialog dialog);
190     
191     /**
192      * Notifies this tab that the specified configuration has been
193      * launched, resulting in the given launch. This method can be
194      * called when a tab's control does not exist, to support single-click
195      * launching.
196      * 
197      * @param launch the result of launching the current
198      *  launch configuration
199      * @deprecated As of R3.0, this method is no longer called by the launch
200      *  framework. Since tabs do not exist when launching is performed elsewhere
201      *  than the launch dialog, this method cannot be relied upon for launching
202      *  functionality.
203      */
204     public void launched(ILaunch launch);
205     
206     /**
207      * Returns the name of this tab.
208      * 
209      * @return the name of this tab
210      */
211     public String   getName();
212     
213     /**
214      * Returns the image for this tab, or <code>null</code> if none
215      * 
216      * @return the image for this tab, or <code>null</code> if none
217      */
218     public Image getImage();    
219     
220     /**
221      * Notification that this tab has become the active tab in the launch
222      * configuration dialog.
223      * 
224      * @param workingCopy the launch configuration being edited
225      * @since 3.0
226      */
227     public void activated(ILaunchConfigurationWorkingCopy workingCopy);
228     
229     /**
230      * Notification that this tab is no longer the active tab in the launch
231      * configuration dialog.
232      *  
233      * @param workingCopy the launch configuration being edited
234      * @since 3.0
235      */
236     public void deactivated(ILaunchConfigurationWorkingCopy workingCopy);
237 }
238 
239
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags