IWorkbenchConfigurer


1   /*******************************************************************************
2    * Copyright (c) 2003, 2005 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.application;
12  
13  import org.eclipse.core.runtime.IAdaptable;
14  import org.eclipse.core.runtime.IStatus;
15  import org.eclipse.jface.resource.ImageDescriptor;
16  import org.eclipse.jface.window.WindowManager;
17  import org.eclipse.ui.IMemento;
18  import org.eclipse.ui.IWorkbench;
19  import org.eclipse.ui.IWorkbenchWindow;
20  import org.eclipse.ui.WorkbenchException;
21  
22  /**
23   * Interface providing special access for configuring the workbench.
24   * <p>
25   * Note that these objects are only available to the main application
26   * (the plug-in that creates and owns the workbench).
27   * </p>
28   * <p>
29   * This interface is not intended to be implemented by clients.
30   * </p>
31   * 
32   * @see WorkbenchAdvisor#initialize
33   * @since 3.0
34   */
35  public interface IWorkbenchConfigurer {
36  
37      /**
38       * Restore status code indicating that the saved state
39       * could not be restored, but that startup should continue
40       * with a reset state.
41       * 
42       * @see #restoreState
43       */
44      public static final int RESTORE_CODE_RESET = 1;
45  
46      /**
47       * Restore status code indicating that the saved state
48       * could not be restored, and that the application
49       * must exit immediately without modifying any previously
50       * saved workbench state.
51       */
52      public static final int RESTORE_CODE_EXIT = 2;
53  
54      /**
55       * Returns the underlying workbench.
56       * 
57       * @return the workbench
58       */
59      public IWorkbench getWorkbench();
60  
61      /**
62       * Returns whether the workbench state should be saved on close and 
63       * restored on subsequent open.  
64       * <p>
65       * The initial value is <code>false</code>.
66       * </p>
67       * 
68       * @return <code>true</code> to save and restore workbench state, or
69       *  <code>false</code> to forget current workbench state on close.
70       */
71      public boolean getSaveAndRestore();
72  
73      /**
74       * Sets whether the workbench state should be saved on close and 
75       * restored on subsequent open.
76       * 
77       * @param enabled <code>true</code> to save and restore workbench state, or
78       *  <code>false</code> to forget current workbench state on close.
79       */
80      public void setSaveAndRestore(boolean enabled);
81      
82      /**
83       * Restores a workbench window from the given memento.
84       * 
85       * @param memento the memento from which to restore the window's state
86       * @return the configurer for the restored window
87       * @throws WorkbenchException if an error occurred during the restore
88       * @see IWorkbenchWindowConfigurer#saveState(IMemento)
89       * @since 3.1
90       */
91      public IWorkbenchWindowConfigurer restoreWorkbenchWindow(IMemento memento)
92              throws WorkbenchException;
93  
94      /**
95       * Returns the workbench window manager.
96       *
97       * @return the workbench window manager
98       * 
99       * Note:IWorkbenchWindow is implemented using JFace's Window (and therefore uses WindowManager), 
100      *   but this is an implementation detail
101      */
102     public WindowManager getWorkbenchWindowManager();
103 
104     /**
105      * Declares a workbench image.
106      * <p>
107      * The workbench remembers the given image descriptor under the given name,
108      * and makes the image available to plug-ins via
109      * {@link IWorkbench#getSharedImages() IWorkbench.getSharedImages()}.
110      * For "shared" images, the workbench remembers the image descriptor and
111      * will manages the image object create from it; clients retrieve "shared"
112      * images via
113      * {@link org.eclipse.ui.ISharedImages#getImage ISharedImages.getImage()}.
114      * For the other, "non-shared" images, the workbench remembers only the
115      * image descriptor; clients retrieve the image descriptor via
116      * {@link org.eclipse.ui.ISharedImages#getImageDescriptor
117      * ISharedImages.getImageDescriptor()} and are entirely
118      * responsible for managing the image objects they create from it.
119      * (This is made confusing by the historical fact that the API interface
120      *  is called "ISharedImages".)
121      * </p>
122      * 
123      * @param symbolicName the symbolic name of the image
124      * @param descriptor the image descriptor
125      * @param shared <code>true</code> if this is a shared image, and
126      * <code>false</code> if this is not a shared image
127      * @see org.eclipse.ui.ISharedImages#getImage
128      * @see org.eclipse.ui.ISharedImages#getImageDescriptor
129      */
130     public void declareImage(String   symbolicName, ImageDescriptor descriptor,
131             boolean shared);
132 
133     /**
134      * Forces the workbench to close due to an emergency. This method should
135      * only be called when the workbench is in dire straights and cannot
136      * continue, and cannot even risk a normal workbench close (think "out of
137      * memory" or "unable to create shell"). When this method is called, an
138      * abbreviated workbench shutdown sequence is performed (less critical
139      * steps may be skipped). The workbench advisor is still called; however,
140      * it must not attempt to communicate with the user. While an emergency
141      * close is in progress, <code>emergencyClosing</code> returns
142      * <code>true</code>. Workbench advisor methods should always check this
143      * flag before communicating with the user.
144      * 
145      * @see #emergencyClosing
146      */
147     public void emergencyClose();
148 
149     /**
150      * Returns whether the workbench is being closed due to an emergency.
151      * When this method returns <code>true</code>, the workbench is in dire
152      * straights and cannot continue. Indeed, things are so bad that we cannot
153      * even risk a normal workbench close. Workbench advisor methods should
154      * always check this flag before attempting to communicate with the user.
155      * 
156      * @return <code>true</code> if the workbench is in the process of being
157      * closed under emergency conditions, and <code>false</code> otherwise
158      */
159     public boolean emergencyClosing();
160 
161     /**
162      * Returns an object that can be used to configure the given window.
163      * 
164      * @param window a workbench window
165      * @return a workbench window configurer
166      */
167     public IWorkbenchWindowConfigurer getWindowConfigurer(
168             IWorkbenchWindow window);
169 
170     /**
171      * Returns the data associated with the workbench at the given key.
172      * 
173      * @param key the key
174      * @return the data, or <code>null</code> if there is no data at the given
175      * key
176      */
177     public Object   getData(String   key);
178 
179     /**
180      * Sets the data associated with the workbench at the given key.
181      * 
182      * @param key the key
183      * @param data the data, or <code>null</code> to delete existing data
184      */
185     public void setData(String   key, Object   data);
186 
187     /**
188      * Restores the workbench state saved from the previous session, if any.
189      * This includes any open windows and their open perspectives, open views
190      * and editors, layout information, and any customizations to the open 
191      * perspectives. 
192      * <p>
193      * This is typically called from the advisor's <code>openWindows()</code>
194      * method.
195      * </p>
196      * 
197      * @return a status object indicating whether the restore was successful
198      * @see #RESTORE_CODE_RESET
199      * @see #RESTORE_CODE_EXIT
200      * @see WorkbenchAdvisor#openWindows
201      */
202     public IStatus restoreState();
203 
204     /**
205      * Opens the first time window, using the default perspective and
206      * default page input.
207      * <p>
208      * This is typically called from the advisor's <code>openWindows()</code>
209      * method.
210      * </p>
211      * 
212      * @see WorkbenchAdvisor#openWindows
213      */
214     public void openFirstTimeWindow();
215     
216     /**
217      * Returns <code>true</code> if the workbench should exit when the last
218      * window is closed, <code>false</code> if the window should just be
219      * closed, leaving the workbench (and its event loop) running.
220      * <p>
221      * If <code>true</code>, the last window's state is saved before closing,
222      * so that it will be restored in the next session. This applies only if
223      * {@link #getSaveAndRestore() returns <code>true</code>}).
224      * </p>
225      * <p>
226      * If <code>false</code>, the window is simply closed, losing its state.
227      * </p>
228      * <p>
229      * If the workbench is left running, it can be closed using
230      * {@link IWorkbench#close()}, or a new window can be opened using
231      * {@link IWorkbench#openWorkbenchWindow(String, IAdaptable)}.
232      * </p>
233      * <p>
234      * The initial value is <code>true</code>.
235      * </p>
236      * 
237      * @return <code>true</code> if the workbench will exit when the last
238      *         window is closed, <code>false</code> if the window should just
239      *         be closed
240      * @since 3.1
241      */
242     public boolean getExitOnLastWindowClose();
243     
244     /**
245      * Sets whether the workbench should exit when the last window is closed, or
246      * whether the window should just be closed, leaving the workbench (and its
247      * event loop) running.
248      * <p>
249      * For more details, see {@link #getExitOnLastWindowClose()}.
250      * </p>
251      * 
252      * @param enabled
253      *            <code>true</code> if the workbench should exit when the last
254      *            window is closed, <code>false</code> if the window should
255      *            just be closed
256      * @since 3.1
257      */
258     public void setExitOnLastWindowClose(boolean enabled);
259 }
260
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags