KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > application > WorkbenchWindowAdvisor


1 /*******************************************************************************
2  * Copyright (c) 2005, 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.application;
12
13 import org.eclipse.core.runtime.Assert;
14 import org.eclipse.core.runtime.IStatus;
15 import org.eclipse.core.runtime.Status;
16 import org.eclipse.swt.widgets.Composite;
17 import org.eclipse.swt.widgets.Control;
18 import org.eclipse.swt.widgets.Shell;
19 import org.eclipse.ui.IMemento;
20 import org.eclipse.ui.IWorkbenchPreferenceConstants;
21 import org.eclipse.ui.PlatformUI;
22 import org.eclipse.ui.WorkbenchException;
23 import org.eclipse.ui.actions.ActionFactory;
24 import org.eclipse.ui.internal.WorkbenchWindowConfigurer;
25 import org.eclipse.ui.internal.util.PrefUtil;
26 import org.eclipse.ui.intro.IIntroManager;
27
28 /**
29  * Public base class for configuring a workbench window.
30  * <p>
31  * The workbench window advisor object is created in response to a workbench
32  * window being created (one per window), and is used to configure the window.
33  * </p>
34  * <p>
35  * An application should declare a subclass of <code>WorkbenchWindowAdvisor</code>
36  * and override methods to configure workbench windows to suit the needs of the
37  * particular application.
38  * </p>
39  * <p>
40  * The following advisor methods are called at strategic points in the
41  * workbench window's lifecycle (as with the workbench advisor, all occur
42  * within the dynamic scope of the call to
43  * {@link PlatformUI#createAndRunWorkbench PlatformUI.createAndRunWorkbench}):
44  * <ul>
45  * <li><code>preWindowOpen</code> - called as the window is being opened;
46  * use to configure aspects of the window other than actions bars</li>
47  * <li><code>postWindowRestore</code> - called after the window has been
48  * recreated from a previously saved state; use to adjust the restored
49  * window</li>
50  * <li><code>postWindowCreate</code> - called after the window has been created,
51  * either from an initial state or from a restored state; used to adjust the
52  * window</li>
53  * <li><code>openIntro</code> - called immediately before the window is opened in
54  * order to create the introduction component, if any.</li>
55  * <li><code>postWindowOpen</code> - called after the window has been
56  * opened; use to hook window listeners, etc.</li>
57  * <li><code>preWindowShellClose</code> - called when the window's shell
58  * is closed by the user; use to pre-screen window closings</li>
59  * </ul>
60  * </p>
61  *
62  * @since 3.1
63  */

64 public class WorkbenchWindowAdvisor {
65
66     private IWorkbenchWindowConfigurer windowConfigurer;
67
68     /**
69      * Creates a new workbench window advisor for configuring a workbench
70      * window via the given workbench window configurer.
71      *
72      * @param configurer an object for configuring the workbench window
73      */

74     public WorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer) {
75         Assert.isNotNull(configurer);
76         this.windowConfigurer = configurer;
77     }
78
79     /**
80      * Returns the workbench window configurer.
81      *
82      * @return the workbench window configurer
83      */

84     protected IWorkbenchWindowConfigurer getWindowConfigurer() {
85         return windowConfigurer;
86     }
87     
88     /**
89      * Performs arbitrary actions before the window is opened.
90      * <p>
91      * This method is called before the window's controls have been created.
92      * Clients must not call this method directly (although super calls are okay).
93      * The default implementation does nothing. Subclasses may override.
94      * Typical clients will use the window configurer to tweak the
95      * workbench window in an application-specific way; however, filling the
96      * window's menu bar, tool bar, and status line must be done in
97      * {@link ActionBarAdvisor#fillActionBars}, which is called immediately
98      * after this method is called.
99      * </p>
100      */

101     public void preWindowOpen() {
102         // do nothing
103
}
104
105     /**
106      * Creates a new action bar advisor to configure the action bars of the window
107      * via the given action bar configurer.
108      * The default implementation returns a new instance of {@link ActionBarAdvisor}.
109      *
110      * @param configurer the action bar configurer for the window
111      * @return the action bar advisor for the window
112      */

113     public ActionBarAdvisor createActionBarAdvisor(IActionBarConfigurer configurer) {
114         return new ActionBarAdvisor(configurer);
115     }
116     
117     /**
118      * Performs arbitrary actions after the window has been restored,
119      * but before it is opened.
120      * <p>
121      * This method is called after a previously-saved window has been
122      * recreated. This method is not called when a new window is created from
123      * scratch. This method is never called when a workbench is started for the
124      * very first time, or when workbench state is not saved or restored.
125      * Clients must not call this method directly (although super calls are okay).
126      * The default implementation does nothing. Subclasses may override.
127      * It is okay to call <code>IWorkbench.close()</code> from this method.
128      * </p>
129      *
130      * @exception WorkbenchException thrown if there are any errors to report
131      * from post-restoration of the window
132      */

133     public void postWindowRestore() throws WorkbenchException {
134         // do nothing
135
}
136
137     /**
138      * Opens the introduction componenet.
139      * <p>
140      * Clients must not call this method directly (although super calls are okay).
141      * The default implementation opens the intro in the first window provided
142      * if the preference IWorkbenchPreferences.SHOW_INTRO is <code>true</code>. If
143      * an intro is shown then this preference will be set to <code>false</code>.
144      * Subsequently, and intro will be shown only if
145      * <code>WorkbenchConfigurer.getSaveAndRestore()</code> returns
146      * <code>true</code> and the introduction was visible on last shutdown.
147      * Subclasses may override.
148      * </p>
149      */

150     public void openIntro() {
151         // TODO: Refactor this into an IIntroManager.openIntro(IWorkbenchWindow) call
152

153         // introOpened flag needs to be global
154
IWorkbenchConfigurer wbConfig = getWindowConfigurer().getWorkbenchConfigurer();
155         final String JavaDoc key = "introOpened"; //$NON-NLS-1$
156
Boolean JavaDoc introOpened = (Boolean JavaDoc) wbConfig.getData(key);
157         if (introOpened != null && introOpened.booleanValue()) {
158             return;
159         }
160
161         wbConfig.setData(key, Boolean.TRUE);
162
163         boolean showIntro = PrefUtil.getAPIPreferenceStore().getBoolean(
164                 IWorkbenchPreferenceConstants.SHOW_INTRO);
165         
166         IIntroManager introManager = wbConfig.getWorkbench().getIntroManager();
167         
168         boolean hasIntro = introManager.hasIntro();
169         boolean isNewIntroContentAvailable = introManager.isNewContentAvailable();
170         
171         if (hasIntro && (showIntro || isNewIntroContentAvailable)) {
172             introManager
173                     .showIntro(getWindowConfigurer().getWindow(), false);
174
175             PrefUtil.getAPIPreferenceStore().setValue(
176                     IWorkbenchPreferenceConstants.SHOW_INTRO, false);
177             PrefUtil.saveAPIPrefs();
178         }
179     }
180
181     /**
182      * Performs arbitrary actions after the window has been created (possibly
183      * after being restored), but has not yet been opened.
184      * <p>
185      * This method is called after the window has been created from scratch,
186      * or when it has been restored from a previously-saved window. In the latter case,
187      * this method is called after <code>postWindowRestore</code>.
188      * Clients must not call this method directly (although super calls are okay).
189      * The default implementation does nothing. Subclasses may override.
190      * </p>
191      */

192     public void postWindowCreate() {
193         // do nothing
194
}
195
196     /**
197      * Performs arbitrary actions after the window has been opened (possibly
198      * after being restored).
199      * <p>
200      * This method is called after the window has been opened. This method is
201      * called after the window has been created from scratch, or when
202      * it has been restored from a previously-saved window.
203      * Clients must not call this method directly (although super calls are okay).
204      * The default implementation does nothing. Subclasses may override.
205      * </p>
206      */

