KickJava   Java API By Example, From Geeks To Geeks.

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


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 java.lang.reflect.InvocationTargetException JavaDoc;
14
15 import org.eclipse.core.runtime.IAdaptable;
16 import org.eclipse.core.runtime.dynamichelpers.IExtensionTracker;
17 import org.eclipse.jface.operation.IRunnableContext;
18 import org.eclipse.jface.operation.IRunnableWithProgress;
19 import org.eclipse.jface.window.IShellProvider;
20 import org.eclipse.swt.widgets.Shell;
21 import org.eclipse.ui.commands.ICommandService;
22 import org.eclipse.ui.contexts.IContextService;
23 import org.eclipse.ui.handlers.IHandlerService;
24 import org.eclipse.ui.keys.IBindingService;
25 import org.eclipse.ui.services.IServiceLocator;
26
27 /**
28  * A workbench window is a top level window in a workbench. Visually, a
29  * workbench window has a menubar, a toolbar, a status bar, and a main area for
30  * displaying a single page consisting of a collection of views and editors.
31  * <p>
32  * Each workbench window has a collection of 0 or more pages; the active page is
33  * the one that is being presented to the end user; at most one page is active
34  * in a window at a time.
35  * </p>
36  * <p>
37  * The workbench window supports a few {@link IServiceLocator services} by
38  * default. If these services are used to allocate resources, it is important to
39  * remember to clean up those resources after you are done with them. Otherwise,
40  * the resources will exist until the workbench window is closed. The supported
41  * services are:
42  * </p>
43  * <ul>
44  * <li>{@link ICommandService}</li>
45  * <li>{@link IContextService}</li>
46  * <li>{@link IHandlerService}</li>
47  * <li>{@link IBindingService}. Resources allocated through this service will
48  * not be cleaned up until the workbench shuts down.</li>
49  * </ul>
50  * <p>
51  * This interface is not intended to be implemented by clients.
52  * </p>
53  *
54  * @see IWorkbenchPage
55  */

56 public interface IWorkbenchWindow extends IPageService, IRunnableContext,
57         IServiceLocator, IShellProvider {
58     /**
59      * Closes this workbench window.
60      * <p>
61      * If the window has an open editor with unsaved content, the user will be
62      * given the opportunity to save it.
63      * </p>
64      *
65      * @return <code>true</code> if the window was successfully closed, and
66      * <code>false</code> if it is still open
67      */

68     public boolean close();
69
70     /**
71      * Returns the currently active page for this workbench window.
72      *
73      * @return the active page, or <code>null</code> if none
74      */

75     public IWorkbenchPage getActivePage();
76
77     /**
78      * Returns a list of the pages in this workbench window.
79      * <p>
80      * Note that each window has its own pages; pages are never shared between
81      * different windows.
82      * </p>
83      *
84      * @return a list of pages
85      */

86     public IWorkbenchPage[] getPages();
87
88     /**
89      * Returns the part service which tracks part activation within this
90      * workbench window.
91      *
92      * @return the part service
93      */

94     public IPartService getPartService();
95
96     /**
97      * Returns the selection service which tracks selection within this
98      * workbench window.
99      *
100      * @return the selection service
101      */

102     public ISelectionService getSelectionService();
103
104     /**
105      * Returns this workbench window's shell.
106      *
107      * @return the shell containing this window's controls or <code>null</code>
108      * if the shell has not been created yet or if the window has been closed
109      */

110     public Shell getShell();
111
112     /**
113      * Returns the workbench for this window.
114      *
115      * @return the workbench
116      */

117     public IWorkbench getWorkbench();
118
119     /**
120      * Returns whether the specified menu is an application menu as opposed to
121      * a part menu. Application menus contain items which affect the workbench
122      * or window. Part menus contain items which affect the active part (view
123      * or editor).
124      * <p>
125      * This is typically used during "in place" editing. Application menus
126      * should be preserved during menu merging. All other menus may be removed
127      * from the window.
128      * </p>
129      *
130      * @param menuId
131      * the menu id
132      * @return <code>true</code> if the specified menu is an application
133      * menu, and <code>false</code> if it is not
134      */

135     public boolean isApplicationMenu(String JavaDoc menuId);
136
137     /**
138      * Creates and opens a new workbench page. The perspective of the new page
139      * is defined by the specified perspective ID. The new page become active.
140      * <p>
141      * <b>Note:</b> Since release 2.0, a window is limited to contain at most
142      * one page. If a page exist in the window when this method is used, then
143      * another window is created for the new page. Callers are strongly
144      * recommended to use the <code>IWorkbench.showPerspective</code> APIs to
145      * programmatically show a perspective.
146      * </p>
147      *
148      * @param perspectiveId
149      * the perspective id for the window's initial page
150      * @param input
151      * the page input, or <code>null</code> if there is no current
152      * input. This is used to seed the input for the new page's
153      * views.
154      * @return the new workbench page
155      * @exception WorkbenchException
156      * if a page could not be opened
157      *
158      * @see IWorkbench#showPerspective(String, IWorkbenchWindow, IAdaptable)
159      */

160     public IWorkbenchPage openPage(String JavaDoc perspectiveId, IAdaptable input)
161             throws WorkbenchException;
162
163     /**
164      * Creates and opens a new workbench page. The default perspective is used
165      * as a template for creating the page. The page becomes active.
166      * <p>
167      * <b>Note:</b> Since release 2.0, a window is limited to contain at most
168      * one page. If a page exist in the window when this method is used, then
169      * another window is created for the new page. Callers are strongly
170      * recommended to use the <code>IWorkbench.showPerspective</code> APIs to
171      * programmatically show a perspective.
172      * </p>
173      *
174      * @param input
175      * the page input, or <code>null</code> if there is no current
176      * input. This is used to seed the input for the new page's
177      * views.
178      * @return the new workbench window
179      * @exception WorkbenchException
180      * if a page could not be opened
181      *
182      * @see IWorkbench#showPerspective(String, IWorkbenchWindow, IAdaptable)
183      */

184     public IWorkbenchPage openPage(IAdaptable input) 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, IRunnableWithProgress runnable) throws InvocationTargetException JavaDoc, InterruptedException JavaDoc;
199
200     /**
201      * Sets or clears the currently active page for this workbench window.
202      *
203      * @param page
204      * the new active page
205      */

206     public void setActivePage(IWorkbenchPage page);
207     
208     /**
209      * <p>
210      * Return the extension tracker for the workbench. This tracker may be used
211      * by plug-ins to ensure responsiveness to changes to the plug-in registry.
212      * </p>
213      * <p>
214      * The tracker at this level of the workbench is typically used to track
215      * elements that persist for the life of the workbench. For example, the
216      * action objects corresponding to new wizards contributed by plug-ins fall
217      * into this category.
218      * </p>
219      *
220      * @return the extension tracker
221      * @see IWorkbench#getExtensionTracker()
222      * @see IWorkbenchPage#getExtensionTracker()
223      * @since 3.1
224      */

225     public IExtensionTracker getExtensionTracker();
226 }
227
Popular Tags