org.eclipse.ui.application
Class WorkbenchAdvisor

java.lang.Object
  extended by org.eclipse.ui.application.WorkbenchAdvisor
Direct Known Subclasses:
eWorkbenchAdvisor

public abstract class WorkbenchAdvisor
extends java.lang.Object

Public base class for configuring the workbench.

Note that the workbench advisor object is created in advance of creating the workbench. However, by the time the workbench starts calling methods on this class, PlatformUI.getWorkbench is guaranteed to have been properly initialized.

Example of creating and running a workbench (in an IPlatformRunnable):

 
 public class MyApplication implements IPlatformRunnable {
   public Object run(Object args) {
     WorkbenchAdvisor workbenchAdvisor = new MyWorkbenchAdvisor();
     Display display = PlatformUI.createDisplay();
     int returnCode = PlatformUI.createAndRunWorkbench(display, workbenchAdvisor);
     if (returnCode == PlatformUI.RETURN_RESTART) {
        return IPlatformRunnable.EXIT_RESTART;
     } else {
        return IPlatformRunnable.EXIT_OK;
   }
 }
 
 

An application should declare a subclass of WorkbenchAdvisor and override methods to configure the workbench to suit the needs of the particular application.

The following advisor methods are called at strategic points in the workbench's lifecycle (all occur within the dynamic scope of the call to PlatformUI.createAndRunWorkbench):

Since:
3.0

Constructor Summary
protected WorkbenchAdvisor()
          Creates and initializes a new workbench advisor instance.
 
Method Summary
 Control createEmptyWindowContents(IWorkbenchWindowConfigurer configurer, Composite parent)
          Deprecated. since 3.1, override WorkbenchWindowAdvisor.createEmptyWindowContents(Composite) instead
 void createWindowContents(IWorkbenchWindowConfigurer configurer, Shell shell)
          Deprecated. since 3.1, override WorkbenchWindowAdvisor.createWindowContents(Shell) instead
 WorkbenchWindowAdvisor createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer)
          EXPERIMENTAL -- May change before 3.1 ships.
 void eventLoopException(java.lang.Throwable exception)
          Performs arbitrary actions when the event loop crashes (the code that handles a UI event throws an exception that is not caught).
 void eventLoopIdle(Display display)
          Performs arbitrary work or yields when there are no events to be processed.
 IAdaptable getDefaultPageInput()
          Returns the default input for newly created workbench pages when the input is not explicitly specified.
abstract  java.lang.String getInitialWindowPerspectiveId()
          Returns the id of the perspective to use for the initial workbench org.eclipse.jface.window, or null if no initial perspective should be shown in the initial workbench org.eclipse.jface.window.
 java.lang.String getMainPreferencePageId()
          Returns the id of the org.eclipse.jface.preference page that should be presented most prominently.
protected  IWorkbenchConfigurer getWorkbenchConfigurer()
          Returns the workbench configurer for the advisor.
 void initialize(IWorkbenchConfigurer configurer)
          Performs arbitrary initialization before the workbench starts running.
 void internalBasicInitialize(IWorkbenchConfigurer configurer)
          Remembers the configurer and calls initialize.
 boolean isApplicationMenu(IWorkbenchWindowConfigurer configurer, java.lang.String menuId)
          Deprecated. since 3.1, override ActionBarAdvisor#isApplicationMenu(String) instead
 void openIntro(IWorkbenchWindowConfigurer configurer)
          Deprecated. since 3.1, override WorkbenchWindowAdvisor.openIntro() instead
 boolean openWindows()
          Opens the workbench windows on startup.
 void postShutdown()
          Performs arbitrary finalization after the workbench stops running.
 void postStartup()
          Performs arbitrary actions after the workbench windows have been opened (or restored), but before the main event loop is run.
 void postWindowClose(IWorkbenchWindowConfigurer configurer)
          Deprecated. since 3.1, override WorkbenchWindowAdvisor.postWindowClose() instead
 void postWindowCreate(IWorkbenchWindowConfigurer configurer)
          Deprecated. since 3.1, override WorkbenchWindowAdvisor.postWindowCreate() instead
 void postWindowOpen(IWorkbenchWindowConfigurer configurer)
          Deprecated. since 3.1, override WorkbenchWindowAdvisor.postWindowOpen() instead
 void postWindowRestore(IWorkbenchWindowConfigurer configurer)
          Deprecated. since 3.1, override WorkbenchWindowAdvisor.postWindowRestore() instead
 boolean preShutdown()
          Performs arbitrary finalization before the workbench is about to shut down.
 void preStartup()
          Performs arbitrary actions just before the first workbench org.eclipse.jface.window is opened (or restored).
 void preWindowOpen(IWorkbenchWindowConfigurer configurer)
          Deprecated. since 3.1, override WorkbenchWindowAdvisor.preWindowOpen() instead
 boolean preWindowShellClose(IWorkbenchWindowConfigurer configurer)
          Deprecated. since 3.1, override WorkbenchWindowAdvisor.preWindowShellClose() instead
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WorkbenchAdvisor

protected WorkbenchAdvisor()
Creates and initializes a new workbench advisor instance.

Method Detail

internalBasicInitialize

public final void internalBasicInitialize(IWorkbenchConfigurer configurer)
Remembers the configurer and calls initialize.

For internal use by the workbench only.

Parameters:
configurer - an object for configuring the workbench

initialize

public void initialize(IWorkbenchConfigurer configurer)
Performs arbitrary initialization before the workbench starts running.

This method is called during workbench initialization prior to any windows being opened. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. Typical clients will use the configurer passed in to tweak the workbench. If further tweaking is required in the future, the configurer may be obtained using getWorkbenchConfigurer.

Parameters:
configurer - an object for configuring the workbench

getWorkbenchConfigurer

protected IWorkbenchConfigurer getWorkbenchConfigurer()
Returns the workbench configurer for the advisor. Can be null if the advisor is not initialized yet.

Returns:
the workbench configurer, or null if the advisor is not initialized yet

preStartup

public void preStartup()
Performs arbitrary actions just before the first workbench org.eclipse.jface.window is opened (or restored).

This method is called after the workbench has been initialized and just before the first org.eclipse.jface.window is about to be opened. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.


postStartup

public void postStartup()
Performs arbitrary actions after the workbench windows have been opened (or restored), but before the main event loop is run.

This method is called just after the windows have been opened. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. It is okay to call IWorkbench.close() from this method.


preShutdown

public boolean preShutdown()
Performs arbitrary finalization before the workbench is about to shut down.

This method is called immediately prior to workbench shutdown before any windows have been closed. Clients must not call this method directly (although super calls are okay). The default implementation returns true. Subclasses may override.

The advisor may veto a regular shutdown by returning false, although this will be ignored if the workbench is being forced to shut down.

Returns:
true to allow the workbench to proceed with shutdown, false to veto a non-forced shutdown

postShutdown

public void postShutdown()
Performs arbitrary finalization after the workbench stops running.

This method is called during workbench shutdown after all windows have been closed. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.


eventLoopException

public void eventLoopException(java.lang.Throwable exception)
Performs arbitrary actions when the event loop crashes (the code that handles a UI event throws an exception that is not caught).

This method is called when the code handling a UI event throws an exception. In a perfectly functioning application, this method would never be called. In practice, it comes into play when there are bugs in the code that trigger unchecked runtime exceptions. It is also activated when the system runs short of memory, etc. Fatal errors (ThreadDeath) are not passed on to this method, as there is nothing that could be done.

Clients must not call this method directly (although super calls are okay). The default implementation logs the problem so that it does not go unnoticed. Subclasses may override or extend this method. It is generally a bad idea to override with an empty method, and you should be especially careful when handling Errors.

Parameters:
exception - the uncaught exception that was thrown inside the UI event loop

eventLoopIdle

public void eventLoopIdle(Display display)
Performs arbitrary work or yields when there are no events to be processed.

This method is called when there are currently no more events on the queue to be processed at the moment.

Clients must not call this method directly (although super calls are okay). The default implementation yields until new events enter the queue. Subclasses may override or extend this method. It is generally a bad idea to override with an empty method. It is okay to call IWorkbench.close() from this method.

Parameters:
display - the main display of the workbench UI

createWorkbenchWindowAdvisor

public WorkbenchWindowAdvisor createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer)
EXPERIMENTAL -- May change before 3.1 ships. Creates a new workbench org.eclipse.jface.window advisor for configuring a new workbench org.eclipse.jface.window via the given workbench org.eclipse.jface.window configurer. Clients should override to provide their own org.eclipse.jface.window configurer. This method replaces all the other org.eclipse.jface.window and action bar lifecycle methods on the workbench advisor.

The default implementation creates a org.eclipse.jface.window advisor that calls back to the legacy org.eclipse.jface.window and action bar lifecycle methods on the workbench advisor, for backwards compatibility with 3.0.

TODO: replace this with an extension point and a getDefaultWorkbenchWindowAdvisorId() method

