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