Eclipse eRCP
Release 1.1

org.eclipse.ui
Interface IWorkbench


public interface IWorkbench

A workbench is the root object for the Eclipse Platform user interface.

A workbench has one or more main windows which present to the end user information based on some underlying model, typically on resources in an underlying workspace. A workbench usually starts with a single open org.eclipse.jface.window, and automatically closes when its last org.eclipse.jface.window closes.

Each workbench org.eclipse.jface.window has a collection of pages; the active page is the one that is being presented to the end user; at most one page is active in a org.eclipse.jface.window at a time.

Each workbench page has a collection of workbench parts, of which there are two kinds: views and editors. A page's parts are arranged (tiled or stacked) for presentation on the screen. The arrangement is not fixed; the user can arrange the parts as they see fit. A perspective is a template for a page, capturing a collection of parts and their arrangement.

The platform creates a workbench when the workbench plug-in is activated; since this happens at most once during the life of the running platform, there is only one workbench instance. Due to its singular nature, it is commonly referred to as the workbench.

This interface is not intended to be implemented by clients.

See Also:
PlatformUI.getWorkbench()

Method Summary
 void addWindowListener(IWindowListener listener)
          Adds a org.eclipse.jface.window listener.
 boolean close()
          Closes this workbench and all its open windows.
 IWorkbenchWindow getActiveWorkbenchWindow()
          Returns the currently active org.eclipse.jface.window for this workbench (if any).
 IWorkbenchCommandSupport getCommandSupport()
          Deprecated. Please use getAdapter(ICommandService.class) instead.
 Display getDisplay()
          Returns the display for this workbench.
 IElementFactory getElementFactory(String factoryId)
          Returns the element factory with the given id.
 IExtensionTracker getExtensionTracker()
           Return the extension tracker for the workbench.
 IPerspectiveRegistry getPerspectiveRegistry()
          Returns the perspective registry for the workbench.
 PreferenceManager getPreferenceManager()
          Returns the org.eclipse.jface.preference manager for the workbench.
 IPreferenceStore getPreferenceStore()
          Returns the org.eclipse.jface.preference store for the workbench.
 ISharedImages getSharedImages()
          Returns the shared images for the workbench.
 IViewRegistry getViewRegistry()
          Returns the editor registry for the workbench.
 int getWorkbenchWindowCount()
          Returns the number of open main windows associated with this workbench.
 IWorkbenchWindow[] getWorkbenchWindows()
          Returns a list of the open main windows associated with this workbench.
 boolean isClosing()
          Returns a boolean indicating whether the workbench is in the process of closing.
 IWorkbenchWindow openWorkbenchWindow(IAdaptable input)
          Creates and opens a new workbench org.eclipse.jface.window with one page.
 IWorkbenchWindow openWorkbenchWindow(String perspectiveId, IAdaptable input)
          Creates and opens a new workbench org.eclipse.jface.window with one page.
 void removeWindowListener(IWindowListener listener)
          Removes a org.eclipse.jface.window listener.
 boolean restart()
          Closes then restarts this workbench.
 IWorkbenchPage showPerspective(String perspectiveId, IWorkbenchWindow window)
          Shows the specified perspective to the user.
 IWorkbenchPage showPerspective(String perspectiveId, IWorkbenchWindow window, IAdaptable input)
          Shows the specified perspective to the user.
 

Method Detail

getDisplay

public Display getDisplay()
Returns the display for this workbench.

Code should always ask the workbench for the display rather than rely on Display.getDefault().

Returns:
the display to be used for all UI interactions with this workbench
Since:
3.0

addWindowListener

public void addWindowListener(IWindowListener listener)
Adds a org.eclipse.jface.window listener.

Parameters:
listener - the org.eclipse.jface.window listener to add
Since:
2.0

removeWindowListener

public void removeWindowListener(IWindowListener listener)
Removes a org.eclipse.jface.window listener.

Parameters:
listener - the org.eclipse.jface.window listener to remove
Since:
2.0

close

public boolean close()
Closes this workbench and all its open windows.

If the workbench has an open editor with unsaved content, the user will be given the opportunity to save it.

Returns:
true if the workbench was successfully closed, and false if it is still open

getActiveWorkbenchWindow

public IWorkbenchWindow getActiveWorkbenchWindow()
Returns the currently active org.eclipse.jface.window for this workbench (if any). Returns null if there is no active workbench org.eclipse.jface.window. Returns null if called from a non-UI thread.

Returns:
the active workbench org.eclipse.jface.window, or null if there is no active workbench org.eclipse.jface.window or if called from a non-UI thread

getPerspectiveRegistry

public IPerspectiveRegistry getPerspectiveRegistry()
Returns the perspective registry for the workbench.

Returns:
the workbench perspective registry

getPreferenceManager

public PreferenceManager getPreferenceManager()
Returns the org.eclipse.jface.preference manager for the workbench.

Returns:
the workbench org.eclipse.jface.preference manager

getPreferenceStore

public IPreferenceStore getPreferenceStore()
Returns the org.eclipse.jface.preference store for the workbench.

Returns:
the workbench org.eclipse.jface.preference store
Since:
2.0

getSharedImages

public ISharedImages getSharedImages()
Returns the shared images for the workbench.

Returns:
the shared image manager

getWorkbenchWindowCount

public int getWorkbenchWindowCount()
Returns the number of open main windows associated with this workbench. Note that wizards and org.eclipse.jface.dialogs are not included in this list since they are not considered main windows.

Returns:
the number of open windows
Since:
3.0 @issue Use getWorkbenchWindows().length?

getWorkbenchWindows

public IWorkbenchWindow[] getWorkbenchWindows()
Returns a list of the open main windows associated with this workbench. Note that wizards and org.eclipse.jface.dialogs are not included in this list since they are not considered main windows.

Returns:
a list of open windows

openWorkbenchWindow

public IWorkbenchWindow openWorkbenchWindow(String perspectiveId,
                                            IAdaptable input)
                                     throws WorkbenchException
Creates and opens a new workbench org.eclipse.jface.window with one page. The perspective of the new page is defined by the specified perspective ID. The new org.eclipse.jface.window and new page become active.

Note: The caller is responsible to ensure the action using this method will explicitly inform the user a new org.eclipse.jface.window will be opened. Otherwise, callers are strongly recommended to use the openPerspective APIs to programmatically show a perspective to avoid confusing the user.

In most cases where this method is used the caller is tightly coupled to a particular perspective. They define it in the registry and contribute some user interface action to open or activate it. In situations like this a static variable is often used to identify the perspective ID.

Parameters:
perspectiveId - the perspective id for the org.eclipse.jface.window's initial page, or null for no initial page
input - the page input, or null if there is no current input. This is used to seed the input for the new page's views.
Returns:
the new workbench org.eclipse.jface.window
Throws:
WorkbenchException - if a new org.eclipse.jface.window and page could not be opened
See Also:
showPerspective(String, IWorkbenchWindow, IAdaptable)

openWorkbenchWindow

public IWorkbenchWindow openWorkbenchWindow(IAdaptable input)
                                     throws WorkbenchException
Creates and opens a new workbench org.eclipse.jface.window with one page. The perspective of the new page is defined by the default perspective ID. The new org.eclipse.jface.window and new page become active.

Note: The caller is responsible to ensure the action using this method will explicitly inform the user a new org.eclipse.jface.window will be opened. Otherwise, callers are strongly recommended to use the openPerspective APIs to programmatically show a perspective to avoid confusing the user.

Parameters:
input - the page input, or null if there is no current input. This is used to seed the input for the new page's views.
Returns:
the new workbench org.eclipse.jface.window
Throws:
WorkbenchException - if a new org.eclipse.jface.window and page could not be opened
See Also:
showPerspective(String, IWorkbenchWindow, IAdaptable)

restart

public boolean restart()
Closes then restarts this workbench.

If the workbench has an open editor with unsaved content, the user will be given the opportunity to save it.

Returns:
true if the workbench was successfully closed, and false if it could not be closed
Since:
2.0

showPerspective

public IWorkbenchPage showPerspective(String perspectiveId,
                                      IWorkbenchWindow window)
                               throws WorkbenchException
Shows the specified perspective to the user. The caller should use this method when the perspective to be shown is not dependent on the page's input. That is, the perspective can open in any page depending on user preferences.

The perspective may be shown in the specified org.eclipse.jface.window, in another existing org.eclipse.jface.window, or in a new org.eclipse.jface.window depending on user preferences. The exact policy is controlled by the workbench to ensure consistency to the user. The policy is subject to change. The current policy is as follows:

The workbench also defines a number of menu items to activate or open each registered perspective. A complete list of these perspectives is available from the perspective registry found on IWorkbench.

Parameters:
perspectiveId - the perspective ID to show
Returns:
the workbench page that the perspective was shown
Throws:
WorkbenchException - if the perspective could not be shown
Since:
2.0

showPerspective

public IWorkbenchPage showPerspective(String perspectiveId,
                                      IWorkbenchWindow window,
                                      IAdaptable input)
                               throws WorkbenchException
Shows the specified perspective to the user. The caller should use this method when the perspective to be shown is dependent on the page's input. That is, the perspective can only open in any page with the specified input.

The perspective may be shown in the specified org.eclipse.jface.window, in another existing org.eclipse.jface.window, or in a new org.eclipse.jface.window depending on user preferences. The exact policy is controlled by the workbench to ensure consistency to the user. The policy is subject to change. The current policy is as follows:

The workbench also defines a number of menu items to activate or open each registered perspective. A complete list of these perspectives is available from the perspective registry found on IWorkbench.

Parameters:
perspectiveId - the perspective ID to show
input - the page input, or null if there is no current input. This is used to seed the input for the page's views
Returns:
the workbench page that the perspective was shown
Throws:
WorkbenchException - if the perspective could not be shown
Since:
2.0

getElementFactory

public IElementFactory getElementFactory(String factoryId)
Returns the element factory with the given id.

Parameters:
factoryId - the id of the element factory
Returns:
the elment factory, or null if none
Since:
3.0
See Also:
IElementFactory

getCommandSupport

public IWorkbenchCommandSupport getCommandSupport()
Deprecated. Please use getAdapter(ICommandService.class) instead.

Returns an interface to manage commands at the workbench level.

Returns:
an interface to manage commands at the workbench level. Guaranteed not to be null.
Since:
3.0
See Also:
ICommandService

isClosing

public boolean isClosing()
Returns a boolean indicating whether the workbench is in the process of closing.

Returns:
true if the workbench is in the process of closing, false otherwise
Since:
3.1

getExtensionTracker

public IExtensionTracker getExtensionTracker()

Return the extension tracker for the workbench. This tracker may be used by plug-ins to ensure responsiveness to changes to the plug-in registry.

The tracker at this level of the workbench is typically used to track elements that persist for the life of the workbench. For example, IEditorDescriptor objects fall into this category.

This method is EXPERIMENTAL and may change prior to the 3.1 release.

Returns:
the extension tracker
Since:
3.1
See Also:
IWorkbenchWindow.getExtensionTracker(), IWorkbenchPage.getExtensionTracker()

getViewRegistry

public IViewRegistry getViewRegistry()
Returns the editor registry for the workbench.

Returns:
the workbench editor registry
Since:
3.1

Eclipse eRCP
Release 1.1