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  ;
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   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   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  , InterruptedException  ;
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags