Java Doc for WorkbenchAdvisor.java in  » IDE-Eclipse » ui-workbench » org » eclipse » ui » application » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 PlatformUI.createAndRunWorkbench ):

• initialize - called first; before any windows; use to register things
• preStartup - called second; after initialize but before first window is opened; use to temporarily disable things during startup or restore
• postStartup - called third; after first window is opened; use to reenable things temporarily disabled in previous step
• postRestore - called after the workbench and its windows has been recreated from a previously saved state; use to adjust the restored workbench
• preWindowOpen - called as each window is being opened; use to configure aspects of the window other than actions bars
• fillActionBars - called after preWindowOpen to configure a window's action bars
• postWindowRestore - called after a window has been recreated from a previously saved state; use to adjust the restored window
• postWindowCreate - called after a window has been created, either from an initial state or from a restored state; used to adjust the window
• openIntro - called immediately before a window is opened in order to create the introduction component, if any.
• postWindowOpen - called after a window has been opened; use to hook window listeners, etc.
• preWindowShellClose - called when a window's shell is closed by the user; use to pre-screen window closings
• eventLoopException - called to handle the case where the event loop has crashed; use to inform the user that things are not well
• eventLoopIdle - called when there are currently no more events to be processed; use to perform other work or to yield until new events enter the queue
• preShutdown - called immediately prior to workbench shutdown before any windows have been closed; allows the advisor to veto the shutdown
• postShutdown - called last; after event loop has terminated and all windows have been closed; use to deregister things registered during initialize

The default implementation adds a menu bar, a cool bar, a status line, a perspective bar, and a fast view bar.

This method is called when the code handling a UI event throws an exception.

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 returns null.

This method is called during startup when the workbench is creating the first new window.

The default implementation returns null.

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).

This method is called during workbench shutdown after all windows have been closed.

This method is called just after the windows have been opened.

This method is called after the window's controls have been disposed. Clients must not call this method directly (although super calls are okay).

This method is called after a new window has been created from scratch, or when a previously-saved window has been restored.

This method is called after a window has been opened.

This method is called after a previously-saved window have been recreated.

This method is called immediately prior to workbench shutdown before any windows have been closed.

This method is called after the workbench has been initialized and just before the first window is about to be opened.

This method is called before the window's controls have been created. Clients must not call this method directly (although super calls are okay).

This method is called from a ShellListener associated with the workbench window.

The default implementation simply returns an OK status.

The default implementation simply returns an OK status.

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 window contents and layout, but must call IWorkbenchWindowConfigurer.createPageComposite.

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

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.

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.

If flags does include FILL_PROXY, then this is a request to describe the actions bars of the given workbench window (which will already have been filled); again, the remaining flags indicate which combination of the menu bar, the tool bar, and the status line are to be described. The actions included in the proxy action bars can be the same instances as in the actual window's action bars. Calling ActionFactory to create new action instances is not recommended, because these actions internally register listeners with the window and there is no opportunity to dispose of these actions.

This method is called just after WorkbenchAdvisor.preWindowOpen preWindowOpen . Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.

The default implementation returns null. Subclasses may override.

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

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

The default implementation returns null. Subclasses may override.

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.

For internal use by the workbench only.

The default implementation returns false. Subclasses may override.

Clients must not call this method directly (although super calls are okay). The default implementation opens the intro in the first window provided the preference IWorkbenchPreferences.SHOW_INTRO is true. If an intro is shown then this 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.

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.

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.

This method is called after the 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 window in an application-specific way.

This method is called after a new window has been created from scratch, or when a previously-saved 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.

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

This method is called after a previously-saved window have been recreated. This method is not called when a new 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.

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.

This method is called after the workbench has been initialized and just before the first 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.

This method is called before the 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 window in an application-specific way; however, filling the window's menu bar, tool bar, and status line must be done in WorkbenchAdvisor.fillActionBars fillActionBars , which is called immediately after this method is called.

This method is called from a ShellListener associated with the workbench window. It is not called when the 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 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 window under some circumstances.

The default implementation simply returns an OK status. Subclasses may extend or override.

The default implementation simply returns an OK status. Subclasses may extend or override.