Class WorkbenchAdvisor
- java.lang.Object
-
- org.eclipse.ui.application.WorkbenchAdvisor
-
public abstract class WorkbenchAdvisor extends 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.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
):initialize
- called first; before any windows; use to register thingspreStartup
- called second; after initialize but before first window is opened; use to temporarily disable things during startup or restorepostStartup
- called third; after first window is opened; use to reenable things temporarily disabled in previous steppostRestore
- called after the workbench and its windows has been recreated from a previously saved state; use to adjust the restored workbenchpreWindowOpen
- called as each window is being opened; use to configure aspects of the window other than actions barsfillActionBars
- called afterpreWindowOpen
to configure a window's action barspostWindowRestore
- called after a window has been recreated from a previously saved state; use to adjust the restored windowpostWindowCreate
- called after a window has been created, either from an initial state or from a restored state; used to adjust the windowopenIntro
- 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 closingseventLoopException
- called to handle the case where the event loop has crashed; use to inform the user that things are not welleventLoopIdle
- called when there are currently no more events to be processed; use to perform other work or to yield until new events enter the queuepreShutdown
- called immediately prior to workbench shutdown before any windows have been closed; allows the advisor to veto the shutdownpostShutdown
- called last; after event loop has terminated and all windows have been closed; use to deregister things registered during initialize
- Since:
- 3.0
-
-
Field Summary
Fields Modifier and Type Field Description static int
FILL_COOL_BAR
Deprecated.useinstead
static int
FILL_MENU_BAR
Deprecated.useinstead
static int
FILL_PROXY
Deprecated.useinstead
static int
FILL_STATUS_LINE
Deprecated.useinstead
-
Constructor Summary
Constructors Modifier Constructor Description protected
WorkbenchAdvisor()
Creates and initializes a new workbench advisor instance.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
createWindowContents(IWorkbenchWindowConfigurer configurer, Shell shell)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.createWindowContents(Shell)
insteadWorkbenchWindowAdvisor
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer)
Creates a new workbench window advisor for configuring a new workbench window via the given workbench window configurer.void
eventLoopException(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.void
fillActionBars(IWorkbenchWindow window, IActionBarConfigurer configurer, int flags)
Deprecated.since 3.1, overrideActionBarAdvisor.fillActionBars(int)
insteadContributionComparator
getComparatorFor(String contributionType)
Return the contribution comparator for the particular type of contribution.IAdaptable
getDefaultPageInput()
Returns the default input for newly created workbench pages when the input is not explicitly specified.abstract String
getInitialWindowPerspectiveId()
Returns the id of the perspective to use for the initial workbench window, ornull
if no initial perspective should be shown in the initial workbench window.String
getMainPreferencePageId()
Returns the id of the preference page that should be presented most prominently.protected IWorkbenchConfigurer
getWorkbenchConfigurer()
Returns the workbench configurer for the advisor.AbstractStatusHandler
getWorkbenchErrorHandler()
Returns the workbench error handler for the advisor.void
initialize(IWorkbenchConfigurer configurer)
Performs arbitrary initialization before the workbench starts running.void
internalBasicInitialize(IWorkbenchConfigurer configurer)
Remembers the configurer and callsinitialize
.boolean
isApplicationMenu(IWorkbenchWindowConfigurer configurer, String menuId)
Deprecated.since 3.1, overrideActionBarAdvisor.isApplicationMenu(String)
insteadvoid
openIntro(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.openIntro()
insteadboolean
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, overrideWorkbenchWindowAdvisor.postWindowClose()
insteadvoid
postWindowCreate(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.postWindowCreate()
insteadvoid
postWindowOpen(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.postWindowOpen()
insteadvoid
postWindowRestore(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.postWindowRestore()
insteadboolean
preShutdown()
Performs arbitrary finalization before the workbench is about to shut down.void
preStartup()
Performs arbitrary actions just before the first workbench window is opened (or restored).void
preWindowOpen(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.preWindowOpen()
insteadboolean
preWindowShellClose(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.preWindowShellClose()
insteadIStatus
restoreState(IMemento memento)
Restores arbitrary application-specific state information for this workbench advisor.IStatus
saveState(IMemento memento)
Saves arbitrary application-specific state information for this workbench advisor.
-
-
-
Field Detail
-
FILL_PROXY
@Deprecated public static final int FILL_PROXY
Deprecated.useinstead
Bit flag forfillActionBars
indicating that the operation is not filling the action bars of an actual workbench window, but rather a proxy (used for perspective customization).- See Also:
- Constant Field Values
-
FILL_MENU_BAR
@Deprecated public static final int FILL_MENU_BAR
Deprecated.useinstead
Bit flag forfillActionBars
indicating that the operation is supposed to fill (or describe) the workbench window's menu bar.- See Also:
- Constant Field Values
-
FILL_COOL_BAR
@Deprecated public static final int FILL_COOL_BAR
Deprecated.useinstead
Bit flag forfillActionBars
indicating that the operation is supposed to fill (or describe) the workbench window's cool bar.- See Also:
- Constant Field Values
-
FILL_STATUS_LINE
@Deprecated public static final int FILL_STATUS_LINE
Deprecated.useinstead
Bit flag forfillActionBars
indicating that the operation is supposed to fill (or describe) the workbench window's status line.- See Also:
- Constant Field Values
-
-
Method Detail
-
internalBasicInitialize
public final void internalBasicInitialize(IWorkbenchConfigurer configurer)
Remembers the configurer and callsinitialize
.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 benull
if the advisor is not initialized yet.- Returns:
- the workbench configurer, or
null
if the advisor is not initialized yet
-
getWorkbenchErrorHandler
public AbstractStatusHandler getWorkbenchErrorHandler()
Returns the workbench error handler for the advisor.- Returns:
- the workbench error handler
- Since:
- 3.3
-
preStartup
public void preStartup()
Performs arbitrary actions just before the first workbench window is opened (or restored).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.
-
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(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)
Creates a new workbench window advisor for configuring a new workbench window via the given workbench window configurer. Clients should override to provide their own window configurer. This method replaces all the other window and action bar lifecycle methods on the workbench advisor.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.
- Parameters:
configurer
- the workbench window configurer- Returns:
- a new workbench window advisor
- Since:
- 3.1
-
preWindowOpen
@Deprecated public void preWindowOpen(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.preWindowOpen()
insteadPerforms arbitrary actions before the given workbench window is 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). 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
fillActionBars
, which is called immediately after this method is called.- Parameters:
configurer
- an object for configuring the particular workbench window being opened- See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
-
fillActionBars
@Deprecated public void fillActionBars(IWorkbenchWindow window, IActionBarConfigurer configurer, int flags)
Deprecated.since 3.1, overrideActionBarAdvisor.fillActionBars(int)
insteadConfigures the action bars using the given action bar configurer. Under normal circumstances,flags
does not includeFILL_PROXY
, meaning this is a request to fill the actions\ bars of the given workbench window; the remaining flags indicate which combination of the menu bar (FILL_MENU_BAR
), the tool bar (FILL_COOL_BAR
), and the status line (FILL_STATUS_LINE
) are to be filled.If
flags
does includeFILL_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. CallingActionFactory
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
preWindowOpen
. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.- Parameters:
window
- the workbench windowconfigurer
- the action bar configurer objectflags
- bit mask composed from the constantsFILL_MENU_BAR
,FILL_COOL_BAR
,FILL_STATUS_LINE
, andFILL_PROXY
Note: should 1st param be IWorkbenchWindowConfigurer to be more consistent with other methods? Note: suggest adding ActionBuilder as API, to encapsulate the action building outside of the advisor, and to handle the common pattern of hanging onto the action builder in order to properly handle FILL_PROXY- See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
,WorkbenchWindowAdvisor.createActionBarAdvisor(IActionBarConfigurer)
-
postWindowRestore
@Deprecated public void postWindowRestore(IWorkbenchWindowConfigurer configurer) throws WorkbenchException
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.postWindowRestore()
insteadPerforms arbitrary actions after the given workbench window has been restored, but before it is opened.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.- Parameters:
configurer
- an object for configuring the particular workbench window just restored- Throws:
WorkbenchException
- exception to throw when something failed.- See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
-
openIntro
@Deprecated public void openIntro(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.openIntro()
insteadOpens the introduction componenet.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 tofalse
. Subsequently, and intro will be shown only ifWorkbenchConfigurer.getSaveAndRestore()
returnstrue
and the introduction was visible on last shutdown. Subclasses may override.- Parameters:
configurer
- configurer an object for configuring the particular workbench window just created- See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
-
postWindowCreate
@Deprecated public void postWindowCreate(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.postWindowCreate()
insteadPerforms arbitrary actions after the given workbench window has been created (possibly after being restored), but has not yet been opened.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.- Parameters:
configurer
- an object for configuring the particular workbench window just created- See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
-
postWindowOpen
@Deprecated public void postWindowOpen(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.postWindowOpen()
insteadPerforms arbitrary actions after the given workbench window has been opened (possibly after being restored).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.
- Parameters:
configurer
- an object for configuring the particular workbench window just opened- See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
-
preWindowShellClose
@Deprecated public boolean preWindowShellClose(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.preWindowShellClose()
insteadPerforms arbitrary actions as the given workbench window's shell is being closed directly, and possibly veto the close.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.- Parameters:
configurer
- an object for configuring the particular workbench window whose shell is being closed- Returns:
true
to allow the window to close, andfalse
to prevent the window from closing- See Also:
IWorkbenchWindow.close()
,createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
-
postWindowClose
@Deprecated public void postWindowClose(IWorkbenchWindowConfigurer configurer)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.postWindowClose()
insteadPerforms arbitrary actions after the given workbench window is closed.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.
- Parameters:
configurer
- an object for configuring the particular workbench window being closed- See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
-
isApplicationMenu
@Deprecated public boolean isApplicationMenu(IWorkbenchWindowConfigurer configurer, String menuId)
Deprecated.since 3.1, overrideActionBarAdvisor.isApplicationMenu(String)
insteadReturns whether the menu with the given id is an application menu of the given 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 window.The default implementation returns false. Subclasses may override.
- Parameters:
configurer
- an object for configuring the workbench windowmenuId
- the menu id- Returns:
true
for application menus, andfalse
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 window page, or
null
if none - See Also:
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
-
getInitialWindowPerspectiveId
public abstract String getInitialWindowPerspectiveId()
Returns the id of the perspective to use for the initial workbench window, ornull
if no initial perspective should be shown in the initial workbench window.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.- Returns:
- the id of the perspective for the initial window, or
null
if no initial perspective should be shown
-
getMainPreferencePageId
public String getMainPreferencePageId()
Returns the id of the preference page that should be presented most prominently.The default implementation returns
null
. Subclasses may override.- Returns:
- the id of the preference page, or
null
if none
-
createWindowContents
@Deprecated public void createWindowContents(IWorkbenchWindowConfigurer configurer, Shell shell)
Deprecated.since 3.1, overrideWorkbenchWindowAdvisor.createWindowContents(Shell)
insteadCreates the contents of the 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 onIWorkbenchWindowConfigurer
.Subclasses may override to define custom window contents and layout, but must call
IWorkbenchWindowConfigurer.createPageComposite
.- Parameters:
configurer
- the window configurershell
- the window's shell- See Also:
IWorkbenchWindowConfigurer.createMenuBar()
,IWorkbenchWindowConfigurer.createCoolBarControl(org.eclipse.swt.widgets.Composite)
,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 usingIWorkbenchConfigurer.restoreWorkbenchState()
. If there was no previously saved state, or if the restore failed, then a first-time window is opened usingIWorkbenchConfigurer.openFirstTimeWindow
.- Returns:
true
to proceed with workbench startup, orfalse
to exit
-
saveState
public IStatus saveState(IMemento memento)
Saves arbitrary application-specific state information for this workbench advisor.The default implementation simply returns an OK status. Subclasses may extend or override.
- Parameters:
memento
- the memento in which to save the advisor'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 for this workbench advisor.The default implementation simply returns an OK status. Subclasses may extend or override.
- Parameters:
memento
- the memento from which to restore the advisor's state- Returns:
- a status object indicating whether the restore was successful
- Since:
- 3.1
-
getComparatorFor
public ContributionComparator getComparatorFor(String contributionType)
Return the contribution comparator for the particular type of contribution. The default implementation of this class returns a comparator that sorts the items by label. The contributionType may be one of the constants inIContributionService
or it can be a value defined by the user.- Parameters:
contributionType
- the contribution type- Returns:
- the comparator, must not return
null
- Since:
- 3.4
- See Also:
IContributionService.getComparatorFor(String)
-
-