|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.ui.application.WorkbenchAdvisor
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 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 bars fillActionBars
- called after preWindowOpen
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
Field Summary | |
---|---|
static int |
FILL_COOL_BAR
Deprecated. use instead |
static int |
FILL_MENU_BAR
Deprecated. use instead |
static int |
FILL_PROXY
Deprecated. use instead |
static int |
FILL_STATUS_LINE
Deprecated. use instead |
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 |
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. |
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 |
Field Detail |
public static final int FILL_PROXY
instead
fillActionBars
indicating that the
operation is not filling the action bars of an actual workbench window,
but rather a proxy (used for perspective customization).
public static final int FILL_MENU_BAR
instead
fillActionBars
indicating that the
operation is supposed to fill (or describe) the workbench window's menu
bar.
public static final int FILL_COOL_BAR
instead
fillActionBars
indicating that the
operation is supposed to fill (or describe) the workbench window's cool
bar.
public static final int FILL_STATUS_LINE
instead
fillActionBars
indicating that the
operation is supposed to fill (or describe) the workbench window's status
line.
Constructor Detail |
protected WorkbenchAdvisor()
Method Detail |
public final void internalBasicInitialize(IWorkbenchConfigurer configurer)
initialize
.
For internal use by the workbench only.
configurer
- an object for configuring the workbenchpublic void initialize(IWorkbenchConfigurer configurer)
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
.
configurer
- an object for configuring the workbenchprotected IWorkbenchConfigurer getWorkbenchConfigurer()
null
if the advisor is not initialized yet.
null
if the advisor is not initialized yetpublic void preStartup()
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.
public void postStartup()
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.
public boolean preShutdown()
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.
true
to allow the workbench to proceed with shutdown,
false
to veto a non-forced shutdownpublic void postShutdown()
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.
public void eventLoopException(Throwable exception)
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.
exception
- the uncaught exception that was thrown inside the UI
event looppublic void eventLoopIdle(Display display)
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.
display
- the main display of the workbench UIpublic WorkbenchWindowAdvisor createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer)
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.
configurer
- the workbench window configurer
public void preWindowOpen(IWorkbenchWindowConfigurer configurer)
WorkbenchWindowAdvisor.preWindowOpen()
instead
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.
configurer
- an object for configuring the particular workbench
window being openedcreateWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
public void fillActionBars(IWorkbenchWindow window, IActionBarConfigurer configurer, int flags)
ActionBarAdvisor.fillActionBars(int)
instead
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.
window
- the workbench windowconfigurer
- the action bar configurer objectflags
- 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_PROXYcreateWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
,
WorkbenchWindowAdvisor.createActionBarAdvisor(IActionBarConfigurer)
public void postWindowRestore(IWorkbenchWindowConfigurer configurer) throws WorkbenchException
WorkbenchWindowAdvisor.postWindowRestore()
instead
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.
configurer
- an object for configuring the particular workbench
window just restored
WorkbenchException
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
public void openIntro(IWorkbenchWindowConfigurer configurer)
WorkbenchWindowAdvisor.openIntro()
instead
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.
configurer
- configurer an object for configuring the particular workbench
window just createdcreateWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
public void postWindowCreate(IWorkbenchWindowConfigurer configurer)
WorkbenchWindowAdvisor.postWindowCreate()
instead
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.
configurer
- an object for configuring the particular workbench
window just createdcreateWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
public void postWindowOpen(IWorkbenchWindowConfigurer configurer)
WorkbenchWindowAdvisor.postWindowOpen()
instead
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.
configurer
- an object for configuring the particular workbench
window just openedcreateWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
public boolean preWindowShellClose(IWorkbenchWindowConfigurer configurer)
WorkbenchWindowAdvisor.preWindowShellClose()
instead
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.
configurer
- an object for configuring the particular workbench
window whose shell is being closed
true
to allow the window to close,
and false
to prevent the window from closingIWorkbenchWindow.close()
,
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
public void postWindowClose(IWorkbenchWindowConfigurer configurer)
WorkbenchWindowAdvisor.postWindowClose()
instead
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.
configurer
- an object for configuring the particular workbench
window being closedcreateWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
public boolean isApplicationMenu(IWorkbenchWindowConfigurer configurer, String menuId)
ActionBarAdvisor.isApplicationMenu(String)
instead
The default implementation returns false. Subclasses may override.
configurer
- an object for configuring the workbench windowmenuId
- the menu id
true
for application menus, and false
for part-specific menusWorkbenchWindowAdvisor.createActionBarAdvisor(IActionBarConfigurer)
public IAdaptable getDefaultPageInput()
The default implementation returns null
.
Subclasses may override.
null
if nonecreateWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
public abstract String getInitialWindowPerspectiveId()
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.
null
if no initial perspective should be shownpublic String getMainPreferencePageId()
The default implementation returns null
.
Subclasses may override.
null
if nonepublic void createWindowContents(IWorkbenchWindowConfigurer configurer, Shell shell)
WorkbenchWindowAdvisor.createWindowContents(Shell)
instead
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
.
configurer
- the window configurershell
- the window's shellIWorkbenchWindowConfigurer.createMenuBar()
,
IWorkbenchWindowConfigurer.createCoolBarControl(org.eclipse.swt.widgets.Composite)
,
IWorkbenchWindowConfigurer.createStatusLineControl(org.eclipse.swt.widgets.Composite)
,
IWorkbenchWindowConfigurer.createPageComposite(org.eclipse.swt.widgets.Composite)
,
createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer)
public boolean openWindows()
IWorkbenchConfigurer.restoreWorkbenchState()
.
If there was no previously saved state, or if the restore failed,
then a first-time window is opened using
IWorkbenchConfigurer.openFirstTimeWindow
.
true
to proceed with workbench startup,
or false
to exitpublic IStatus saveState(IMemento memento)
The default implementation simply returns an OK status. Subclasses may extend or override.
memento
- the memento in which to save the advisor's state
public IStatus restoreState(IMemento memento)
The default implementation simply returns an OK status. Subclasses may extend or override.
memento
- the memento from which to restore the advisor's state
|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.