Parameters:
configurer - the workbench org.eclipse.jface.window configurer
Returns:
a new workbench org.eclipse.jface.window advisor
Since:
3.1

preWindowOpen

public void preWindowOpen(IWorkbenchWindowConfigurer configurer)
Deprecated. since 3.1, override WorkbenchWindowAdvisor.preWindowOpen() instead

Performs arbitrary actions before the given workbench org.eclipse.jface.window is opened.

This method is called before the org.eclipse.jface.window's controls have been created. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. Typical clients will use the configurer passed in to tweak the workbench org.eclipse.jface.window in an application-specific way; however, filling the org.eclipse.jface.window's menu bar, tool bar, and status line must be done in fillActionBars, which is called immediately after this method is called.

Parameters:
configurer - an object for configuring the particular workbench org.eclipse.jface.window being opened
See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)

postWindowRestore

public void postWindowRestore(IWorkbenchWindowConfigurer configurer)
                       throws WorkbenchException
Deprecated. since 3.1, override WorkbenchWindowAdvisor.postWindowRestore() instead

Performs arbitrary actions after the given workbench org.eclipse.jface.window has been restored, but before it is opened.

This method is called after a previously-saved org.eclipse.jface.window have been recreated. This method is not called when a new org.eclipse.jface.window is created from scratch. This method is never called when a workbench is started for the very first time, or when workbench state is not saved or restored. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. It is okay to call IWorkbench.close() from this method.

Parameters:
configurer - an object for configuring the particular workbench org.eclipse.jface.window just restored
Throws:
WorkbenchException
See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)

openIntro

public void openIntro(IWorkbenchWindowConfigurer configurer)
Deprecated. since 3.1, override WorkbenchWindowAdvisor.openIntro() instead

Opens the introduction componenet.

Clients must not call this method directly (although super calls are okay). The default implementation opens the intro in the first org.eclipse.jface.window provided the org.eclipse.jface.preference IWorkbenchPreferences.SHOW_INTRO is true. If an intro is shown then this org.eclipse.jface.preference will be set to false. Subsequently, and intro will be shown only if WorkbenchConfigurer.getSaveAndRestore() returns true and the introduction was visible on last shutdown. Subclasses may override.

Parameters:
configurer - configurer an object for configuring the particular workbench org.eclipse.jface.window just created
See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)

postWindowCreate

public void postWindowCreate(IWorkbenchWindowConfigurer configurer)
Deprecated. since 3.1, override WorkbenchWindowAdvisor.postWindowCreate() instead

Performs arbitrary actions after the given workbench org.eclipse.jface.window has been created (possibly after being restored), but has not yet been opened.

This method is called after a new org.eclipse.jface.window has been created from scratch, or when a previously-saved org.eclipse.jface.window has been restored. In the latter case, this method is called after postWindowRestore. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.

Parameters:
configurer - an object for configuring the particular workbench org.eclipse.jface.window just created
See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)

postWindowOpen

public void postWindowOpen(IWorkbenchWindowConfigurer configurer)
Deprecated. since 3.1, override WorkbenchWindowAdvisor.postWindowOpen() instead

Performs arbitrary actions after the given workbench org.eclipse.jface.window has been opened (possibly after being restored).

This method is called after a org.eclipse.jface.window has been opened. This method is called after a new org.eclipse.jface.window has been created from scratch, or when a previously-saved org.eclipse.jface.window has been restored. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.

Parameters:
configurer - an object for configuring the particular workbench org.eclipse.jface.window just opened
See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)

preWindowShellClose

public boolean preWindowShellClose(IWorkbenchWindowConfigurer configurer)
Deprecated. since 3.1, override WorkbenchWindowAdvisor.preWindowShellClose() instead

Performs arbitrary actions as the given workbench org.eclipse.jface.window's shell is being closed directly, and possibly veto the close.

This method is called from a ShellListener associated with the workbench org.eclipse.jface.window. It is not called when the org.eclipse.jface.window is being closed for other reasons. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. Typical clients may use the configurer passed in to access the workbench org.eclipse.jface.window being closed. If this method returns false, then the user's request to close the shell is ignored. This gives the workbench advisor an opportunity to query the user and/or veto the closing of a org.eclipse.jface.window under some circumstances.

Parameters:
configurer - an object for configuring the particular workbench org.eclipse.jface.window whose shell is being closed
Returns:
true to allow the org.eclipse.jface.window to close, and false to prevent the org.eclipse.jface.window from closing
See Also:
IWorkbenchWindow.close(), createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)

postWindowClose

