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 java.lang.reflect.InvocationTargetException;
013:
014: import org.eclipse.core.runtime.IAdaptable;
015: import org.eclipse.core.runtime.dynamichelpers.IExtensionTracker;
016: import org.eclipse.jface.operation.IRunnableContext;
017: import org.eclipse.jface.operation.IRunnableWithProgress;
018: import org.eclipse.jface.window.IShellProvider;
019: import org.eclipse.swt.widgets.Shell;
020: import org.eclipse.ui.commands.ICommandService;
021: import org.eclipse.ui.contexts.IContextService;
022: import org.eclipse.ui.handlers.IHandlerService;
023: import org.eclipse.ui.keys.IBindingService;
024: import org.eclipse.ui.services.IServiceLocator;
025:
026: /**
027: * A workbench window is a top level window in a workbench. Visually, a
028: * workbench window has a menubar, a toolbar, a status bar, and a main area for
029: * displaying a single page consisting of a collection of views and editors.
030: * <p>
031: * Each workbench window has a collection of 0 or more pages; the active page is
032: * the one that is being presented to the end user; at most one page is active
033: * in a window at a time.
034: * </p>
035: * <p>
036: * The workbench window supports a few {@link IServiceLocator services} by
037: * default. If these services are used to allocate resources, it is important to
038: * remember to clean up those resources after you are done with them. Otherwise,
039: * the resources will exist until the workbench window is closed. The supported
040: * services are:
041: * </p>
042: * <ul>
043: * <li>{@link ICommandService}</li>
044: * <li>{@link IContextService}</li>
045: * <li>{@link IHandlerService}</li>
046: * <li>{@link IBindingService}. Resources allocated through this service will
047: * not be cleaned up until the workbench shuts down.</li>
048: * </ul>
049: * <p>
050: * This interface is not intended to be implemented by clients.
051: * </p>
052: *
053: * @see IWorkbenchPage
054: */
055: public interface IWorkbenchWindow extends IPageService,
056: IRunnableContext, IServiceLocator, IShellProvider {
057: /**
058: * Closes this workbench window.
059: * <p>
060: * If the window has an open editor with unsaved content, the user will be
061: * given the opportunity to save it.
062: * </p>
063: *
064: * @return <code>true</code> if the window was successfully closed, and
065: * <code>false</code> if it is still open
066: */
067: public boolean close();
068:
069: /**
070: * Returns the currently active page for this workbench window.
071: *
072: * @return the active page, or <code>null</code> if none
073: */
074: public IWorkbenchPage getActivePage();
075:
076: /**
077: * Returns a list of the pages in this workbench window.
078: * <p>
079: * Note that each window has its own pages; pages are never shared between
080: * different windows.
081: * </p>
082: *
083: * @return a list of pages
084: */
085: public IWorkbenchPage[] getPages();
086:
087: /**
088: * Returns the part service which tracks part activation within this
089: * workbench window.
090: *
091: * @return the part service
092: */
093: public IPartService getPartService();
094:
095: /**
096: * Returns the selection service which tracks selection within this
097: * workbench window.
098: *
099: * @return the selection service
100: */
101: public ISelectionService getSelectionService();
102:
103: /**
104: * Returns this workbench window's shell.
105: *
106: * @return the shell containing this window's controls or <code>null</code>
107: * if the shell has not been created yet or if the window has been closed
108: */
109: public Shell getShell();
110:
111: /**
112: * Returns the workbench for this window.
113: *
114: * @return the workbench
115: */
116: public IWorkbench getWorkbench();
117:
118: /**
119: * Returns whether the specified menu is an application menu as opposed to
120: * a part menu. Application menus contain items which affect the workbench
121: * or window. Part menus contain items which affect the active part (view
122: * or editor).
123: * <p>
124: * This is typically used during "in place" editing. Application menus
125: * should be preserved during menu merging. All other menus may be removed
126: * from the window.
127: * </p>
128: *
129: * @param menuId
130: * the menu id
131: * @return <code>true</code> if the specified menu is an application
132: * menu, and <code>false</code> if it is not
133: */
134: public boolean isApplicationMenu(String menuId);
135:
136: /**
137: * Creates and opens a new workbench page. The perspective of the new page
138: * is defined by the specified perspective ID. The new page become active.
139: * <p>
140: * <b>Note:</b> Since release 2.0, a window is limited to contain at most
141: * one page. If a page exist in the window when this method is used, then
142: * another window is created for the new page. Callers are strongly
143: * recommended to use the <code>IWorkbench.showPerspective</code> APIs to
144: * programmatically show a perspective.
145: * </p>
146: *
147: * @param perspectiveId
148: * the perspective id for the window's initial page
149: * @param input
150: * the page input, or <code>null</code> if there is no current
151: * input. This is used to seed the input for the new page's
152: * views.
153: * @return the new workbench page
154: * @exception WorkbenchException
155: * if a page could not be opened
156: *
157: * @see IWorkbench#showPerspective(String, IWorkbenchWindow, IAdaptable)
158: */
159: public IWorkbenchPage openPage(String perspectiveId,
160: IAdaptable input) throws WorkbenchException;
161:
162: /**
163: * Creates and opens a new workbench page. The default perspective is used
164: * as a template for creating the page. The page becomes active.
165: * <p>
166: * <b>Note:</b> Since release 2.0, a window is limited to contain at most
167: * one page. If a page exist in the window when this method is used, then
168: * another window is created for the new page. Callers are strongly
169: * recommended to use the <code>IWorkbench.showPerspective</code> APIs to
170: * programmatically show a perspective.
171: * </p>
172: *
173: * @param input
174: * the page input, or <code>null</code> if there is no current
175: * input. This is used to seed the input for the new page's
176: * views.
177: * @return the new workbench window
178: * @exception WorkbenchException
179: * if a page could not be opened
180: *
181: * @see IWorkbench#showPerspective(String, IWorkbenchWindow, IAdaptable)
182: */
183: public IWorkbenchPage openPage(IAdaptable input)
184: throws WorkbenchException;
185:
186: /**
187: * This specialization of IRunnableContext#run(boolean, boolean,
188: * IRunnableWithProgress) blocks until the runnable has been run,
189: * regardless of the value of <code>fork</code>.
190: * It is recommended that <code>fork</code> is set to
191: * true in most cases. If <code>fork</code> is set to <code>false</code>,
192: * the runnable will run in the UI thread and it is the runnable's
193: * responsibility to call <code>Display.readAndDispatch()</code>
194: * to ensure UI responsiveness.
195: *
196: * @since 3.2
197: */
198: public void run(boolean fork, boolean cancelable,
199: IRunnableWithProgress runnable)
200: throws InvocationTargetException, InterruptedException;
201:
202: /**
203: * Sets or clears the currently active page for this workbench window.
204: *
205: * @param page
206: * the new active page
207: */
208: public void setActivePage(IWorkbenchPage page);
209:
210: /**
211: * <p>
212: * Return the extension tracker for the workbench. This tracker may be used
213: * by plug-ins to ensure responsiveness to changes to the plug-in registry.
214: * </p>
215: * <p>
216: * The tracker at this level of the workbench is typically used to track
217: * elements that persist for the life of the workbench. For example, the
218: * action objects corresponding to new wizards contributed by plug-ins fall
219: * into this category.
220: * </p>
221: *
222: * @return the extension tracker
223: * @see IWorkbench#getExtensionTracker()
224: * @see IWorkbenchPage#getExtensionTracker()
225: * @since 3.1
226: */
227: public IExtensionTracker getExtensionTracker();
228: }
|