KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > IWorkbench


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 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.core.runtime.dynamichelpers.IExtensionTracker;
15 import org.eclipse.jface.operation.IRunnableContext;
16 import org.eclipse.jface.preference.IPreferenceStore;
17 import org.eclipse.jface.preference.PreferenceManager;
18 import org.eclipse.jface.window.IShellProvider;
19 import org.eclipse.swt.widgets.Display;
20 import org.eclipse.ui.activities.IWorkbenchActivitySupport;
21 import org.eclipse.ui.browser.IWorkbenchBrowserSupport;
22 import org.eclipse.ui.commands.ICommandService;
23 import org.eclipse.ui.commands.IWorkbenchCommandSupport;
24 import org.eclipse.ui.contexts.IContextService;
25 import org.eclipse.ui.contexts.IWorkbenchContextSupport;
26 import org.eclipse.ui.handlers.IHandlerService;
27 import org.eclipse.ui.help.IWorkbenchHelpSystem;
28 import org.eclipse.ui.intro.IIntroManager;
29 import org.eclipse.ui.keys.IBindingService;
30 import org.eclipse.ui.operations.IWorkbenchOperationSupport;
31 import org.eclipse.ui.progress.IProgressService;
32 import org.eclipse.ui.services.IServiceLocator;
33 import org.eclipse.ui.themes.IThemeManager;
34 import org.eclipse.ui.views.IViewRegistry;
35 import org.eclipse.ui.wizards.IWizardRegistry;
36
37 /**
38  * A workbench is the root object for the Eclipse Platform user interface.
39  * <p>
40  * A <b>workbench</b> has one or more main windows which present to the end
41  * user information based on some underlying model, typically on resources in an
42  * underlying workspace. A workbench usually starts with a single open window,
43  * and automatically closes when its last window closes.
44  * </p>
45  * <p>
46  * Each <b>workbench window</b> has a collection of <b>pages</b>; the active
47  * page is the one that is being presented to the end user; at most one page is
48  * active in a window at a time.
49  * </p>
50  * <p>
51  * Each workbench page has a collection of <b>workbench parts</b>, of which
52  * there are two kinds: views and editors. A page's parts are arranged (tiled or
53  * stacked) for presentation on the screen. The arrangement is not fixed; the
54  * user can arrange the parts as they see fit. A <b>perspective</b> is a
55  * template for a page, capturing a collection of parts and their arrangement.
56  * </p>
57  * <p>
58  * The platform creates a workbench when the workbench plug-in is activated;
59  * since this happens at most once during the life of the running platform,
60  * there is only one workbench instance. Due to its singular nature, it is
61  * commonly referred to as <it>the</it> workbench.
62  * </p>
63  * <p>
64  * The workbench supports a few {@link IServiceLocator services} by default. If
65  * these services are used to allocate resources, it is important to remember to
66  * clean up those resources after you are done with them. Otherwise, the
67  * resources will exist until the workbench shuts down. The supported services
68  * are:
69  * </p>
70  * <ul>
71  * <li>{@link IBindingService}</li>
72  * <li>{@link ICommandService}</li>
73  * <li>{@link IContextService}</li>
74  * <li>{@link IHandlerService}</li>
75  * </ul>
76  * <p>
77  * This interface is not intended to be implemented by clients.
78  * </p>
79  *
80  * @see org.eclipse.ui.PlatformUI#getWorkbench
81  */

82 public interface IWorkbench extends IAdaptable, IServiceLocator {
83     /**
84      * Returns the display for this workbench.
85      * <p>
86      * Code should always ask the workbench for the display rather than rely on
87      * {@link Display#getDefault Display.getDefault()}.
88      * </p>
89      *
90      * @return the display to be used for all UI interactions with this
91      * workbench
92      * @since 3.0
93      */

94     public Display getDisplay();
95
96     /**
97      * Returns the progress service for the workbench.
98      *
99      * @return the progress service
100      * @since 3.0
101      */

102     public IProgressService getProgressService();
103
104     /**
105      * Adds a workbench listener.
106      *
107      * @param listener
108      * the workbench listener to add
109      * @since 3.2
110      */

111     public void addWorkbenchListener(IWorkbenchListener listener);
112
113     /**
114      * Removes a workbench listener.
115      *
116      * @param listener
117      * the workbench listener to remove
118      * @since 3.2
119      */

120     public void removeWorkbenchListener(IWorkbenchListener listener);
121     
122     /**
123      * Adds a window listener.
124      *
125      * @param listener
126      * the window listener to add
127      * @since 2.0
128      */

129     public void addWindowListener(IWindowListener listener);
130
131     /**
132      * Removes a window listener.
133      *
134      * @param listener
135      * the window listener to remove
136      * @since 2.0
137      */

138     public void removeWindowListener(IWindowListener listener);
139
140     /**
141      * Closes this workbench and all its open windows.
142      * <p>
143      * If the workbench has an open editor with unsaved content, the user will
144      * be given the opportunity to save it.
145      * </p>
146      *
147      * @return <code>true</code> if the workbench was successfully closed, and
148      * <code>false</code> if it is still open
149      */

150     public boolean close();
151
152     /**
153      * Returns the currently active window for this workbench (if any). Returns
154      * <code>null</code> if there is no active workbench window. Returns
155      * <code>null</code> if called from a non-UI thread.
156      *
157      * @return the active workbench window, or <code>null</code> if there is
158      * no active workbench window or if called from a non-UI thread
159      */

160     public IWorkbenchWindow getActiveWorkbenchWindow();
161
162     /**
163      * Returns the editor registry for the workbench.
164      *
165      * @return the workbench editor registry
166      */

167     public IEditorRegistry getEditorRegistry();
168
169     /**
170      * <p>
171      * Returns the undoable operation support for the workbench.
172      * </p>
173      *
174      * @return the workbench operation support
175      *
176      * @since 3.1
177      */

178     public IWorkbenchOperationSupport getOperationSupport();
179
180     /**
181      * Returns the perspective registry for the workbench.
182      *
183      * @return the workbench perspective registry
184      */

185     public IPerspectiveRegistry getPerspectiveRegistry();
186
187     /**
188      * Returns the preference manager for the workbench.
189      *
190      * @return the workbench preference manager
191      */

192     public PreferenceManager getPreferenceManager();
193
194     /**
195      * Returns the preference store for the workbench.
196      *
197      * @return the workbench preference store
198      * @since 2.0
199      * @deprecated this returns the internal preference store for the workbench,
200      * which clients should not use. Use
201      * {@link PlatformUI#getPreferenceStore()} instead. Note that
202      * these preference stores are not the same. If you were
203      * previously storing preferences in the store returned by this
204      * method you should move them to your own plugin preference
205      * store.
206      */

207     public IPreferenceStore getPreferenceStore();
208
209     /**
210      * Returns the shared images for the workbench.
211      *
212      * @return the shared image manager
213      */

214     public ISharedImages getSharedImages();
215
216     /**
217      * Returns the number of open main windows associated with this workbench.
218      * Note that wizards and dialogs are not included in this list since they
219      * are not considered main windows.
220      *
221      * @return the number of open windows
222      * @since 3.0
223      */

224     public int getWorkbenchWindowCount();
225
226     /**
227      * Returns a list of the open main windows associated with this workbench.
228      * Note that wizards and dialogs are not included in this list since they
229      * are not considered main windows.
230      *
231      * @return a list of open windows
232      */

233     public IWorkbenchWindow[] getWorkbenchWindows();
234
235     /**
236      * Returns the working set manager for the workbench.
237      *
238      * @return the working set manager
239      * @since 2.0
240      */

241     public IWorkingSetManager getWorkingSetManager();
242
243     /**
244      * Creates a new local working set manager. Clients of local working set
245      * managers are responsible for calling {@link IWorkingSetManager#dispose()}
246      * when the working sets it manages are no longer needed.
247      *
248      * @return the local working set manager
249      * @since 3.1
250      */

251     public ILocalWorkingSetManager createLocalWorkingSetManager();
252
253     /**
254      * Creates and opens a new workbench window with one page. The perspective
255      * of the new page is defined by the specified perspective ID. The new
256      * window and new page become active.
257      * <p>
258      * <b>Note:</b> The caller is responsible to ensure the action using this
259      * method will explicitly inform the user a new window will be opened.
260      * Otherwise, callers are strongly recommended to use the
261      * <code>openPerspective</code> APIs to programmatically show a
262      * perspective to avoid confusing the user.
263      * </p>
264      * <p>
265      * In most cases where this method is used the caller is tightly coupled to
266      * a particular perspective. They define it in the registry and contribute
267      * some user interface action to open or activate it. In situations like
268      * this a static variable is often used to identify the perspective ID.
269      * </p>
270      *
271      * @param perspectiveId
272      * the perspective id for the window's initial page, or
273      * <code>null</code> for no initial page
274      * @param input
275      * the page input, or <code>null</code> if there is no current
276      * input. This is used to seed the input for the new page's
277      * views.
278      * @return the new workbench window
279      * @exception WorkbenchException
280      * if a new window and page could not be opened
281      *
282      * @see IWorkbench#showPerspective(String, IWorkbenchWindow, IAdaptable)
283      */

284     public IWorkbenchWindow openWorkbenchWindow(String JavaDoc perspectiveId,
285             IAdaptable input) throws WorkbenchException;
286
287     /**
288      * Creates and opens a new workbench window with one page. The perspective
289      * of the new page is defined by the default perspective ID. The new window
290      * and new page become active.
291      * <p>
292      * <b>Note:</b> The caller is responsible to ensure the action using this
293      * method will explicitly inform the user a new window will be opened.
294      * Otherwise, callers are strongly recommended to use the
295      * <code>openPerspective</code> APIs to programmatically show a
296      * perspective to avoid confusing the user.
297      * </p>
298      *
299      * @param input
300      * the page input, or <code>null</code> if there is no current
301      * input. This is used to seed the input for the new page's
302      * views.
303      * @return the new workbench window
304      * @exception WorkbenchException
305      * if a new window and page could not be opened
306      *
307      * @see IWorkbench#showPerspective(String, IWorkbenchWindow, IAdaptable)
308      */

309     public IWorkbenchWindow openWorkbenchWindow(IAdaptable input)
310             throws WorkbenchException;
311
312     /**
313      * Closes then restarts this workbench.
314      * <p>
315      * If the workbench has an open editor with unsaved content, the user will
316      * be given the opportunity to save it.
317      * </p>
318      *
319      * @return <code>true</code> if the workbench was successfully closed, and
320      * <code>false</code> if it could not be closed
321      *
322      * @since 2.0
323      */

324     public boolean restart();
325
326     /**
327      * Shows the specified perspective to the user. The caller should use this
328      * method when the perspective to be shown is not dependent on the page's
329      * input. That is, the perspective can open in any page depending on user
330      * preferences.
331      * <p>
332      * The perspective may be shown in the specified window, in another existing
333      * window, or in a new window depending on user preferences. The exact
334      * policy is controlled by the workbench to ensure consistency to the user.
335      * The policy is subject to change. The current policy is as follows:
336      * <ul>
337      * <li>If the specified window has the requested perspective open, then the
338      * window is given focus and the perspective is shown. The page's input is
339      * ignored.</li>
340      * <li>If another window that has the workspace root as input and the
341      * requested perspective open and active, then the window is given focus.
342      * </li>
343      * <li>Otherwise the requested perspective is opened and shown in the
344      * specified window or in a new window depending on the current user
345      * preference for opening perspectives, and that window is given focus.
346      * </li>
347      * </ul>
348      * </p>
349      * <p>
350      * The workbench also defines a number of menu items to activate or open
351      * each registered perspective. A complete list of these perspectives is
352      * available from the perspective registry found on <code>IWorkbench</code>.
353      * </p>
354      *
355      * @param perspectiveId
356      * the perspective ID to show
357      * @param window
358      * the workbench window of the action calling this method.
359      * @return the workbench page that the perspective was shown
360      * @exception WorkbenchException
361      * if the perspective could not be shown
362      *
363      * @since 2.0
364      */

365     public IWorkbenchPage showPerspective(String JavaDoc perspectiveId,
366             IWorkbenchWindow window) throws WorkbenchException;
367
368     /**
369      * Shows the specified perspective to the user. The caller should use this
370      * method when the perspective to be shown is dependent on the page's input.
371      * That is, the perspective can only open in any page with the specified
372      * input.
373      * <p>
374      * The perspective may be shown in the specified window, in another existing
375      * window, or in a new window depending on user preferences. The exact
376      * policy is controlled by the workbench to ensure consistency to the user.
377      * The policy is subject to change. The current policy is as follows:
378      * <ul>
379      * <li>If the specified window has the requested perspective open and the
380      * same requested input, then the window is given focus and the perspective
381      * is shown.</li>
382      * <li>If another window has the requested input and the requested
383      * perspective open and active, then that window is given focus.</li>
384      * <li>If the specified window has the same requested input but not the
385      * requested perspective, then the window is given focus and the perspective
386      * is opened and shown on condition that the user preference is not to open
387      * perspectives in a new window.</li>
388      * <li>Otherwise the requested perspective is opened and shown in a new
389      * window, and the window is given focus.</li>
390      * </ul>
391      * </p>
392      * <p>
393      * The workbench also defines a number of menu items to activate or open
394      * each registered perspective. A complete list of these perspectives is
395      * available from the perspective registry found on <code>IWorkbench</code>.
396      * </p>
397      *
398      * @param perspectiveId
399      * the perspective ID to show
400      * @param window
401      * the workbench window of the action calling this method.
402      * @param input
403      * the page input, or <code>null</code> if there is no current
404      * input. This is used to seed the input for the page's views
405      * @return the workbench page that the perspective was shown
406      * @exception WorkbenchException
407      * if the perspective could not be shown
408      *
409      * @since 2.0
410      */

411     public IWorkbenchPage showPerspective(String JavaDoc perspectiveId,
412             IWorkbenchWindow window, IAdaptable input)
413             throws WorkbenchException;
414
415     /**
416      * Returns the decorator manager.
417      * <p>
418      * Any client using the decorator manager should come up with the text and
419      * image for the element (including any of the part's own decorations)
420      * before calling the decorator manager. It should also add a listener to be
421      * notified when decorations change.
422      * </p>
423      * <p>
424      * Note that if the element implements <code>IAdaptable</code>,
425      * decorators may use this mechanism to obtain an adapter (for example an
426      * <code>IResource</code>), and derive the decoration from the adapter
427      * rather than the element. Since the adapter may differ from the original
428      * element, those using the decorator manager should be prepared to handle
429      * notification that the decoration for the adapter has changed, in addition
430      * to handling notification that the decoration for the element has changed.
431      * That is, it needs to be able to map back from the adapter to the element.
432      * </p>
433      *
434      * @return the decorator manager
435      */

436     public IDecoratorManager getDecoratorManager();
437
438     /**
439      * Save all dirty editors in the workbench. Opens a dialog to prompt the
440      * user if <code>confirm</code> is true. Return true if successful. Return
441      * false if the user has canceled the command.
442      *
443      * @param confirm <code>true</code> to ask the user before saving unsaved
444      * changes (recommended), and <code>false</code> to save
445      * unsaved changes without asking
446      * @return <code>true</code> if the command succeeded, and
447      * <code>false</code> if the operation was canceled by the user or
448      * an error occurred while saving
449      */

450     public boolean saveAllEditors(boolean confirm);
451
452     /**
453      * Returns the element factory with the given id.
454      *
455      * @param factoryId
456      * the id of the element factory
457      * @return the element factory, or <code>null</code> if none
458      * @see IElementFactory
459      * @since 3.0
460      */

461     public IElementFactory getElementFactory(String JavaDoc factoryId);
462
463     /**
464      * Returns an interface to manage activities at the workbench level.
465      *
466      * @return an interface to manage activities at the workbench level.
467      * Guaranteed not to be <code>null</code>.
468      * @since 3.0
469      */

470     IWorkbenchActivitySupport getActivitySupport();
471
472     /**
473      * Returns an interface to manage commands at the workbench level.
474      *
475      * @return an interface to manage commands at the workbench level.
476      * Guaranteed not to be <code>null</code>.
477      * @since 3.0
478      * @deprecated Please use {@link IServiceLocator#getService(Class)} instead.
479      * @see ICommandService
480      * @see IHandlerService
481      */

482     IWorkbenchCommandSupport getCommandSupport();
483
484     /**
485      * Returns an interface to manage contexts at the workbench level.
486      *
487      * @return an interface to manage contexts at the workbench level.
488      * Guaranteed not to be <code>null</code>.
489      * @since 3.0
490      * @deprecated Please use {@link IServiceLocator#getService(Class)} instead.
491      * @see IContextService
492      */

493     IWorkbenchContextSupport getContextSupport();
494
495     /**
496      * Return the theme manager for this workbench.
497      *
498      * @return the theme manager for this workbench.Guaranteed not to be
499      * <code>null</code>.
500      * @since 3.0
501      */

502     public IThemeManager getThemeManager();
503
504     /**
505      * Return the intro manager for this workbench.
506      *
507      * @return the intro manager for this workbench. Guaranteed not to be
508      * <code>null</code>.
509      * @since 3.0
510      */

511     public IIntroManager getIntroManager();
512
513     /**
514      * Return the help system for this workbench.
515      *
516      * @return the help system
517      * @since 3.1
518      */

519     public IWorkbenchHelpSystem getHelpSystem();
520
521     /**
522      * Return the browser support for this workbench.
523      *
524      * @return the browser support system
525      * @since 3.1
526      */

527     public IWorkbenchBrowserSupport getBrowserSupport();
528
529     /**
530      * Returns a boolean indicating whether the workbench is in the process of
531      * closing.
532      *
533      * @return <code>true</code> if the workbench is in the process of
534      * closing, <code>false</code> otherwise
535      * @since 3.1
536      */

537     public boolean isClosing();
538
539     /**
540      * <p>
541      * Return the extension tracker for the workbench. This tracker may be used
542      * by plug-ins to ensure responsiveness to changes to the plug-in registry.
543      * </p>
544      * <p>
545      * The tracker at this level of the workbench is typically used to track
546      * elements that persist for the life of the workbench. For example,
547      * <code>IEditorDescriptor</code> objects fall into this category.
548      * </p>
549      *
550      * @return the extension tracker
551      * @see IWorkbenchWindow#getExtensionTracker()
552      * @see IWorkbenchPage#getExtensionTracker()
553      * @since 3.1
554      */

555     public IExtensionTracker getExtensionTracker();
556
557     /**
558      * Returns the view registry for the workbench.
559      *
560      * @return the workbench view registry
561      * @since 3.1
562      */

563     public IViewRegistry getViewRegistry();
564
565     /**
566      * Return the new wizard registry.
567      *
568      * @return the new wizard registry
569      * @since 3.1
570      */

571     public IWizardRegistry getNewWizardRegistry();
572
573     /**
574      * Return the import wizard registry.
575      *
576      * @return the import wizard registry
577      * @since 3.1
578      */

579     public IWizardRegistry getImportWizardRegistry();
580
581     /**
582      * Return the export wizard registry.
583      *
584      * @return the export wizard registry
585      * @since 3.1
586      */

587     public IWizardRegistry getExportWizardRegistry();
588     
589     /**
590      * Save all dirty saveables in the workbench that match the given filter.
591      * Opens a dialog to prompt the user if <code>confirm</code> is true.
592      * Return true if successful. Return false if the user has canceled the
593      * command.
594      *
595      * @since 3.3
596      *
597      * @param shellProvider the provider used to obtain a shell in prompting is
598      * required. Clients can use a workbench window for this.
599      * @param runnableContext a runnable context that will be used to provide a
600      * progress monitor while the save is taking place. Clients can
601      * use a workbench window for this.
602      * @param filter the filter used to determine if a particular dirty saveable
603      * needs to be saved or <code>null</code> if all dirty
604      * saveables should be saved.
605      * @param confirm <code>true</code> to ask the user before saving unsaved
606      * changes (recommended), and <code>false</code> to save
607      * unsaved changes without asking
608      * @return <code>true</code> if the command succeeded, and
609      * <code>false</code> if the operation was canceled by the user or
610      * an error occurred while saving
611      */

612     public boolean saveAll(IShellProvider shellProvider,
613             IRunnableContext runnableContext, ISaveableFilter filter,
614             boolean confirm);
615 }
616
Popular Tags