207     public void postWindowOpen() {
208         // do nothing
209
}
210
211     /**
212      * Performs arbitrary actions as the window's shell is being closed
213      * directly, and possibly veto the close.
214      * <p>
215      * This method is called from a ShellListener associated with the window,
216      * for example when the user clicks the window's close button. It is not
217      * called when the window is being closed for other reasons, such as if the
218      * user exits the workbench via the {@link ActionFactory#QUIT} action.
219      * Clients must not call this method directly (although super calls are
220      * okay). If this method returns <code>false</code>, then the user's
221      * request to close the shell is ignored. This gives the workbench advisor
222      * an opportunity to query the user and/or veto the closing of a window
223      * under some circumstances.
224      * </p>
225      *
226      * @return <code>true</code> to allow the window to close, and
227      * <code>false</code> to prevent the window from closing
228      * @see org.eclipse.ui.IWorkbenchWindow#close
229      * @see WorkbenchAdvisor#preShutdown()
230      */

231     public boolean preWindowShellClose() {
232         // do nothing, but allow the close() to proceed
233
return true;
234     }
235
236     /**
237      * Performs arbitrary actions after the window is closed.
238      * <p>
239      * This method is called after the window's controls have been disposed.
240      * Clients must not call this method directly (although super calls are
241      * okay). The default implementation does nothing. Subclasses may override.
242      * </p>
243      */

244     public void postWindowClose() {
245         // do nothing
246
}
247
248     /**
249      * Creates the contents of the window.
250      * <p>
251      * The default implementation adds a menu bar, a cool bar, a status line,
252      * a perspective bar, and a fast view bar. The visibility of these controls
253      * can be configured using the <code>setShow*</code> methods on
254      * <code>IWorkbenchWindowConfigurer</code>.
255      * </p>
256      * <p>
257      * Subclasses may override to define custom window contents and layout,
258      * but must call <code>IWorkbenchWindowConfigurer.createPageComposite</code>.
259      * </p>
260      *
261      * @param shell the window's shell
262      * @see IWorkbenchWindowConfigurer#createMenuBar
263      * @see IWorkbenchWindowConfigurer#createCoolBarControl
264      * @see IWorkbenchWindowConfigurer#createStatusLineControl
265      * @see IWorkbenchWindowConfigurer#createPageComposite
266      */

267     public void createWindowContents(Shell shell) {
268         ((WorkbenchWindowConfigurer) getWindowConfigurer()).createDefaultContents(shell);
269     }
270
271     /**
272      * Creates and returns the control to be shown when the window has no open pages.
273      * If <code>null</code> is returned, the default window background is shown.
274      * <p>
275      * The default implementation returns <code>null</code>.
276      * Subclasses may override.
277      * </p>
278      *
279      * @param parent the parent composite
280      * @return the control or <code>null</code>
281      */

282     public Control createEmptyWindowContents(Composite parent) {
283         return null;
284     }
285
286     /**
287      * Disposes any resources allocated by this window advisor.
288      * This is the last method called on this window advisor by the workbench.
289      * The default implementation does nothing.
290      * Subclasses may extend.
291      */

292     public void dispose() {
293         // do nothing.
294
}
295     
296     /**
297      * Saves arbitrary application specific state information.
298      *
299      * @param memento the storage area for object's state
300      * @return a status object indicating whether the save was successful
301      * @since 3.1
302      */

303     public IStatus saveState(IMemento memento) {
304         // do nothing
305
return Status.OK_STATUS;
306     }
307     
308     /**
309      * Restores arbitrary application specific state information.
310      *
311      * @param memento the storage area for object's state
312      * @return a status object indicating whether the restore was successful
313      * @since 3.1
314      */

315     public IStatus restoreState(IMemento memento) {
316         // do nothing
317
return Status.OK_STATUS;
318     }
319 }
320
Popular Tags