WorkbenchAdvisor


1   /*******************************************************************************
2    * Copyright (c) 2003, 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  
12  package org.eclipse.ui.application;
13  
14  import org.eclipse.core.runtime.IAdaptable;
15  import org.eclipse.core.runtime.IStatus;
16  import org.eclipse.core.runtime.Status;
17  import org.eclipse.swt.widgets.Display;
18  import org.eclipse.swt.widgets.Shell;
19  import org.eclipse.ui.IMemento;
20  import org.eclipse.ui.IWorkbenchPreferenceConstants;
21  import org.eclipse.ui.IWorkbenchWindow;
22  import org.eclipse.ui.PlatformUI;
23  import org.eclipse.ui.WorkbenchException;
24  import org.eclipse.ui.internal.StartupThreading;
25  import org.eclipse.ui.internal.UISynchronizer;
26  import org.eclipse.ui.internal.WorkbenchPlugin;
27  import org.eclipse.ui.internal.WorkbenchWindowConfigurer;
28  import org.eclipse.ui.internal.StartupThreading.StartupRunnable;
29  import org.eclipse.ui.internal.application.CompatibilityWorkbenchWindowAdvisor;
30  import org.eclipse.ui.internal.util.PrefUtil;
31  import org.eclipse.ui.statushandlers.AbstractStatusHandler;
32  import org.eclipse.ui.statushandlers.StatusManager;
33  import org.eclipse.ui.statushandlers.WorkbenchErrorHandler;
34  
35  /**
36   * Public base class for configuring the workbench.
37   * <p>
38   * Note that the workbench advisor object is created in advance of creating the
39   * workbench. However, by the time the workbench starts calling methods on this
40   * class, <code>PlatformUI.getWorkbench</code> is guaranteed to have been
41   * properly initialized.
42   * </p>
43   * <p>
44   * Example of creating and running a workbench (in an
45   * <code>IPlatformRunnable</code>):
46   * 
47   * <pre>
48   * <code>
49   *           public class MyApplication implements IPlatformRunnable {
50   *             public Object run(Object args) {
51   *               WorkbenchAdvisor workbenchAdvisor = new MyWorkbenchAdvisor();
52   *               Display display = PlatformUI.createDisplay();
53   *               int returnCode = PlatformUI.createAndRunWorkbench(display, workbenchAdvisor);
54   *               if (returnCode == PlatformUI.RETURN_RESTART) {
55   *                  return IPlatformRunnable.EXIT_RESTART;
56   *               } else {
57   *                  return IPlatformRunnable.EXIT_OK;
58   *             }
59   *           }
60   * </code>
61   * </pre>
62   * 
63   * </p>
64   * <p>
65   * An application should declare a subclass of <code>WorkbenchAdvisor</code>
66   * and override methods to configure the workbench to suit the needs of the
67   * particular application.
68   * </p>
69   * <p>
70   * The following advisor methods are called at strategic points in the
71   * workbench's lifecycle (all occur within the dynamic scope of the call to
72   * {@link PlatformUI#createAndRunWorkbench PlatformUI.createAndRunWorkbench}):
73   * <ul>
74   * <li><code>initialize</code> - called first; before any windows; use to
75   * register things</li>
76   * <li><code>preStartup</code> - called second; after initialize but before
77   * first window is opened; use to temporarily disable things during startup or
78   * restore</li>
79   * <li><code>postStartup</code> - called third; after first window is opened;
80   * use to reenable things temporarily disabled in previous step</li>
81   * <li><code>postRestore</code> - called after the workbench and its windows
82   * has been recreated from a previously saved state; use to adjust the restored
83   * workbench</li>
84   * <li><code>preWindowOpen</code> - called as each window is being opened;
85   * use to configure aspects of the window other than actions bars </li>
86   * <li><code>fillActionBars</code> - called after <code>preWindowOpen</code>
87   * to configure a window's action bars</li>
88   * <li><code>postWindowRestore</code> - called after a window has been
89   * recreated from a previously saved state; use to adjust the restored window</li>
90   * <li><code>postWindowCreate</code> - called after a window has been
91   * created, either from an initial state or from a restored state; used to
92   * adjust the window</li>
93   * <li><code>openIntro</code> - called immediately before a window is opened
94   * in order to create the introduction component, if any.</li>
95   * <li><code>postWindowOpen</code> - called after a window has been opened;
96   * use to hook window listeners, etc.</li>
97   * <li><code>preWindowShellClose</code> - called when a window's shell is
98   * closed by the user; use to pre-screen window closings</li>
99   * <li><code>eventLoopException</code> - called to handle the case where the
100  * event loop has crashed; use to inform the user that things are not well</li>
101  * <li><code>eventLoopIdle</code> - called when there are currently no more
102  * events to be processed; use to perform other work or to yield until new
103  * events enter the queue</li>
104  * <li><code>preShutdown</code> - called immediately prior to workbench
105  * shutdown before any windows have been closed; allows the advisor to veto the
106  * shutdown</li>
107  * <li><code>postShutdown</code> - called last; after event loop has
108  * terminated and all windows have been closed; use to deregister things
109  * registered during initialize</li>
110  * </ul>
111  * </p>
112  * 
113  * @since 3.0
114  */
115 public abstract class WorkbenchAdvisor {
116 
117     /**
118      * Bit flag for {@link #fillActionBars fillActionBars} indicating that the
119      * operation is not filling the action bars of an actual workbench window,
120      * but rather a proxy (used for perspective customization).
121      * 
122      * @deprecated use {@link ActionBarAdvisor#FILL_PROXY instead}
123      */
124     public static final int FILL_PROXY = ActionBarAdvisor.FILL_PROXY;
125 
126     /**
127      * Bit flag for {@link #fillActionBars fillActionBars} indicating that the
128      * operation is supposed to fill (or describe) the workbench window's menu
129      * bar.
130      * 
131      * @deprecated use {@link ActionBarAdvisor#FILL_MENU_BAR instead}
132      */
133     public static final int FILL_MENU_BAR = ActionBarAdvisor.FILL_MENU_BAR;
134 
135     /**
136      * Bit flag for {@link #fillActionBars fillActionBars} indicating that the
137      * operation is supposed to fill (or describe) the workbench window's cool
138      * bar.
139      * 
140      * @deprecated use {@link ActionBarAdvisor#FILL_COOL_BAR instead}
141      */
142     public static final int FILL_COOL_BAR = ActionBarAdvisor.FILL_COOL_BAR;
143 
144     /**
145      * Bit flag for {@link #fillActionBars fillActionBars} indicating that the
146      * operation is supposed to fill (or describe) the workbench window's status
147      * line.
148      * 
149      * @deprecated use {@link ActionBarAdvisor#FILL_STATUS_LINE instead}
150      */
151     public static final int FILL_STATUS_LINE = ActionBarAdvisor.FILL_STATUS_LINE;
152 
153     /**
154      * The workbench configurer.
155      */
156     private IWorkbenchConfigurer workbenchConfigurer;
157 
158     /**
159      * The workbench error handler.
160      */
161     private AbstractStatusHandler workbenchErrorHandler;
162 
163     private boolean introOpened;
164 
165     /**
166      * Creates and initializes a new workbench advisor instance.
167      */
168     protected WorkbenchAdvisor() {
169         // do nothing
170     }
171 
172     /**
173      * Remembers the configurer and calls <code>initialize</code>.
174      * <p>
175      * For internal use by the workbench only.
176      * </p>
177      * 
178      * @param configurer
179      *            an object for configuring the workbench
180      */
181     public final void internalBasicInitialize(IWorkbenchConfigurer configurer) {
182         if (workbenchConfigurer != null) {
183             throw new IllegalStateException  ();
184         }
185         this.workbenchConfigurer = configurer;
186         initialize(configurer);
187     }
188 
189     /**
190      * Performs arbitrary initialization before the workbench starts running.
191      * <p>
192      * This method is called during workbench initialization prior to any
193      * windows being opened. Clients must not call this method directly
194      * (although super calls are okay). The default implementation does nothing.
195      * Subclasses may override. Typical clients will use the configurer passed
196      * in to tweak the workbench. If further tweaking is required in the future,
197      * the configurer may be obtained using <code>getWorkbenchConfigurer</code>.
198      * </p>
199      * 
200      * @param configurer
201      *            an object for configuring the workbench
202      */
203     public void initialize(IWorkbenchConfigurer configurer) {
204         // do nothing
205     }
206 
207     /**
208      * Returns the workbench configurer for the advisor. Can be
209      * <code>null</code> if the advisor is not initialized yet.
210      * 
211      * @return the workbench configurer, or <code>null</code> if the advisor
212      *         is not initialized yet
213      */
214     protected IWorkbenchConfigurer getWorkbenchConfigurer() {
215         return workbenchConfigurer;
216     }
217 
218     /**
219      * Returns the workbench error handler for the advisor.
220      * 
221      * @return the workbench error handler
222      * @since 3.3
223      */
224     public AbstractStatusHandler getWorkbenchErrorHandler() {
225         if (workbenchErrorHandler == null) {
226             workbenchErrorHandler = new WorkbenchErrorHandler();
227         }
228         return workbenchErrorHandler;
229     }
230 
231     /**
232      * Performs arbitrary actions just before the first workbench window is
233      * opened (or restored).
234      * <p>
235      * This method is called after the workbench has been initialized and just
236      * before the first window is about to be opened. Clients must not call this
237      * method directly (although super calls are okay). The default
238      * implementation does nothing. Subclasses may override.
239      * </p>
240      */
241     public void preStartup() {
242         // do nothing
243     }
244 
245     /**
246      * Performs arbitrary actions after the workbench windows have been opened
247      * (or restored), but before the main event loop is run.
248      * <p>
249      * This method is called just after the windows have been opened. Clients
250      * must not call this method directly (although super calls are okay). The
251      * default implementation does nothing. Subclasses may override. It is okay
252      * to call <code>IWorkbench.close()</code> from this method.
253      * </p>
254      */
255     public void postStartup() {
256         // do nothing
257     }
258 
259     /**
260      * Performs arbitrary finalization before the workbench is about to shut
261      * down.
262      * <p>
263      * This method is called immediately prior to workbench shutdown before any
264      * windows have been closed. Clients must not call this method directly
265      * (although super calls are okay). The default implementation returns
266      * <code>true</code>. Subclasses may override.
267      * </p>
268      * <p>
269      * The advisor may veto a regular shutdown by returning <code>false</code>,
270      * although this will be ignored if the workbench is being forced to shut
271      * down.
272      * </p>
273      * 
274      * @return <code>true</code> to allow the workbench to proceed with
275      *         shutdown, <code>false</code> to veto a non-forced shutdown
276      */
277     public boolean preShutdown() {
278         return true;
279     }
280 
281     /**
282      * Performs arbitrary finalization after the workbench stops running.
283      * <p>
284      * This method is called during workbench shutdown after all windows have
285      * been closed. Clients must not call this method directly (although super
286      * calls are okay). The default implementation does nothing. Subclasses may
287      * override.
288      * </p>
289      */
290     public void postShutdown() {
291         // do nothing
292     }
293 
294     /**
295      * Performs arbitrary actions when the event loop crashes (the code that
296      * handles a UI event throws an exception that is not caught).
297      * <p>
298      * This method is called when the code handling a UI event throws an
299      * exception. In a perfectly functioning application, this method would
300      * never be called. In practice, it comes into play when there are bugs in
301      * the code that trigger unchecked runtime exceptions. It is also activated
302      * when the system runs short of memory, etc. Fatal errors (ThreadDeath) are
303      * not passed on to this method, as there is nothing that could be done.
304      * </p>
305      * <p>
306      * Clients must not call this method directly (although super calls are
307      * okay). The default implementation logs the problem so that it does not go
308      * unnoticed. Subclasses may override or extend this method. It is generally
309      * a bad idea to override with an empty method, and you should be especially
310      * careful when handling Errors.
311      * </p>
312      * 
313      * @param exception
314      *            the uncaught exception that was thrown inside the UI event
315      *            loop
316      */
317     public void eventLoopException(Throwable   exception) {
318         // Protection from client doing super(null) call
319         if (exception == null) {
320             return;
321         }
322 
323         try {
324             StatusManager.getManager().handle(
325                     new Status(IStatus.ERROR, WorkbenchPlugin.PI_WORKBENCH,
326                             "Unhandled event loop exception", exception)); //$NON-NLS-1$
327 
328             if (WorkbenchPlugin.DEBUG) {
329                 exception.printStackTrace();
330             }
331         } catch (Throwable   e) {
332             // One of the log listeners probably failed. Core should have logged
333             // the
334             // exception since its the first listener.
335             System.err.println("Error while logging event loop exception:"); //$NON-NLS-1$
336             exception.printStackTrace();
337             System.err.println("Logging exception:"); //$NON-NLS-1$
338             e.printStackTrace();
339         }
340     }
341 
342     /**
343      * Performs arbitrary work or yields when there are no events to be
344      * processed.
345      * <p>
346      * This method is called when there are currently no more events on the
347      * queue to be processed at the moment.
348      * </p>
349      * <p>
350      * Clients must not call this method directly (although super calls are
351      * okay). The default implementation yields until new events enter the
352      * queue. Subclasses may override or extend this method. It is generally a
353      * bad idea to override with an empty method. It is okay to call
354      * <code>IWorkbench.close()</code> from this method.
355      * </p>
356      * 
357      * @param display
358      *            the main display of the workbench UI
359      */
360     public void eventLoopIdle(Display display) {
361         // default: yield cpu until new events enter the queue
362         display.sleep();
363     }
364 
365     /**
366      * Creates a new workbench window advisor for configuring a new workbench
367      * window via the given workbench window configurer. Clients should override
368      * to provide their own window configurer. This method replaces all the
369      * other window and action bar lifecycle methods on the workbench advisor.
370      * <p>
371      * The default implementation creates a window advisor that calls back to
372      * the legacy window and action bar lifecycle methods on the workbench
373      * advisor, for backwards compatibility with 3.0.
374      * </p>
375      * 
376      * @param configurer
377      *            the workbench window configurer
378      * @return a new workbench window advisor
379      * @since 3.1
380      */
381     public WorkbenchWindowAdvisor createWorkbenchWindowAdvisor(
382             IWorkbenchWindowConfigurer configurer) {
383         return new CompatibilityWorkbenchWindowAdvisor(this, configurer);
384     }
385 
386     /**
387      * Performs arbitrary actions before the given workbench window is opened.
388      * <p>
389      * This method is called before the window's controls have been created.
390      * Clients must not call this method directly (although super calls are
391      * okay). The default implementation does nothing. Subclasses may override.
392      * Typical clients will use the configurer passed in to tweak the workbench
393      * window in an application-specific way; however, filling the window's menu
394      * bar, tool bar, and status line must be done in
395      * {@link #fillActionBars fillActionBars}, which is called immediately
396      * after this method is called.
397      * </p>
398      * 
399      * @param configurer
400      *            an object for configuring the particular workbench window
401      *            being opened
402      * 
403      * @deprecated since 3.1, override
404      *             {@link WorkbenchWindowAdvisor#preWindowOpen()} instead
405      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
406      */
407     public void preWindowOpen(IWorkbenchWindowConfigurer configurer) {
408         // do nothing
409     }
410 
411     /**
412      * Configures the action bars using the given action bar configurer. Under
413      * normal circumstances, <code>flags</code> does not include
414      * <code>FILL_PROXY</code>, meaning this is a request to fill the
415      * actions\ bars of the given workbench window; the remaining flags indicate
416      * which combination of the menu bar (<code>FILL_MENU_BAR</code>), the
417      * tool bar (<code>FILL_COOL_BAR</code>), and the status line (<code>FILL_STATUS_LINE</code>)
418      * are to be filled.
419      * <p>
420      * If <code>flags</code> does include <code>FILL_PROXY</code>, then
421      * this is a request to describe the actions bars of the given workbench
422      * window (which will already have been filled); again, the remaining flags
423      * indicate which combination of the menu bar, the tool bar, and the status
424      * line are to be described. The actions included in the proxy action bars
425      * can be the same instances as in the actual window's action bars. Calling
426      * <code>ActionFactory</code> to create new action instances is not
427      * recommended, because these actions internally register listeners with the
428      * window and there is no opportunity to dispose of these actions.
429      * </p>
430      * <p>
431      * This method is called just after {@link #preWindowOpen preWindowOpen}.
432      * Clients must not call this method directly (although super calls are
433      * okay). The default implementation does nothing. Subclasses may override.
434      * </p>
435      * 
436      * @param window
437      *            the workbench window
438      * @param configurer
439      *            the action bar configurer object
440      * @param flags
441      *            bit mask composed from the constants
442      *            {@link #FILL_MENU_BAR FILL_MENU_BAR},
443      *            {@link #FILL_COOL_BAR FILL_COOL_BAR},
444      *            {@link #FILL_STATUS_LINE FILL_STATUS_LINE}, and
445      *            {@link #FILL_PROXY FILL_PROXY} Note: should 1st param be
446      *            IWorkbenchWindowConfigurer to be more consistent with other
447      *            methods? Note: suggest adding ActionBuilder as API, to
448      *            encapsulate the action building outside of the advisor, and to
449      *            handle the common pattern of hanging onto the action builder
450      *            in order to properly handle FILL_PROXY
451      * 
452      * @deprecated since 3.1, override
453      *             {@link ActionBarAdvisor#fillActionBars(int)} instead
454      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
455      * @see WorkbenchWindowAdvisor#createActionBarAdvisor(IActionBarConfigurer)
456      */
457     public void fillActionBars(IWorkbenchWindow window,
458             IActionBarConfigurer configurer, int flags) {
459         // do nothing by default
460     }
461 
462     /**
463      * Performs arbitrary actions after the given workbench window has been
464      * restored, but before it is opened.
465      * <p>
466      * This method is called after a previously-saved window have been
467      * recreated. This method is not called when a new window is created from
468      * scratch. This method is never called when a workbench is started for the
469      * very first time, or when workbench state is not saved or restored.
470      * Clients must not call this method directly (although super calls are
471      * okay). The default implementation does nothing. Subclasses may override.
472      * It is okay to call <code>IWorkbench.close()</code> from this method.
473      * </p>
474      * 
475      * @param configurer
476      *            an object for configuring the particular workbench window just
477      *            restored
478      * 
479      * @deprecated since 3.1, override
480      *             {@link WorkbenchWindowAdvisor#postWindowRestore()} instead
481      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
482      */
483     public void postWindowRestore(IWorkbenchWindowConfigurer configurer)
484             throws WorkbenchException {
485         // do nothing
486     }
487 
488     /**
489      * Opens the introduction componenet.
490      * <p>
491      * Clients must not call this method directly (although super calls are
492      * okay). The default implementation opens the intro in the first window
493      * provided the preference IWorkbenchPreferences.SHOW_INTRO is
494      * <code>true</code>. If an intro is shown then this preference will be
495      * set to <code>false</code>. Subsequently, and intro will be shown only
496      * if <code>WorkbenchConfigurer.getSaveAndRestore()</code> returns
497      * <code>true</code> and the introduction was visible on last shutdown.
498      * Subclasses may override.
499      * </p>
500      * 
501      * @param configurer
502      *            configurer an object for configuring the particular workbench
503      *            window just created
504      * 
505      * @deprecated since 3.1, override
506      *             {@link WorkbenchWindowAdvisor#openIntro()} instead
507      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
508      */
509     public void openIntro(IWorkbenchWindowConfigurer configurer) {
510         if (introOpened) {
511             return;
512         }
513 
514         introOpened = true;
515 
516         boolean showIntro = PrefUtil.getAPIPreferenceStore().getBoolean(
517                 IWorkbenchPreferenceConstants.SHOW_INTRO);
518 
519         if (!showIntro) {
520             return;
521         }
522 
523         if (getWorkbenchConfigurer().getWorkbench().getIntroManager()
524                 .hasIntro()) {
525             getWorkbenchConfigurer().getWorkbench().getIntroManager()
526                     .showIntro(configurer.getWindow(), false);
527 
528             PrefUtil.getAPIPreferenceStore().setValue(
529                     IWorkbenchPreferenceConstants.SHOW_INTRO, false);
530             PrefUtil.saveAPIPrefs();
531         }
532     }
533 
534     /**
535      * Performs arbitrary actions after the given workbench window has been
536      * created (possibly after being restored), but has not yet been opened.
537      * <p>
538      * This method is called after a new window has been created from scratch,
539      * or when a previously-saved window has been restored. In the latter case,
540      * this method is called after <code>postWindowRestore</code>. Clients
541      * must not call this method directly (although super calls are okay). The
542      * default implementation does nothing. Subclasses may override.
543      * </p>
544      * 
545      * @param configurer
546      *            an object for configuring the particular workbench window just
547      *            created
548      * 
549      * @deprecated since 3.1, override
550      *             {@link WorkbenchWindowAdvisor#postWindowCreate()} instead
551      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
552      */
553     public void postWindowCreate(IWorkbenchWindowConfigurer configurer) {
554         // do nothing
555     }
556 
557     /**
558      * Performs arbitrary actions after the given workbench window has been
559      * opened (possibly after being restored).
560      * <p>
561      * This method is called after a window has been opened. This method is
562      * called after a new window has been created from scratch, or when a
563      * previously-saved window has been restored. Clients must not call this
564      * method directly (although super calls are okay). The default
565      * implementation does nothing. Subclasses may override.
566      * </p>
567      * 
568      * @param configurer
569      *            an object for configuring the particular workbench window just
570      *            opened
571      * 
572      * @deprecated since 3.1, override
573      *             {@link WorkbenchWindowAdvisor#postWindowOpen()} instead
574      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
575      */
576     public void postWindowOpen(IWorkbenchWindowConfigurer configurer) {
577         // do nothing
578     }
579 
580     /**
581      * Performs arbitrary actions as the given workbench window's shell is being
582      * closed directly, and possibly veto the close.
583      * <p>
584      * This method is called from a ShellListener associated with the workbench
585      * window. It is not called when the window is being closed for other
586      * reasons. Clients must not call this method directly (although super calls
587      * are okay). The default implementation does nothing. Subclasses may
588      * override. Typical clients may use the configurer passed in to access the
589      * workbench window being closed. If this method returns <code>false</code>,
590      * then the user's request to close the shell is ignored. This gives the
591      * workbench advisor an opportunity to query the user and/or veto the
592      * closing of a window under some circumstances.
593      * </p>
594      * 
595      * @param configurer
596      *            an object for configuring the particular workbench window
597      *            whose shell is being closed
598      * @return <code>true</code> to allow the window to close, and
599      *         <code>false</code> to prevent the window from closing
600      * @see org.eclipse.ui.IWorkbenchWindow#close
601      * 
602      * @deprecated since 3.1, override
603      *             {@link WorkbenchWindowAdvisor#preWindowShellClose()} instead
604      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
605      */
606     public boolean preWindowShellClose(IWorkbenchWindowConfigurer configurer) {
607         // do nothing, but allow the close() to proceed
608         return true;
609     }
610 
611     /**
612      * Performs arbitrary actions after the given workbench window is closed.
613      * <p>
614      * This method is called after the window's controls have been disposed.
615      * Clients must not call this method directly (although super calls are
616      * okay). The default implementation does nothing. Subclasses may override.
617      * Typical clients will use the configurer passed in to tweak the workbench
618      * window in an application-specific way.
619      * </p>
620      * 
621      * @param configurer
622      *            an object for configuring the particular workbench window
623      *            being closed
624      * 
625      * @deprecated since 3.1, override
626      *             {@link WorkbenchWindowAdvisor#postWindowClose()} instead
627      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
628      */
629     public void postWindowClose(IWorkbenchWindowConfigurer configurer) {
630         // do nothing
631     }
632 
633     /**
634      * Returns whether the menu with the given id is an application menu of the
635      * given window. This is used during OLE "in place" editing. Application
636      * menus should be preserved during menu merging. All other menus may be
637      * removed from the window.
638      * <p>
639      * The default implementation returns false. Subclasses may override.
640      * </p>
641      * 
642      * @param configurer
643      *            an object for configuring the workbench window
644      * @param menuId
645      *            the menu id
646      * @return <code>true</code> for application menus, and <code>false</code>
647      *         for part-specific menus
648      * 
649      * @deprecated since 3.1, override
650      *             {@link ActionBarAdvisor#isApplicationMenu(String)} instead
651      * @see WorkbenchWindowAdvisor#createActionBarAdvisor(IActionBarConfigurer)
652      */
653     public boolean isApplicationMenu(IWorkbenchWindowConfigurer configurer,
654             String   menuId) {
655         // default: not an application menu
656         return false;
657     }
658 
659     /**
660      * Returns the default input for newly created workbench pages when the
661      * input is not explicitly specified.
662      * <p>
663      * The default implementation returns <code>null</code>. Subclasses may
664      * override.
665      * </p>
666      * 
667      * @return the default input for a new workbench window page, or
668      *         <code>null</code> if none
669      * 
670      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
671      */
672     public IAdaptable getDefaultPageInput() {
673         // default: no input
674         return null;
675     }
676 
677     /**
678      * Returns the id of the perspective to use for the initial workbench
679      * window, or <code>null</code> if no initial perspective should be shown
680      * in the initial workbench window.
681      * <p>
682      * This method is called during startup when the workbench is creating the
683      * first new window. Subclasses must implement.
684      * </p>
685      * <p>
686      * If the {@link IWorkbenchPreferenceConstants#DEFAULT_PERSPECTIVE_ID}
687      * preference is specified, it supercedes the perspective specified here.
688      * </p>
689      * 
690      * @return the id of the perspective for the initial window, or
691      *         <code>null</code> if no initial perspective should be shown
692      */
693     public abstract String   getInitialWindowPerspectiveId();
694 
695     /**
696      * Returns the id of the preference page that should be presented most
697      * prominently.
698      * <p>
699      * The default implementation returns <code>null</code>. Subclasses may
700      * override.
701      * </p>
702      * 
703      * @return the id of the preference page, or <code>null</code> if none
704      */
705     public String   getMainPreferencePageId() {
706         // default: no opinion
707         return null;
708     }
709 
710     /**
711      * Creates the contents of the window.
712      * <p>
713      * The default implementation adds a menu bar, a cool bar, a status line, a
714      * perspective bar, and a fast view bar. The visibility of these controls
715      * can be configured using the <code>setShow*</code> methods on
716      * <code>IWorkbenchWindowConfigurer</code>.
717      * </p>
718      * <p>
719      * Subclasses may override to define custom window contents and layout, but
720      * must call <code>IWorkbenchWindowConfigurer.createPageComposite</code>.
721      * </p>
722      * 
723      * @param configurer
724      *            the window configurer
725      * @param shell
726      *            the window's shell
727      * @see IWorkbenchWindowConfigurer#createMenuBar
728      * @see IWorkbenchWindowConfigurer#createCoolBarControl
729      * @see IWorkbenchWindowConfigurer#createStatusLineControl
730      * @see IWorkbenchWindowConfigurer#createPageComposite
731      * 
732      * @deprecated since 3.1, override
733      *             {@link WorkbenchWindowAdvisor#createWindowContents(Shell)}
734      *             instead
735      * @see #createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
736      */
737     public void createWindowContents(IWorkbenchWindowConfigurer configurer,
738             Shell shell) {
739         ((WorkbenchWindowConfigurer) configurer).createDefaultContents(shell);
740     }
741 
742     /**
743      * Opens the workbench windows on startup. The default implementation tries
744      * to restore the previously saved workbench state using
745      * <code>IWorkbenchConfigurer.restoreWorkbenchState()</code>. If there
746      * was no previously saved state, or if the restore failed, then a
747      * first-time window is opened using
748      * <code>IWorkbenchConfigurer.openFirstTimeWindow</code>.
749      * 
750      * @return <code>true</code> to proceed with workbench startup, or
751      *         <code>false</code> to exit
752      */
753     public boolean openWindows() {
754         final Display display = PlatformUI.getWorkbench().getDisplay();
755         final boolean result [] = new boolean[1];
756         
757         // spawn another init thread.  For API compatibility We guarantee this method is called from 
758         // the UI thread but it could take enough time to disrupt progress reporting.
759         // spawn a new thread to do the grunt work of this initialization and spin the event loop 
760         // ourselves just like it's done in Workbench.
761         final boolean[] initDone = new boolean[]{false};
762         final Throwable   [] error = new Throwable  [1];
763         Thread   initThread = new Thread  () {
764             /* (non-Javadoc)
765              * @see java.lang.Thread#run()
766              */
767             public void run() {
768                 try {
769                     //declare us to be a startup thread so that our syncs will be executed 
770                     UISynchronizer.startupThread.set(Boolean.TRUE);
771                     final IWorkbenchConfigurer [] myConfigurer = new IWorkbenchConfigurer[1];
772                     StartupThreading.runWithoutExceptions(new StartupRunnable() {
773     
774                         public void runWithException() throws Throwable   {
775                             myConfigurer[0] = getWorkbenchConfigurer();
776                             
777                         }});
778                     
779                     IStatus status = myConfigurer[0].restoreState();
780                     if (!status.isOK()) {
781                         if (status.getCode() == IWorkbenchConfigurer.RESTORE_CODE_EXIT) {
782                             result[0] = false;
783                             return;
784                         }
785                         if (status.getCode() == IWorkbenchConfigurer.RESTORE_CODE_RESET) {
786                             myConfigurer[0].openFirstTimeWindow();
787                         }
788                     }
789                     result[0] = true;
790                 } catch (Throwable   e) {
791                     error[0] = e;
792                 }
793                 finally {
794                     initDone[0] = true;
795                     display.wake();
796                 }
797             }};
798             initThread.start();
799 
800             while (true) {
801                 if (!display.readAndDispatch()) {
802                     if (initDone[0])
803                         break;
804                     display.sleep();
805                 }
806                 
807             }
808             
809             // can only be a runtime or error
810             if (error[0] instanceof Error  )
811                 throw (Error  )error[0];
812             else if (error[0] instanceof RuntimeException  )
813                 throw (RuntimeException  )error[0];
814         
815             return result[0];
816     }
817 
818     /**
819      * Saves arbitrary application-specific state information for this workbench
820      * advisor.
821      * <p>
822      * The default implementation simply returns an OK status. Subclasses may
823      * extend or override.
824      * </p>
825      * 
826      * @param memento
827      *            the memento in which to save the advisor's state
828      * @return a status object indicating whether the save was successful
829      * @since 3.1
830      */
831     public IStatus saveState(IMemento memento) {
832         return Status.OK_STATUS;
833     }
834 
835     /**
836      * Restores arbitrary application-specific state information for this
837      * workbench advisor.
838      * <p>
839      * The default implementation simply returns an OK status. Subclasses may
840      * extend or override.
841      * </p>
842      * 
843      * @param memento
844      *            the memento from which to restore the advisor's state
845      * @return a status object indicating whether the restore was successful
846      * @since 3.1
847      */
848     public IStatus restoreState(IMemento memento) {
849         return Status.OK_STATUS;
850     }
851 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags