001: /*******************************************************************************
002: * Copyright (c) 2003, 2005 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.application;
011:
012: import org.eclipse.core.runtime.IAdaptable;
013: import org.eclipse.core.runtime.IStatus;
014: import org.eclipse.jface.resource.ImageDescriptor;
015: import org.eclipse.jface.window.WindowManager;
016: import org.eclipse.ui.IMemento;
017: import org.eclipse.ui.IWorkbench;
018: import org.eclipse.ui.IWorkbenchWindow;
019: import org.eclipse.ui.WorkbenchException;
020:
021: /**
022: * Interface providing special access for configuring the workbench.
023: * <p>
024: * Note that these objects are only available to the main application
025: * (the plug-in that creates and owns the workbench).
026: * </p>
027: * <p>
028: * This interface is not intended to be implemented by clients.
029: * </p>
030: *
031: * @see WorkbenchAdvisor#initialize
032: * @since 3.0
033: */
034: public interface IWorkbenchConfigurer {
035:
036: /**
037: * Restore status code indicating that the saved state
038: * could not be restored, but that startup should continue
039: * with a reset state.
040: *
041: * @see #restoreState
042: */
043: public static final int RESTORE_CODE_RESET = 1;
044:
045: /**
046: * Restore status code indicating that the saved state
047: * could not be restored, and that the application
048: * must exit immediately without modifying any previously
049: * saved workbench state.
050: */
051: public static final int RESTORE_CODE_EXIT = 2;
052:
053: /**
054: * Returns the underlying workbench.
055: *
056: * @return the workbench
057: */
058: public IWorkbench getWorkbench();
059:
060: /**
061: * Returns whether the workbench state should be saved on close and
062: * restored on subsequent open.
063: * <p>
064: * The initial value is <code>false</code>.
065: * </p>
066: *
067: * @return <code>true</code> to save and restore workbench state, or
068: * <code>false</code> to forget current workbench state on close.
069: */
070: public boolean getSaveAndRestore();
071:
072: /**
073: * Sets whether the workbench state should be saved on close and
074: * restored on subsequent open.
075: *
076: * @param enabled <code>true</code> to save and restore workbench state, or
077: * <code>false</code> to forget current workbench state on close.
078: */
079: public void setSaveAndRestore(boolean enabled);
080:
081: /**
082: * Restores a workbench window from the given memento.
083: *
084: * @param memento the memento from which to restore the window's state
085: * @return the configurer for the restored window
086: * @throws WorkbenchException if an error occurred during the restore
087: * @see IWorkbenchWindowConfigurer#saveState(IMemento)
088: * @since 3.1
089: */
090: public IWorkbenchWindowConfigurer restoreWorkbenchWindow(
091: IMemento memento) throws WorkbenchException;
092:
093: /**
094: * Returns the workbench window manager.
095: *
096: * @return the workbench window manager
097: *
098: * Note:IWorkbenchWindow is implemented using JFace's Window (and therefore uses WindowManager),
099: * but this is an implementation detail
100: */
101: public WindowManager getWorkbenchWindowManager();
102:
103: /**
104: * Declares a workbench image.
105: * <p>
106: * The workbench remembers the given image descriptor under the given name,
107: * and makes the image available to plug-ins via
108: * {@link IWorkbench#getSharedImages() IWorkbench.getSharedImages()}.
109: * For "shared" images, the workbench remembers the image descriptor and
110: * will manages the image object create from it; clients retrieve "shared"
111: * images via
112: * {@link org.eclipse.ui.ISharedImages#getImage ISharedImages.getImage()}.
113: * For the other, "non-shared" images, the workbench remembers only the
114: * image descriptor; clients retrieve the image descriptor via
115: * {@link org.eclipse.ui.ISharedImages#getImageDescriptor
116: * ISharedImages.getImageDescriptor()} and are entirely
117: * responsible for managing the image objects they create from it.
118: * (This is made confusing by the historical fact that the API interface
119: * is called "ISharedImages".)
120: * </p>
121: *
122: * @param symbolicName the symbolic name of the image
123: * @param descriptor the image descriptor
124: * @param shared <code>true</code> if this is a shared image, and
125: * <code>false</code> if this is not a shared image
126: * @see org.eclipse.ui.ISharedImages#getImage
127: * @see org.eclipse.ui.ISharedImages#getImageDescriptor
128: */
129: public void declareImage(String symbolicName,
130: ImageDescriptor descriptor, boolean shared);
131:
132: /**
133: * Forces the workbench to close due to an emergency. This method should
134: * only be called when the workbench is in dire straights and cannot
135: * continue, and cannot even risk a normal workbench close (think "out of
136: * memory" or "unable to create shell"). When this method is called, an
137: * abbreviated workbench shutdown sequence is performed (less critical
138: * steps may be skipped). The workbench advisor is still called; however,
139: * it must not attempt to communicate with the user. While an emergency
140: * close is in progress, <code>emergencyClosing</code> returns
141: * <code>true</code>. Workbench advisor methods should always check this
142: * flag before communicating with the user.
143: *
144: * @see #emergencyClosing
145: */
146: public void emergencyClose();
147:
148: /**
149: * Returns whether the workbench is being closed due to an emergency.
150: * When this method returns <code>true</code>, the workbench is in dire
151: * straights and cannot continue. Indeed, things are so bad that we cannot
152: * even risk a normal workbench close. Workbench advisor methods should
153: * always check this flag before attempting to communicate with the user.
154: *
155: * @return <code>true</code> if the workbench is in the process of being
156: * closed under emergency conditions, and <code>false</code> otherwise
157: */
158: public boolean emergencyClosing();
159:
160: /**
161: * Returns an object that can be used to configure the given window.
162: *
163: * @param window a workbench window
164: * @return a workbench window configurer
165: */
166: public IWorkbenchWindowConfigurer getWindowConfigurer(
167: IWorkbenchWindow window);
168:
169: /**
170: * Returns the data associated with the workbench at the given key.
171: *
172: * @param key the key
173: * @return the data, or <code>null</code> if there is no data at the given
174: * key
175: */
176: public Object getData(String key);
177:
178: /**
179: * Sets the data associated with the workbench at the given key.
180: *
181: * @param key the key
182: * @param data the data, or <code>null</code> to delete existing data
183: */
184: public void setData(String key, Object data);
185:
186: /**
187: * Restores the workbench state saved from the previous session, if any.
188: * This includes any open windows and their open perspectives, open views
189: * and editors, layout information, and any customizations to the open
190: * perspectives.
191: * <p>
192: * This is typically called from the advisor's <code>openWindows()</code>
193: * method.
194: * </p>
195: *
196: * @return a status object indicating whether the restore was successful
197: * @see #RESTORE_CODE_RESET
198: * @see #RESTORE_CODE_EXIT
199: * @see WorkbenchAdvisor#openWindows
200: */
201: public IStatus restoreState();
202:
203: /**
204: * Opens the first time window, using the default perspective and
205: * default page input.
206: * <p>
207: * This is typically called from the advisor's <code>openWindows()</code>
208: * method.
209: * </p>
210: *
211: * @see WorkbenchAdvisor#openWindows
212: */
213: public void openFirstTimeWindow();
214:
215: /**
216: * Returns <code>true</code> if the workbench should exit when the last
217: * window is closed, <code>false</code> if the window should just be
218: * closed, leaving the workbench (and its event loop) running.
219: * <p>
220: * If <code>true</code>, the last window's state is saved before closing,
221: * so that it will be restored in the next session. This applies only if
222: * {@link #getSaveAndRestore() returns <code>true</code>}).
223: * </p>
224: * <p>
225: * If <code>false</code>, the window is simply closed, losing its state.
226: * </p>
227: * <p>
228: * If the workbench is left running, it can be closed using
229: * {@link IWorkbench#close()}, or a new window can be opened using
230: * {@link IWorkbench#openWorkbenchWindow(String, IAdaptable)}.
231: * </p>
232: * <p>
233: * The initial value is <code>true</code>.
234: * </p>
235: *
236: * @return <code>true</code> if the workbench will exit when the last
237: * window is closed, <code>false</code> if the window should just
238: * be closed
239: * @since 3.1
240: */
241: public boolean getExitOnLastWindowClose();
242:
243: /**
244: * Sets whether the workbench should exit when the last window is closed, or
245: * whether the window should just be closed, leaving the workbench (and its
246: * event loop) running.
247: * <p>
248: * For more details, see {@link #getExitOnLastWindowClose()}.
249: * </p>
250: *
251: * @param enabled
252: * <code>true</code> if the workbench should exit when the last
253: * window is closed, <code>false</code> if the window should
254: * just be closed
255: * @since 3.1
256: */
257: public void setExitOnLastWindowClose(boolean enabled);
258: }
|