org.eclipse.ui.application
Class WorkbenchWindowAdvisor

java.lang.Object
  extended by org.eclipse.ui.application.WorkbenchWindowAdvisor

public class WorkbenchWindowAdvisor
extends java.lang.Object

Public base class for configuring a workbench org.eclipse.jface.window.

The workbench org.eclipse.jface.window advisor object is created in response to a workbench org.eclipse.jface.window being created (one per org.eclipse.jface.window), and is used to configure the org.eclipse.jface.window.

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

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

Since:
3.1

Constructor Summary
WorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer)
          Creates a new workbench org.eclipse.jface.window advisor for configuring a workbench org.eclipse.jface.window via the given workbench org.eclipse.jface.window configurer.
 
Method Summary
 Control createEmptyWindowContents(Composite parent)
          Creates and returns the control to be shown when the org.eclipse.jface.window has no open pages.
 void createWindowContents(Shell shell)
          Creates the contents of the org.eclipse.jface.window.
 void dispose()
          Disposes any resources allocated by this org.eclipse.jface.window advisor.
protected  IWorkbenchWindowConfigurer getWindowConfigurer()
          Returns the workbench org.eclipse.jface.window configurer.
 void openIntro()
          Opens the introduction componenet.
 void postWindowClose()
          Performs arbitrary actions after the org.eclipse.jface.window is closed.
 void postWindowCreate()
          Performs arbitrary actions after the org.eclipse.jface.window has been created (possibly after being restored), but has not yet been opened.
 void postWindowOpen()
          Performs arbitrary actions after the org.eclipse.jface.window has been opened (possibly after being restored).
 void postWindowRestore()
          Performs arbitrary actions after the org.eclipse.jface.window has been restored, but before it is opened.
 void preWindowOpen()
          Performs arbitrary actions before the org.eclipse.jface.window is opened.
 boolean preWindowShellClose()
          Performs arbitrary actions as the org.eclipse.jface.window's shell is being closed directly, and possibly veto the close.
 IStatus restoreState(IMemento memento)
          Restores arbitrary application specific state information.
 IStatus saveState(IMemento memento)
          Saves arbitrary application specific state information.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WorkbenchWindowAdvisor

public WorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer)
Creates a new workbench org.eclipse.jface.window advisor for configuring a workbench org.eclipse.jface.window via the given workbench org.eclipse.jface.window configurer.

Parameters:
configurer - an object for configuring the workbench org.eclipse.jface.window
Method Detail

getWindowConfigurer

protected IWorkbenchWindowConfigurer getWindowConfigurer()
Returns the workbench org.eclipse.jface.window configurer.

Returns:
the workbench org.eclipse.jface.window configurer

preWindowOpen

public void preWindowOpen()
Performs arbitrary actions before the 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 org.eclipse.jface.window configurer 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 ActionBarAdvisor#fillActionBars, which is called immediately after this method is called.


postWindowRestore

public void postWindowRestore()
                       throws WorkbenchException
Performs arbitrary actions after the org.eclipse.jface.window has been restored, but before it is opened.

This method is called after a previously-saved org.eclipse.jface.window has 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.

Throws:
WorkbenchException - thrown if there are any errors to report from post-restoration of the org.eclipse.jface.window

openIntro

public void openIntro()
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 if 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.


postWindowCreate

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

This method is called after the org.eclipse.jface.window has been created from scratch, or when it has been restored from a previously-saved org.eclipse.jface.window. 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.


postWindowOpen

public void postWindowOpen()
Performs arbitrary actions after the org.eclipse.jface.window has been opened (possibly after being restored).

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


preWindowShellClose

public boolean preWindowShellClose()
Performs arbitrary actions as the 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 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). 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.

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

postWindowClose

public void postWindowClose()
Performs arbitrary actions after the 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.


createWindowContents

public void createWindowContents(Shell shell)
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:
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)

createEmptyWindowContents

public Control createEmptyWindowContents(Composite parent)
Creates and returns the control to be shown when the 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:
parent - the parent composite
Returns:
the control or null

dispose

public void dispose()
Disposes any resources allocated by this org.eclipse.jface.window advisor. This is the last method called on this org.eclipse.jface.window advisor by the workbench. The default implementation does nothing. Subclasses may extend.


saveState

public IStatus saveState(IMemento memento)
Saves arbitrary application specific state information.

Parameters:
memento - the storage area for object's state
Returns:
a status object indicating whether the save was successful
Since:
3.1

restoreState

public IStatus restoreState(IMemento memento)
Restores arbitrary application specific state information.

Parameters:
memento - the storage area for object's state
Returns:
a status object indicating whether the restore was successful
Since:
3.1