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   key = "introOpened"; //$NON-NLS-1$
156         Boolean   introOpened = (Boolean  ) 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags