org.eclipse.ui.application
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.
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):
-
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
-
Since:
- 3.0
|
Constructor Summary
|
protected
|
WorkbenchAdvisor
()
Creates and initializes a new workbench advisor instance. |
|
Method Summary
|
void
|
createWindowContents
(
IWorkbenchWindowConfigurer configurer,
Shell shell)
Deprecated. since 3.1, override
WorkbenchWindowAdvisor.createWindowContents(Shell)
instead
|
WorkbenchWindowAdvisor
|
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, override
ActionBarAdvisor.fillActionBars(int) instead
|
ContributionComparator
|
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, or null 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 calls initialize. |
boolean
|
isApplicationMenu
(
IWorkbenchWindowConfigurer configurer,
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 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
|
IStatus
|
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. |
|
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
FILL_PROXY
public static final int FILL_PROXY
-
Deprecated. use
instead
- Bit flag for
fillActionBars 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
public static final int FILL_MENU_BAR
-
Deprecated. use
instead
- Bit flag for
fillActionBars indicating that the
operation is supposed to fill (or describe) the workbench window's menu
bar.
-
See Also:
-
Constant Field Values
FILL_COOL_BAR
public static final int FILL_COOL_BAR
-
Deprecated. use
instead
- Bit flag for
fillActionBars indicating that the
operation is supposed to fill (or describe) the workbench window's cool
bar.
-
See Also:
-
Constant Field Values
FILL_STATUS_LINE
public static final int FILL_STATUS_LINE
-
Deprecated. use
instead
- Bit flag for
fillActionBars indicating that the
operation is supposed to fill (or describe) the workbench window's status
line.
-
See Also:
-
Constant Field Values
WorkbenchAdvisor
protected WorkbenchAdvisor()
- Creates and initializes a new workbench advisor instance.
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
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
public void preWindowOpen(
IWorkbenchWindowConfigurer configurer)
-
Deprecated. since 3.1, override
WorkbenchWindowAdvisor.preWindowOpen() instead
- Performs 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
public void fillActionBars(
IWorkbenchWindow window,
IActionBarConfigurer configurer,
int flags)
-
Deprecated. since 3.1, override
ActionBarAdvisor.fillActionBars(int) instead
- Configures the action bars using the given action bar configurer. Under
normal circumstances,
flags does not include
FILL_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 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
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 window -
configurer - the action bar configurer object -
flags - bit mask composed from the constants
FILL_MENU_BAR,
FILL_COOL_BAR,
FILL_STATUS_LINE, and
FILL_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
public void postWindowRestore(
IWorkbenchWindowConfigurer configurer)
throws
WorkbenchException
-
Deprecated. since 3.1, override
WorkbenchWindowAdvisor.postWindowRestore() instead
- Performs 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
-
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 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.
-
-
Parameters:
-
configurer - configurer an object for configuring the particular workbench
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 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
public void postWindowOpen(
IWorkbenchWindowConfigurer configurer)
-
Deprecated. since 3.1, override
WorkbenchWindowAdvisor.postWindowOpen() instead
- Performs 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
public boolean preWindowShellClose(
IWorkbenchWindowConfigurer configurer)
-
Deprecated. since 3.1, override
WorkbenchWindowAdvisor.preWindowShellClose() instead
- Performs 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, and
false to prevent the 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 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
public boolean isApplicationMenu(
IWorkbenchWindowConfigurer configurer,
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 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 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 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, or
null 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
public void createWindowContents(
IWorkbenchWindowConfigurer configurer,
Shell shell)
-
Deprecated. since 3.1, override
WorkbenchWindowAdvisor.createWindowContents(Shell)
instead
- Creates 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 on
IWorkbenchWindowConfigurer.
Subclasses may override to define custom window contents and layout, but
must call IWorkbenchWindowConfigurer.createPageComposite.
-
-
Parameters:
-
configurer - the window configurer -
shell - 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 using
IWorkbenchConfigurer.restoreWorkbenchState(). If there
was no previously saved state, or if the restore failed, then a
first-time window is opened using
IWorkbenchConfigurer.openFirstTimeWindow.
-
-
Returns:
-
true to proceed with workbench startup, or
false 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 in
IContributionService 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)
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