public void postWindowClose(IWorkbenchWindowConfigurer configurer)
Deprecated. since 3.1, override WorkbenchWindowAdvisor.postWindowClose() instead

Performs arbitrary actions after the given workbench org.eclipse.jface.window is closed.

This method is called after the org.eclipse.jface.window's controls have been disposed. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. Typical clients will use the configurer passed in to tweak the workbench org.eclipse.jface.window in an application-specific way.

Parameters:
configurer - an object for configuring the particular workbench org.eclipse.jface.window being closed
See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)

isApplicationMenu

public boolean isApplicationMenu(IWorkbenchWindowConfigurer configurer,
                                 java.lang.String menuId)
Deprecated. since 3.1, override ActionBarAdvisor#isApplicationMenu(String) instead

Returns whether the menu with the given id is an application menu of the given org.eclipse.jface.window. This is used during OLE "in place" editing. Application menus should be preserved during menu merging. All other menus may be removed from the org.eclipse.jface.window.

The default implementation returns false. Subclasses may override.

Parameters:
configurer - an object for configuring the workbench org.eclipse.jface.window
menuId - the menu id
Returns:
true for application menus, and false for part-specific menus
See Also:
WorkbenchWindowAdvisor#createActionBarAdvisor(IActionBarConfigurer)

getDefaultPageInput

public IAdaptable getDefaultPageInput()
Returns the default input for newly created workbench pages when the input is not explicitly specified.

The default implementation returns null. Subclasses may override.

Returns:
the default input for a new workbench org.eclipse.jface.window page, or null if none
See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)

getInitialWindowPerspectiveId

public abstract java.lang.String getInitialWindowPerspectiveId()
Returns the id of the perspective to use for the initial workbench org.eclipse.jface.window, or null if no initial perspective should be shown in the initial workbench org.eclipse.jface.window.

This method is called during startup when the workbench is creating the first new org.eclipse.jface.window. Subclasses must implement.

If the IWorkbenchPreferenceConstants.DEFAULT_PERSPECTIVE_ID org.eclipse.jface.preference is specified, it supercedes the perspective specified here.

Returns:
the id of the perspective for the initial org.eclipse.jface.window, or null if no initial perspective should be shown

getMainPreferencePageId

public java.lang.String getMainPreferencePageId()
Returns the id of the org.eclipse.jface.preference page that should be presented most prominently.

The default implementation returns null. Subclasses may override.

Returns:
the id of the org.eclipse.jface.preference page, or null if none

createWindowContents

public void createWindowContents(IWorkbenchWindowConfigurer configurer,
                                 Shell shell)
Deprecated. since 3.1, override WorkbenchWindowAdvisor.createWindowContents(Shell) instead

Creates the contents of the org.eclipse.jface.window.

The default implementation adds a menu bar, a cool bar, a status line, a perspective bar, and a fast view bar. The visibility of these controls can be configured using the setShow* methods on IWorkbenchWindowConfigurer.

Subclasses may override to define custom org.eclipse.jface.window contents and layout, but must call IWorkbenchWindowConfigurer.createPageComposite.

Parameters:
configurer - the org.eclipse.jface.window configurer
shell - the org.eclipse.jface.window's shell
See Also:
IWorkbenchWindowConfigurer#createMenuBar, IWorkbenchWindowConfigurer#createCoolBarControl, IWorkbenchWindowConfigurer.createStatusLineControl(org.eclipse.swt.widgets.Composite), IWorkbenchWindowConfigurer.createPageComposite(org.eclipse.swt.widgets.Composite), createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)

openWindows

public boolean openWindows()
Opens the workbench windows on startup. The default implementation tries to restore the previously saved workbench state using IWorkbenchConfigurer.restoreWorkbenchState(). If there was no previously saved state, or if the restore failed, then a first-time org.eclipse.jface.window is opened using IWorkbenchConfigurer.openFirstTimeWindow.

Returns:
true to proceed with workbench startup, or false to exit

createEmptyWindowContents

public Control createEmptyWindowContents(IWorkbenchWindowConfigurer configurer,
                                         Composite parent)
Deprecated. since 3.1, override WorkbenchWindowAdvisor.createEmptyWindowContents(Composite) instead

Creates and returns the control to be shown when a org.eclipse.jface.window has no open pages. If null is returned, the default org.eclipse.jface.window background is shown.

The default implementation returns null. Subclasses may override.

Parameters:
configurer - an object for configuring the workbench org.eclipse.jface.window
parent - the parent composite
Returns:
the control or null
Since:
3.1
See Also:
TODO: get rid of this before M6 since it was both introduced and deprecated in 3.1