IWorkingSetManager


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.ui;
12  
13  import org.eclipse.core.runtime.IAdaptable;
14  import org.eclipse.jface.util.IPropertyChangeListener;
15  import org.eclipse.swt.widgets.Shell;
16  import org.eclipse.ui.dialogs.IWorkingSetEditWizard;
17  import org.eclipse.ui.dialogs.IWorkingSetNewWizard;
18  import org.eclipse.ui.dialogs.IWorkingSetSelectionDialog;
19  
20  /**
21   * A working set manager stores working sets and provides property 
22   * change notification when a working set is added or removed.
23   * <p>
24   * The workbench working set manager can be accessed using 
25   * <code>IWorkbench#getWorkingSetManager()</code>
26   * </p>
27   * <p>
28   * This interface is not intended to be implemented by clients.
29   * </p>
30   * 
31   * @see IWorkingSet
32   * @since 2.0 initial version
33   * @since 3.0 added createWorkingSet(IMemento)
34   */
35  public interface IWorkingSetManager {
36  
37      /**
38       * Change event id when a working set is added
39       * newValue of the PropertyChangeEvent will be the added working set.
40       * oldValue will be null.
41       *
42       * @see IPropertyChangeListener
43       */
44      public static final String   CHANGE_WORKING_SET_ADD = "workingSetAdd"; //$NON-NLS-1$
45  
46      /**
47       * Change event id when a working set is removed
48       * newValue of the PropertyChangeEvent will be null.
49       * oldValue will be the removed working set.
50       *
51       * @see IPropertyChangeListener
52       */
53      public static final String   CHANGE_WORKING_SET_REMOVE = "workingSetRemove"; //$NON-NLS-1$
54  
55      /**
56       * Change event id when the working set contents changed
57       * newValue of the PropertyChangeEvent will be the changed working set.
58       * oldValue will be null.
59       *
60       * @see IPropertyChangeListener
61       */
62      public static final String   CHANGE_WORKING_SET_CONTENT_CHANGE = "workingSetContentChange"; //$NON-NLS-1$
63  
64      /**
65       * Change event id when the working set name changed.
66       * newValue of the PropertyChangeEvent will be the changed working set.
67       * oldValue will be null.
68       *
69       * @see IPropertyChangeListener
70       */
71      public static final String   CHANGE_WORKING_SET_NAME_CHANGE = "workingSetNameChange"; //$NON-NLS-1$   
72      
73      /**
74       * Change event id when the working set label changed.
75       * newValue of the PropertyChangeEvent will be the changed working set.
76       * oldValue will be null.
77       *
78       * @see IPropertyChangeListener
79       * @since 3.2
80       */
81      public static final String   CHANGE_WORKING_SET_LABEL_CHANGE = "workingSetLabelChange"; //$NON-NLS-1$ 
82      
83      /**
84       * Change event id when a working set updater got installed.
85       * NewValue of the PropertyChangeEvent will be the installed updater.
86       * OldValue will be <code>null</code>
87       * @since 3.1
88       */
89      public static final String   CHANGE_WORKING_SET_UPDATER_INSTALLED = "workingSetUpdaterInstalled"; //$NON-NLS-1$
90      
91      /**
92       * Change event id when a working set updater got uninstalled.
93       * NewValue will be <code>null</code>
94       * OldValue of the PropertyChangeEvent will be the uninstalled updater.
95       * @since 3.3
96       */
97      public static final String   CHANGE_WORKING_SET_UPDATER_UNINSTALLED = "workingSetUpdaterUninstalled"; //$NON-NLS-1$
98  
99      /**
100      * Adds a property change listener.
101      * 
102      * @param listener the property change listener to add
103      */
104     public void addPropertyChangeListener(IPropertyChangeListener listener);
105 
106     /**
107      * Adds a working set to the top of the list of most recently used 
108      * working sets, making it the most recently used working set.
109      * The last (oldest) item will be deleted if the list exceeds the 
110      * size limit.
111      * 
112      * @param workingSet the working set to add to the list of most 
113      *  recently used working sets.
114      */
115     public void addRecentWorkingSet(IWorkingSet workingSet);
116 
117     /**
118      * Adds a working set to the receiver. The working set must 
119      * not exist yet.
120      * 
121      * @param workingSet the working set to add
122      */
123     public void addWorkingSet(IWorkingSet workingSet);
124 
125     /**
126      * Creates a new working set.
127      * The working set is not added to the working set manager.
128      * 
129      * @param name the name of the new working set. Should not have 
130      *  leading or trailing whitespace.
131      * @param elements the working set contents
132      * @return a new working set with the specified name and content
133      */
134     public IWorkingSet createWorkingSet(String   name, IAdaptable[] elements);
135     
136     /**
137      * Create a working set that is the union of a collection of other working
138      * sets. One connected (via
139      * {@link IWorkingSetManager#addWorkingSet(IWorkingSet)} this working set
140      * will be automatically updated to reflect the contents of the component
141      * sets, should they themselves change.
142      * 
143      * @param name
144      *            the name of the new working set. Should not have leading or
145      *            trailing whitespace.
146      * @param label
147      *            the user-friendly label the working set
148      * @param components
149      *            the component working sets
150      * @return a new working set with the specified name and content
151      * 
152      * @since 3.2
153      */
154     public IWorkingSet createAggregateWorkingSet(String   name, String   label,
155             IWorkingSet[] components);
156 
157     /**
158      * Re-creates and returns a working set from the state captured within the 
159      * given memento. 
160      *
161      * @param memento a memento containing the state for the working set
162      * @return the restored working set, or <code>null</code> if it could not be created
163      * 
164      * @since 3.0
165      */
166     public IWorkingSet createWorkingSet(IMemento memento);
167 
168     /**
169      * Creates a working set edit wizard for the specified working set.
170      * The working set will already be set in the wizard.
171      * The caller is responsible for creating and opening a wizard dialog.
172      *
173      * Example:
174      * <code>
175      *  IWorkingSetEditWizard wizard = workingSetManager.createWorkingSetEditWizard(workingSet);
176      *  if (wizard != null) {
177      *    WizardDialog dialog = new WizardDialog(shell, wizard);
178      *
179      *    dialog.create();      
180      *    if (dialog.open() == Window.OK) {     
181      *        workingSet = wizard.getSelection();
182      *    }
183      *  }
184      * </code>
185      * 
186      * @param workingSet working set to create a working set edit wizard 
187      *  for.
188      * @return a working set edit wizard to edit the specified working set
189      *  or <code>null</code> if no edit wizard has been defined for the
190      *  working set. If the defined edit wizard for the working set could 
191      *  not be loaded a default IResource based wizard will be returned. 
192      *  If the default edit wizard can not be loaded <code>null</code> is 
193      *  returned.
194      * @since 2.1
195      */
196     public IWorkingSetEditWizard createWorkingSetEditWizard(
197             IWorkingSet workingSet);
198     
199 
200     /**
201      * Creates a working set new wizard. The wizard will allow creating new
202      * working sets. Returns <code>null</code> if there aren't any working set
203      * definitions that support creation of working sets.
204      * <p>
205      * Example:
206      * <code>
207      *   IWorkingSetNewWizard wizard= workingSetManager.createWorkingSetNewWizard(null);
208      *   if (wizard != null) {  
209      *       WizardDialog dialog = new WizardDialog(shell, wizard);
210      *
211      *       dialog.create();       
212      *       if (dialog.open() == Window.OK) {      
213      *          ...
214      *       }
215      *   }
216      * </code>
217      * </p>
218      * 
219      * @param workingSetIds a list of working set ids which are valid workings sets
220      *  to be created or <code>null</code> if all currently available working set types
221      *  are valid
222      * 
223      * @return the working set new wizard or <code>null</code>
224      * 
225      * @since 3.1
226      */
227     public IWorkingSetNewWizard createWorkingSetNewWizard(String  [] workingSetIds);
228     
229     /**
230      * @param parent the parent shell
231      * @return the dialog
232      * @deprecated use createWorkingSetSelectionDialog(parent, true) instead
233      */
234     public IWorkingSetSelectionDialog createWorkingSetSelectionDialog(
235             Shell parent);
236 
237     /**
238      * Creates a working set selection dialog that lists all working 
239      * sets and allows the user to add, remove and edit working sets.
240      * The caller is responsible for opening the dialog with 
241      * <code>IWorkingSetSelectionDialog#open</code>, and subsequently 
242      * extracting the selected working sets using 
243      * <code>IWorkingSetSelectionDialog#getSelection</code>.
244      * 
245      * @param parentShell the parent shell of the working set selection dialog
246      * @param multi true=more than one working set can be chosen 
247      *  in the dialog. false=only one working set can be chosen. Multiple
248      *  working sets can still be selected and removed from the list but
249      *  the dialog can only be closed when a single working set is selected.
250      * @return a working set selection dialog
251      */
252     public IWorkingSetSelectionDialog createWorkingSetSelectionDialog(
253             Shell parentShell, boolean multi);
254 
255     /**
256      * Creates a working set selection dialog that lists all working 
257      * sets with the specified ids and allows the user to add, remove and
258      * edit working sets with the specified ids.
259      * The caller is responsible for opening the dialog with 
260      * <code>IWorkingSetSelectionDialog#open</code>, and subsequently 
261      * extracting the selected working sets using 
262      * <code>IWorkingSetSelectionDialog#getSelection</code>.
263      * 
264      * @param parentShell the parent shell of the working set selection dialog
265      * @param multi true=more than one working set can be chosen 
266      *  in the dialog. false=only one working set can be chosen. Multiple
267      *  working sets can still be selected and removed from the list but
268      *  the dialog can only be closed when a single working set is selected.
269      * @param workingsSetIds a list of working set ids which are valid workings sets
270      *  to be selected, created, removed or edited, or <code>null</code> if all currently
271      *  available working set types are valid 
272      * @return a working set selection dialog
273      * @since 3.1
274      */
275     public IWorkingSetSelectionDialog createWorkingSetSelectionDialog(
276             Shell parentShell, boolean multi, String  [] workingsSetIds);
277     
278     /**
279      * Returns the list of most recently used working sets.
280      * The most recently used working set appears first in the list.
281      * 
282      * @return the list of most recently used working sets
283      */
284     public IWorkingSet[] getRecentWorkingSets();
285 
286     /**
287      * Returns the working set with the specified name.
288      * Returns null if there is no working set with that name.
289      * 
290      * @param name the name of the working set to return
291      * @return the working set with the specified name.
292      */
293     public IWorkingSet getWorkingSet(String   name);
294 
295     /**
296      * Returns an array of all working sets stored in the receiver. Any working
297      * set whose {@link IWorkingSet#isVisible()} method returns false will not be
298      * included in this array. For a complete list of working sets please use
299      * {@link #getAllWorkingSets()}.
300      * 
301      * @return the working sets stored in the receiver
302      */
303     public IWorkingSet[] getWorkingSets();
304     
305     /**
306      * Returns an array of all working sets stored in the receiver including
307      * those that are marked as being not visible.
308      * 
309      * @see IWorkingSet#isVisible()
310      * @return the working sets stored in the receiver
311      * @since 3.2
312      */
313     public IWorkingSet[] getAllWorkingSets();
314 
315     /**
316      * Removes the property change listener.
317      * 
318      * @param listener the property change listener to remove
319      */
320     public void removePropertyChangeListener(IPropertyChangeListener listener);
321 
322     /**
323      * Removes the working set
324      * 
325      * @param workingSet the working set to remove
326      */
327     public void removeWorkingSet(IWorkingSet workingSet);
328     
329     /**
330      * Disposes the working set manager.
331      * 
332      * @since 3.1
333      */
334     public void dispose();
335 }
336
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags