001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 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.core.runtime.dynamichelpers.IExtensionTracker;
014: import org.eclipse.jface.operation.IRunnableContext;
015: import org.eclipse.jface.preference.IPreferenceStore;
016: import org.eclipse.jface.preference.PreferenceManager;
017: import org.eclipse.jface.window.IShellProvider;
018: import org.eclipse.swt.widgets.Display;
019: import org.eclipse.ui.activities.IWorkbenchActivitySupport;
020: import org.eclipse.ui.browser.IWorkbenchBrowserSupport;
021: import org.eclipse.ui.commands.ICommandService;
022: import org.eclipse.ui.commands.IWorkbenchCommandSupport;
023: import org.eclipse.ui.contexts.IContextService;
024: import org.eclipse.ui.contexts.IWorkbenchContextSupport;
025: import org.eclipse.ui.handlers.IHandlerService;
026: import org.eclipse.ui.help.IWorkbenchHelpSystem;
027: import org.eclipse.ui.intro.IIntroManager;
028: import org.eclipse.ui.keys.IBindingService;
029: import org.eclipse.ui.operations.IWorkbenchOperationSupport;
030: import org.eclipse.ui.progress.IProgressService;
031: import org.eclipse.ui.services.IServiceLocator;
032: import org.eclipse.ui.themes.IThemeManager;
033: import org.eclipse.ui.views.IViewRegistry;
034: import org.eclipse.ui.wizards.IWizardRegistry;
035:
036: /**
037: * A workbench is the root object for the Eclipse Platform user interface.
038: * <p>
039: * A <b>workbench</b> has one or more main windows which present to the end
040: * user information based on some underlying model, typically on resources in an
041: * underlying workspace. A workbench usually starts with a single open window,
042: * and automatically closes when its last window closes.
043: * </p>
044: * <p>
045: * Each <b>workbench window</b> has a collection of <b>pages</b>; the active
046: * page is the one that is being presented to the end user; at most one page is
047: * active in a window at a time.
048: * </p>
049: * <p>
050: * Each workbench page has a collection of <b>workbench parts</b>, of which
051: * there are two kinds: views and editors. A page's parts are arranged (tiled or
052: * stacked) for presentation on the screen. The arrangement is not fixed; the
053: * user can arrange the parts as they see fit. A <b>perspective</b> is a
054: * template for a page, capturing a collection of parts and their arrangement.
055: * </p>
056: * <p>
057: * The platform creates a workbench when the workbench plug-in is activated;
058: * since this happens at most once during the life of the running platform,
059: * there is only one workbench instance. Due to its singular nature, it is
060: * commonly referred to as <it>the</it> workbench.
061: * </p>
062: * <p>
063: * The workbench supports a few {@link IServiceLocator services} by default. If
064: * these services are used to allocate resources, it is important to remember to
065: * clean up those resources after you are done with them. Otherwise, the
066: * resources will exist until the workbench shuts down. The supported services
067: * are:
068: * </p>
069: * <ul>
070: * <li>{@link IBindingService}</li>
071: * <li>{@link ICommandService}</li>
072: * <li>{@link IContextService}</li>
073: * <li>{@link IHandlerService}</li>
074: * </ul>
075: * <p>
076: * This interface is not intended to be implemented by clients.
077: * </p>
078: *
079: * @see org.eclipse.ui.PlatformUI#getWorkbench
080: */
081: public interface IWorkbench extends IAdaptable, IServiceLocator {
082: /**
083: * Returns the display for this workbench.
084: * <p>
085: * Code should always ask the workbench for the display rather than rely on
086: * {@link Display#getDefault Display.getDefault()}.
087: * </p>
088: *
089: * @return the display to be used for all UI interactions with this
090: * workbench
091: * @since 3.0
092: */
093: public Display getDisplay();
094:
095: /**
096: * Returns the progress service for the workbench.
097: *
098: * @return the progress service
099: * @since 3.0
100: */
101: public IProgressService getProgressService();
102:
103: /**
104: * Adds a workbench listener.
105: *
106: * @param listener
107: * the workbench listener to add
108: * @since 3.2
109: */
110: public void addWorkbenchListener(IWorkbenchListener listener);
111:
112: /**
113: * Removes a workbench listener.
114: *
115: * @param listener
116: * the workbench listener to remove
117: * @since 3.2
118: */
119: public void removeWorkbenchListener(IWorkbenchListener listener);
120:
121: /**
122: * Adds a window listener.
123: *
124: * @param listener
125: * the window listener to add
126: * @since 2.0
127: */
128: public void addWindowListener(IWindowListener listener);
129:
130: /**
131: * Removes a window listener.
132: *
133: * @param listener
134: * the window listener to remove
135: * @since 2.0
136: */
137: public void removeWindowListener(IWindowListener listener);
138:
139: /**
140: * Closes this workbench and all its open windows.
141: * <p>
142: * If the workbench has an open editor with unsaved content, the user will
143: * be given the opportunity to save it.
144: * </p>
145: *
146: * @return <code>true</code> if the workbench was successfully closed, and
147: * <code>false</code> if it is still open
148: */
149: public boolean close();
150:
151: /**
152: * Returns the currently active window for this workbench (if any). Returns
153: * <code>null</code> if there is no active workbench window. Returns
154: * <code>null</code> if called from a non-UI thread.
155: *
156: * @return the active workbench window, or <code>null</code> if there is
157: * no active workbench window or if called from a non-UI thread
158: */
159: public IWorkbenchWindow getActiveWorkbenchWindow();
160:
161: /**
162: * Returns the editor registry for the workbench.
163: *
164: * @return the workbench editor registry
165: */
166: public IEditorRegistry getEditorRegistry();
167:
168: /**
169: * <p>
170: * Returns the undoable operation support for the workbench.
171: * </p>
172: *
173: * @return the workbench operation support
174: *
175: * @since 3.1
176: */
177: public IWorkbenchOperationSupport getOperationSupport();
178:
179: /**
180: * Returns the perspective registry for the workbench.
181: *
182: * @return the workbench perspective registry
183: */
184: public IPerspectiveRegistry getPerspectiveRegistry();
185:
186: /**
187: * Returns the preference manager for the workbench.
188: *
189: * @return the workbench preference manager
190: */
191: public PreferenceManager getPreferenceManager();
192:
193: /**
194: * Returns the preference store for the workbench.
195: *
196: * @return the workbench preference store
197: * @since 2.0
198: * @deprecated this returns the internal preference store for the workbench,
199: * which clients should not use. Use
200: * {@link PlatformUI#getPreferenceStore()} instead. Note that
201: * these preference stores are not the same. If you were
202: * previously storing preferences in the store returned by this
203: * method you should move them to your own plugin preference
204: * store.
205: */
206: public IPreferenceStore getPreferenceStore();
207:
208: /**
209: * Returns the shared images for the workbench.
210: *
211: * @return the shared image manager
212: */
213: public ISharedImages getSharedImages();
214:
215: /**
216: * Returns the number of open main windows associated with this workbench.
217: * Note that wizards and dialogs are not included in this list since they
218: * are not considered main windows.
219: *
220: * @return the number of open windows
221: * @since 3.0
222: */
223: public int getWorkbenchWindowCount();
224:
225: /**
226: * Returns a list of the open main windows associated with this workbench.
227: * Note that wizards and dialogs are not included in this list since they
228: * are not considered main windows.
229: *
230: * @return a list of open windows
231: */
232: public IWorkbenchWindow[] getWorkbenchWindows();
233:
234: /**
235: * Returns the working set manager for the workbench.
236: *
237: * @return the working set manager
238: * @since 2.0
239: */
240: public IWorkingSetManager getWorkingSetManager();
241:
242: /**
243: * Creates a new local working set manager. Clients of local working set
244: * managers are responsible for calling {@link IWorkingSetManager#dispose()}
245: * when the working sets it manages are no longer needed.
246: *
247: * @return the local working set manager
248: * @since 3.1
249: */
250: public ILocalWorkingSetManager createLocalWorkingSetManager();
251:
252: /**
253: * Creates and opens a new workbench window with one page. The perspective
254: * of the new page is defined by the specified perspective ID. The new
255: * window and new page become active.
256: * <p>
257: * <b>Note:</b> The caller is responsible to ensure the action using this
258: * method will explicitly inform the user a new window will be opened.
259: * Otherwise, callers are strongly recommended to use the
260: * <code>openPerspective</code> APIs to programmatically show a
261: * perspective to avoid confusing the user.
262: * </p>
263: * <p>
264: * In most cases where this method is used the caller is tightly coupled to
265: * a particular perspective. They define it in the registry and contribute
266: * some user interface action to open or activate it. In situations like
267: * this a static variable is often used to identify the perspective ID.
268: * </p>
269: *
270: * @param perspectiveId
271: * the perspective id for the window's initial page, or
272: * <code>null</code> for no initial page
273: * @param input
274: * the page input, or <code>null</code> if there is no current
275: * input. This is used to seed the input for the new page's
276: * views.
277: * @return the new workbench window
278: * @exception WorkbenchException
279: * if a new window and page could not be opened
280: *
281: * @see IWorkbench#showPerspective(String, IWorkbenchWindow, IAdaptable)
282: */
283: public IWorkbenchWindow openWorkbenchWindow(String perspectiveId,
284: IAdaptable input) throws WorkbenchException;
285:
286: /**
287: * Creates and opens a new workbench window with one page. The perspective
288: * of the new page is defined by the default perspective ID. The new window
289: * and new page become active.
290: * <p>
291: * <b>Note:</b> The caller is responsible to ensure the action using this
292: * method will explicitly inform the user a new window will be opened.
293: * Otherwise, callers are strongly recommended to use the
294: * <code>openPerspective</code> APIs to programmatically show a
295: * perspective to avoid confusing the user.
296: * </p>
297: *
298: * @param input
299: * the page input, or <code>null</code> if there is no current
300: * input. This is used to seed the input for the new page's
301: * views.
302: * @return the new workbench window
303: * @exception WorkbenchException
304: * if a new window and page could not be opened
305: *
306: * @see IWorkbench#showPerspective(String, IWorkbenchWindow, IAdaptable)
307: */
308: public IWorkbenchWindow openWorkbenchWindow(IAdaptable input)
309: throws WorkbenchException;
310:
311: /**
312: * Closes then restarts this workbench.
313: * <p>
314: * If the workbench has an open editor with unsaved content, the user will
315: * be given the opportunity to save it.
316: * </p>
317: *
318: * @return <code>true</code> if the workbench was successfully closed, and
319: * <code>false</code> if it could not be closed
320: *
321: * @since 2.0
322: */
323: public boolean restart();
324:
325: /**
326: * Shows the specified perspective to the user. The caller should use this
327: * method when the perspective to be shown is not dependent on the page's
328: * input. That is, the perspective can open in any page depending on user
329: * preferences.
330: * <p>
331: * The perspective may be shown in the specified window, in another existing
332: * window, or in a new window depending on user preferences. The exact
333: * policy is controlled by the workbench to ensure consistency to the user.
334: * The policy is subject to change. The current policy is as follows:
335: * <ul>
336: * <li>If the specified window has the requested perspective open, then the
337: * window is given focus and the perspective is shown. The page's input is
338: * ignored.</li>
339: * <li>If another window that has the workspace root as input and the
340: * requested perspective open and active, then the window is given focus.
341: * </li>
342: * <li>Otherwise the requested perspective is opened and shown in the
343: * specified window or in a new window depending on the current user
344: * preference for opening perspectives, and that window is given focus.
345: * </li>
346: * </ul>
347: * </p>
348: * <p>
349: * The workbench also defines a number of menu items to activate or open
350: * each registered perspective. A complete list of these perspectives is
351: * available from the perspective registry found on <code>IWorkbench</code>.
352: * </p>
353: *
354: * @param perspectiveId
355: * the perspective ID to show
356: * @param window
357: * the workbench window of the action calling this method.
358: * @return the workbench page that the perspective was shown
359: * @exception WorkbenchException
360: * if the perspective could not be shown
361: *
362: * @since 2.0
363: */
364: public IWorkbenchPage showPerspective(String perspectiveId,
365: IWorkbenchWindow window) throws WorkbenchException;
366:
367: /**
368: * Shows the specified perspective to the user. The caller should use this
369: * method when the perspective to be shown is dependent on the page's input.
370: * That is, the perspective can only open in any page with the specified
371: * input.
372: * <p>
373: * The perspective may be shown in the specified window, in another existing
374: * window, or in a new window depending on user preferences. The exact
375: * policy is controlled by the workbench to ensure consistency to the user.
376: * The policy is subject to change. The current policy is as follows:
377: * <ul>
378: * <li>If the specified window has the requested perspective open and the
379: * same requested input, then the window is given focus and the perspective
380: * is shown.</li>
381: * <li>If another window has the requested input and the requested
382: * perspective open and active, then that window is given focus.</li>
383: * <li>If the specified window has the same requested input but not the
384: * requested perspective, then the window is given focus and the perspective
385: * is opened and shown on condition that the user preference is not to open
386: * perspectives in a new window.</li>
387: * <li>Otherwise the requested perspective is opened and shown in a new
388: * window, and the window is given focus.</li>
389: * </ul>
390: * </p>
391: * <p>
392: * The workbench also defines a number of menu items to activate or open
393: * each registered perspective. A complete list of these perspectives is
394: * available from the perspective registry found on <code>IWorkbench</code>.
395: * </p>
396: *
397: * @param perspectiveId
398: * the perspective ID to show
399: * @param window
400: * the workbench window of the action calling this method.
401: * @param input
402: * the page input, or <code>null</code> if there is no current
403: * input. This is used to seed the input for the page's views
404: * @return the workbench page that the perspective was shown
405: * @exception WorkbenchException
406: * if the perspective could not be shown
407: *
408: * @since 2.0
409: */
410: public IWorkbenchPage showPerspective(String perspectiveId,
411: IWorkbenchWindow window, IAdaptable input)
412: throws WorkbenchException;
413:
414: /**
415: * Returns the decorator manager.
416: * <p>
417: * Any client using the decorator manager should come up with the text and
418: * image for the element (including any of the part's own decorations)
419: * before calling the decorator manager. It should also add a listener to be
420: * notified when decorations change.
421: * </p>
422: * <p>
423: * Note that if the element implements <code>IAdaptable</code>,
424: * decorators may use this mechanism to obtain an adapter (for example an
425: * <code>IResource</code>), and derive the decoration from the adapter
426: * rather than the element. Since the adapter may differ from the original
427: * element, those using the decorator manager should be prepared to handle
428: * notification that the decoration for the adapter has changed, in addition
429: * to handling notification that the decoration for the element has changed.
430: * That is, it needs to be able to map back from the adapter to the element.
431: * </p>
432: *
433: * @return the decorator manager
434: */
435: public IDecoratorManager getDecoratorManager();
436:
437: /**
438: * Save all dirty editors in the workbench. Opens a dialog to prompt the
439: * user if <code>confirm</code> is true. Return true if successful. Return
440: * false if the user has canceled the command.
441: *
442: * @param confirm <code>true</code> to ask the user before saving unsaved
443: * changes (recommended), and <code>false</code> to save
444: * unsaved changes without asking
445: * @return <code>true</code> if the command succeeded, and
446: * <code>false</code> if the operation was canceled by the user or
447: * an error occurred while saving
448: */
449: public boolean saveAllEditors(boolean confirm);
450:
451: /**
452: * Returns the element factory with the given id.
453: *
454: * @param factoryId
455: * the id of the element factory
456: * @return the element factory, or <code>null</code> if none
457: * @see IElementFactory
458: * @since 3.0
459: */
460: public IElementFactory getElementFactory(String factoryId);
461:
462: /**
463: * Returns an interface to manage activities at the workbench level.
464: *
465: * @return an interface to manage activities at the workbench level.
466: * Guaranteed not to be <code>null</code>.
467: * @since 3.0
468: */
469: IWorkbenchActivitySupport getActivitySupport();
470:
471: /**
472: * Returns an interface to manage commands at the workbench level.
473: *
474: * @return an interface to manage commands at the workbench level.
475: * Guaranteed not to be <code>null</code>.
476: * @since 3.0
477: * @deprecated Please use {@link IServiceLocator#getService(Class)} instead.
478: * @see ICommandService
479: * @see IHandlerService
480: */
481: IWorkbenchCommandSupport getCommandSupport();
482:
483: /**
484: * Returns an interface to manage contexts at the workbench level.
485: *
486: * @return an interface to manage contexts at the workbench level.
487: * Guaranteed not to be <code>null</code>.
488: * @since 3.0
489: * @deprecated Please use {@link IServiceLocator#getService(Class)} instead.
490: * @see IContextService
491: */
492: IWorkbenchContextSupport getContextSupport();
493:
494: /**
495: * Return the theme manager for this workbench.
496: *
497: * @return the theme manager for this workbench.Guaranteed not to be
498: * <code>null</code>.
499: * @since 3.0
500: */
501: public IThemeManager getThemeManager();
502:
503: /**
504: * Return the intro manager for this workbench.
505: *
506: * @return the intro manager for this workbench. Guaranteed not to be
507: * <code>null</code>.
508: * @since 3.0
509: */
510: public IIntroManager getIntroManager();
511:
512: /**
513: * Return the help system for this workbench.
514: *
515: * @return the help system
516: * @since 3.1
517: */
518: public IWorkbenchHelpSystem getHelpSystem();
519:
520: /**
521: * Return the browser support for this workbench.
522: *
523: * @return the browser support system
524: * @since 3.1
525: */
526: public IWorkbenchBrowserSupport getBrowserSupport();
527:
528: /**
529: * Returns a boolean indicating whether the workbench is in the process of
530: * closing.
531: *
532: * @return <code>true</code> if the workbench is in the process of
533: * closing, <code>false</code> otherwise
534: * @since 3.1
535: */
536: public boolean isClosing();
537:
538: /**
539: * <p>
540: * Return the extension tracker for the workbench. This tracker may be used
541: * by plug-ins to ensure responsiveness to changes to the plug-in registry.
542: * </p>
543: * <p>
544: * The tracker at this level of the workbench is typically used to track
545: * elements that persist for the life of the workbench. For example,
546: * <code>IEditorDescriptor</code> objects fall into this category.
547: * </p>
548: *
549: * @return the extension tracker
550: * @see IWorkbenchWindow#getExtensionTracker()
551: * @see IWorkbenchPage#getExtensionTracker()
552: * @since 3.1
553: */
554: public IExtensionTracker getExtensionTracker();
555:
556: /**
557: * Returns the view registry for the workbench.
558: *
559: * @return the workbench view registry
560: * @since 3.1
561: */
562: public IViewRegistry getViewRegistry();
563:
564: /**
565: * Return the new wizard registry.
566: *
567: * @return the new wizard registry
568: * @since 3.1
569: */
570: public IWizardRegistry getNewWizardRegistry();
571:
572: /**
573: * Return the import wizard registry.
574: *
575: * @return the import wizard registry
576: * @since 3.1
577: */
578: public IWizardRegistry getImportWizardRegistry();
579:
580: /**
581: * Return the export wizard registry.
582: *
583: * @return the export wizard registry
584: * @since 3.1
585: */
586: public IWizardRegistry getExportWizardRegistry();
587:
588: /**
589: * Save all dirty saveables in the workbench that match the given filter.
590: * Opens a dialog to prompt the user if <code>confirm</code> is true.
591: * Return true if successful. Return false if the user has canceled the
592: * command.
593: *
594: * @since 3.3
595: *
596: * @param shellProvider the provider used to obtain a shell in prompting is
597: * required. Clients can use a workbench window for this.
598: * @param runnableContext a runnable context that will be used to provide a
599: * progress monitor while the save is taking place. Clients can
600: * use a workbench window for this.
601: * @param filter the filter used to determine if a particular dirty saveable
602: * needs to be saved or <code>null</code> if all dirty
603: * saveables should be saved.
604: * @param confirm <code>true</code> to ask the user before saving unsaved
605: * changes (recommended), and <code>false</code> to save
606: * unsaved changes without asking
607: * @return <code>true</code> if the command succeeded, and
608: * <code>false</code> if the operation was canceled by the user or
609: * an error occurred while saving
610: */
611: public boolean saveAll(IShellProvider shellProvider,
612: IRunnableContext runnableContext, ISaveableFilter filter,
613: boolean confirm);
614: }
|