001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui;
011:
012: import org.eclipse.core.runtime.IAdaptable;
013: import org.eclipse.jface.util.IPropertyChangeListener;
014: import org.eclipse.swt.widgets.Shell;
015: import org.eclipse.ui.dialogs.IWorkingSetEditWizard;
016: import org.eclipse.ui.dialogs.IWorkingSetNewWizard;
017: import org.eclipse.ui.dialogs.IWorkingSetSelectionDialog;
018:
019: /**
020: * A working set manager stores working sets and provides property
021: * change notification when a working set is added or removed.
022: * <p>
023: * The workbench working set manager can be accessed using
024: * <code>IWorkbench#getWorkingSetManager()</code>
025: * </p>
026: * <p>
027: * This interface is not intended to be implemented by clients.
028: * </p>
029: *
030: * @see IWorkingSet
031: * @since 2.0 initial version
032: * @since 3.0 added createWorkingSet(IMemento)
033: */
034: public interface IWorkingSetManager {
035:
036: /**
037: * Change event id when a working set is added
038: * newValue of the PropertyChangeEvent will be the added working set.
039: * oldValue will be null.
040: *
041: * @see IPropertyChangeListener
042: */
043: public static final String CHANGE_WORKING_SET_ADD = "workingSetAdd"; //$NON-NLS-1$
044:
045: /**
046: * Change event id when a working set is removed
047: * newValue of the PropertyChangeEvent will be null.
048: * oldValue will be the removed working set.
049: *
050: * @see IPropertyChangeListener
051: */
052: public static final String CHANGE_WORKING_SET_REMOVE = "workingSetRemove"; //$NON-NLS-1$
053:
054: /**
055: * Change event id when the working set contents changed
056: * newValue of the PropertyChangeEvent will be the changed working set.
057: * oldValue will be null.
058: *
059: * @see IPropertyChangeListener
060: */
061: public static final String CHANGE_WORKING_SET_CONTENT_CHANGE = "workingSetContentChange"; //$NON-NLS-1$
062:
063: /**
064: * Change event id when the working set name changed.
065: * newValue of the PropertyChangeEvent will be the changed working set.
066: * oldValue will be null.
067: *
068: * @see IPropertyChangeListener
069: */
070: public static final String CHANGE_WORKING_SET_NAME_CHANGE = "workingSetNameChange"; //$NON-NLS-1$
071:
072: /**
073: * Change event id when the working set label changed.
074: * newValue of the PropertyChangeEvent will be the changed working set.
075: * oldValue will be null.
076: *
077: * @see IPropertyChangeListener
078: * @since 3.2
079: */
080: public static final String CHANGE_WORKING_SET_LABEL_CHANGE = "workingSetLabelChange"; //$NON-NLS-1$
081:
082: /**
083: * Change event id when a working set updater got installed.
084: * NewValue of the PropertyChangeEvent will be the installed updater.
085: * OldValue will be <code>null</code>
086: * @since 3.1
087: */
088: public static final String CHANGE_WORKING_SET_UPDATER_INSTALLED = "workingSetUpdaterInstalled"; //$NON-NLS-1$
089:
090: /**
091: * Change event id when a working set updater got uninstalled.
092: * NewValue will be <code>null</code>
093: * OldValue of the PropertyChangeEvent will be the uninstalled updater.
094: * @since 3.3
095: */
096: public static final String CHANGE_WORKING_SET_UPDATER_UNINSTALLED = "workingSetUpdaterUninstalled"; //$NON-NLS-1$
097:
098: /**
099: * Adds a property change listener.
100: *
101: * @param listener the property change listener to add
102: */
103: public void addPropertyChangeListener(
104: 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,
135: IAdaptable[] elements);
136:
137: /**
138: * Create a working set that is the union of a collection of other working
139: * sets. One connected (via
140: * {@link IWorkingSetManager#addWorkingSet(IWorkingSet)} this working set
141: * will be automatically updated to reflect the contents of the component
142: * sets, should they themselves change.
143: *
144: * @param name
145: * the name of the new working set. Should not have leading or
146: * trailing whitespace.
147: * @param label
148: * the user-friendly label the working set
149: * @param components
150: * the component working sets
151: * @return a new working set with the specified name and content
152: *
153: * @since 3.2
154: */
155: public IWorkingSet createAggregateWorkingSet(String name,
156: String label, IWorkingSet[] components);
157:
158: /**
159: * Re-creates and returns a working set from the state captured within the
160: * given memento.
161: *
162: * @param memento a memento containing the state for the working set
163: * @return the restored working set, or <code>null</code> if it could not be created
164: *
165: * @since 3.0
166: */
167: public IWorkingSet createWorkingSet(IMemento memento);
168:
169: /**
170: * Creates a working set edit wizard for the specified working set.
171: * The working set will already be set in the wizard.
172: * The caller is responsible for creating and opening a wizard dialog.
173: *
174: * Example:
175: * <code>
176: * IWorkingSetEditWizard wizard = workingSetManager.createWorkingSetEditWizard(workingSet);
177: * if (wizard != null) {
178: * WizardDialog dialog = new WizardDialog(shell, wizard);
179: *
180: * dialog.create();
181: * if (dialog.open() == Window.OK) {
182: * workingSet = wizard.getSelection();
183: * }
184: * }
185: * </code>
186: *
187: * @param workingSet working set to create a working set edit wizard
188: * for.
189: * @return a working set edit wizard to edit the specified working set
190: * or <code>null</code> if no edit wizard has been defined for the
191: * working set. If the defined edit wizard for the working set could
192: * not be loaded a default IResource based wizard will be returned.
193: * If the default edit wizard can not be loaded <code>null</code> is
194: * returned.
195: * @since 2.1
196: */
197: public IWorkingSetEditWizard createWorkingSetEditWizard(
198: IWorkingSet workingSet);
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(
228: String[] workingSetIds);
229:
230: /**
231: * @param parent the parent shell
232: * @return the dialog
233: * @deprecated use createWorkingSetSelectionDialog(parent, true) instead
234: */
235: public IWorkingSetSelectionDialog createWorkingSetSelectionDialog(
236: Shell parent);
237:
238: /**
239: * Creates a working set selection dialog that lists all working
240: * sets and allows the user to add, remove and edit working sets.
241: * The caller is responsible for opening the dialog with
242: * <code>IWorkingSetSelectionDialog#open</code>, and subsequently
243: * extracting the selected working sets using
244: * <code>IWorkingSetSelectionDialog#getSelection</code>.
245: *
246: * @param parentShell the parent shell of the working set selection dialog
247: * @param multi true=more than one working set can be chosen
248: * in the dialog. false=only one working set can be chosen. Multiple
249: * working sets can still be selected and removed from the list but
250: * the dialog can only be closed when a single working set is selected.
251: * @return a working set selection dialog
252: */
253: public IWorkingSetSelectionDialog createWorkingSetSelectionDialog(
254: Shell parentShell, boolean multi);
255:
256: /**
257: * Creates a working set selection dialog that lists all working
258: * sets with the specified ids and allows the user to add, remove and
259: * edit working sets with the specified ids.
260: * The caller is responsible for opening the dialog with
261: * <code>IWorkingSetSelectionDialog#open</code>, and subsequently
262: * extracting the selected working sets using
263: * <code>IWorkingSetSelectionDialog#getSelection</code>.
264: *
265: * @param parentShell the parent shell of the working set selection dialog
266: * @param multi true=more than one working set can be chosen
267: * in the dialog. false=only one working set can be chosen. Multiple
268: * working sets can still be selected and removed from the list but
269: * the dialog can only be closed when a single working set is selected.
270: * @param workingsSetIds a list of working set ids which are valid workings sets
271: * to be selected, created, removed or edited, or <code>null</code> if all currently
272: * available working set types are valid
273: * @return a working set selection dialog
274: * @since 3.1
275: */
276: public IWorkingSetSelectionDialog createWorkingSetSelectionDialog(
277: Shell parentShell, boolean multi, String[] workingsSetIds);
278:
279: /**
280: * Returns the list of most recently used working sets.
281: * The most recently used working set appears first in the list.
282: *
283: * @return the list of most recently used working sets
284: */
285: public IWorkingSet[] getRecentWorkingSets();
286:
287: /**
288: * Returns the working set with the specified name.
289: * Returns null if there is no working set with that name.
290: *
291: * @param name the name of the working set to return
292: * @return the working set with the specified name.
293: */
294: public IWorkingSet getWorkingSet(String name);
295:
296: /**
297: * Returns an array of all working sets stored in the receiver. Any working
298: * set whose {@link IWorkingSet#isVisible()} method returns false will not be
299: * included in this array. For a complete list of working sets please use
300: * {@link #getAllWorkingSets()}.
301: *
302: * @return the working sets stored in the receiver
303: */
304: public IWorkingSet[] getWorkingSets();
305:
306: /**
307: * Returns an array of all working sets stored in the receiver including
308: * those that are marked as being not visible.
309: *
310: * @see IWorkingSet#isVisible()
311: * @return the working sets stored in the receiver
312: * @since 3.2
313: */
314: public IWorkingSet[] getAllWorkingSets();
315:
316: /**
317: * Removes the property change listener.
318: *
319: * @param listener the property change listener to remove
320: */
321: public void removePropertyChangeListener(
322: IPropertyChangeListener listener);
323:
324: /**
325: * Removes the working set
326: *
327: * @param workingSet the working set to remove
328: */
329: public void removeWorkingSet(IWorkingSet workingSet);
330:
331: /**
332: * Disposes the working set manager.
333: *
334: * @since 3.1
335: */
336: public void dispose();
337:
338: /**
339: * Utility method that will add the <code>element</code> to each given
340: * working set in <code>workingSets</code> if possible. This method will
341: * invoke {@link IWorkingSet#adaptElements(IAdaptable[])} for the element on
342: * each working set and the result of this method will be used rather than
343: * the original element in the addition operation.
344: *
345: * @param element
346: * the element to adapt and then add to the working sets
347: * @param workingSets
348: * the working sets to add the element to
349: * @since 3.4
350: */
351: public void addToWorkingSets(IAdaptable element,
352: IWorkingSet[] workingSets);
353: }
|