Package org.eclipse.ui

# Class PlatformUI

java.lang.Object
org.eclipse.ui.PlatformUI

public final class PlatformUI extends Object
The central class for access to the Eclipse Platform User Interface. This class cannot be instantiated; all functionality is provided by static methods. Features provided:

- creation of the workbench.
- access to the workbench.

See Also:
  - `IWorkbench`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Supplier<RuntimeException>`
`NO_WORKBENCH`
A supplier that supplies an `IllegalStateException` that a Workbench is not running.
`static final String`
`PLUGIN_ID`
Identifies the workbench plug-in.
`static final int`
`RETURN_EMERGENCY_CLOSE`
Return code (value 3) indicating that the workbench was terminated with a call to IWorkbenchConfigurer#emergencyClose.
`static final int`
`RETURN_OK`
Return code (value 0) indicating that the workbench terminated normally.
`static final int`
`RETURN_RESTART`
Return code (value 1) indicating that the workbench was terminated with a call to `IWorkbench.restart`.
`static final int`
`RETURN_UNSTARTABLE`
Return code (value 2) indicating that the workbench failed to start.

## Method Summary

Modifier and Type
Method
Description
`static int`
`createAndRunWorkbench(Display display, WorkbenchAdvisor advisor)`
Creates the workbench and associates it with the given display and workbench advisor, and runs the workbench UI.
`static Display`
`createDisplay()`
Creates the `Display` to be used by the workbench.
`static IPreferenceStore`
`createPreferenceStore(Class<?> clazz)`
Creates a `IPreferenceStore` store for the bundle that loaded that class
`static Optional<MApplication>`
`getApplication()`
This methods allows code of eclipse.ui to gracefully migrate to E4 as it has the following properties: It does not throw an exception but returns an empty optional if something is not ready (yet or anymore) so code can choose how to handle this (e.g. use `Optional.orElseThrow()` if required or `Optional.orElse(Object)` if a fallback exits. If this is is actually a (ui) Workbench running, this is returned and could be used If not the service registry is searched for an org.eclipse.e4.ui.workbench.IWorkbench so code can run inside a pure E4 (e.g.
`static IDialogSettingsProvider`
`getDialogSettingsProvider(Bundle bundle)`
Returns the dialog settings provider for the passed bundle.
`static IPreferenceStore`
`getPreferenceStore()`
Returns the preference store used for publicly settable workbench preferences.
`static TestableObject`
`getTestableObject()`
Returns the testable object facade, for use by the test harness.
`static IWorkbench`
`getWorkbench()`
Returns the workbench.
`static boolean`
`isWorkbenchRunning()`
Returns whether `createAndRunWorkbench` has been called to create the workbench, and the workbench has yet to terminate.
`static void`
`setHelp(Composite control, String helpContextId)`
Sets the given help id on the given control in a way that works both for E3/E4 applications

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### PLUGIN_ID

public static final String PLUGIN_ID
Identifies the workbench plug-in.

See Also:
  - Constant Field Values

### RETURN_OK

public static final int RETURN_OK
Return code (value 0) indicating that the workbench terminated normally.

Since:
  3.0
See Also:
  - `createAndRunWorkbench(org.eclipse.swt.widgets.Display, org.eclipse.ui.application.WorkbenchAdvisor)`
  - Constant Field Values

### RETURN_RESTART

public static final int RETURN_RESTART
Return code (value 1) indicating that the workbench was terminated with a call to `IWorkbench.restart`.

Since:
  3.0
See Also:
  - `createAndRunWorkbench(org.eclipse.swt.widgets.Display, org.eclipse.ui.application.WorkbenchAdvisor)`
  - `IWorkbench.restart()`
  - Constant Field Values

### RETURN_UNSTARTABLE

public static final int RETURN_UNSTARTABLE
Return code (value 2) indicating that the workbench failed to start.

Since:
  3.0
See Also:
  - `createAndRunWorkbench(org.eclipse.swt.widgets.Display, org.eclipse.ui.application.WorkbenchAdvisor)`
  - `IWorkbench.restart()`
  - Constant Field Values

### RETURN_EMERGENCY_CLOSE

public static final int RETURN_EMERGENCY_CLOSE
Return code (value 3) indicating that the workbench was terminated with a call to IWorkbenchConfigurer#emergencyClose.

Since:
  3.0
See Also:
  - `createAndRunWorkbench(org.eclipse.swt.widgets.Display, org.eclipse.ui.application.WorkbenchAdvisor)`
  - Constant Field Values

### NO_WORKBENCH

public static final Supplier<RuntimeException> NO_WORKBENCH
A supplier that supplies an `IllegalStateException` that a Workbench is not running.

Since:
  3.126

## Method Details

### getWorkbench

public static IWorkbench getWorkbench()
Returns the workbench. Fails if the workbench has not been created yet.

Returns:
  the workbench

### isWorkbenchRunning

public static boolean isWorkbenchRunning()
Returns whether `createAndRunWorkbench` has been called to create the workbench, and the workbench has yet to terminate.

Note that this method may return `true` while the workbench is still being initialized, so it may not be safe to call workbench API methods even if this method returns true. See bug 49316 for details.

Returns:
  `true` if the workbench has been created and is still running, and `false` if the workbench has not yet been created or has completed
Since:
  3.0

### createAndRunWorkbench

public static int createAndRunWorkbench(Display display, WorkbenchAdvisor advisor)
Creates the workbench and associates it with the given display and workbench advisor, and runs the workbench UI. This entails processing and dispatching events until the workbench is closed or restarted.

This method is intended to be called by the main class (the "application"). Fails if the workbench UI has already been created.

Use `createDisplay` to create the display to pass in.

Note that this method is intended to be called by the application. It must be called exactly once, and early on before anyone else asks `getWorkbench()` for the workbench.

Parameters:
  `display` - the display to be used for all UI interactions with the workbench
  `advisor` - the application-specific advisor that configures and specializes the workbench
Returns:
  return code `RETURN_OK` for normal exit; `RETURN_RESTART` if the workbench was terminated with a call to `IWorkbench.restart`; `RETURN_UNSTARTABLE` if the workbench could not be started; `RETURN_EMERGENCY_CLOSE` if the UI quit because of an emergency; other values reserved for future use
Since:
  3.0

### createDisplay

public static Display createDisplay()
Creates the `Display` to be used by the workbench. It is the caller's responsibility to dispose the resulting `Display`, not the workbench's.

Returns:
  the display
Since:
  3.0

### getTestableObject

public static TestableObject getTestableObject()
Returns the testable object facade, for use by the test harness.

IMPORTANT: This method is only for use by the test harness. Applications and regular plug-ins should not call this method.

To avoid depending on the the Workbench a `TestableObject` can be obtained via OSGi service.

Returns:
  the testable object facade
Since:
  3.0

### getPreferenceStore

public static IPreferenceStore getPreferenceStore()
Returns the preference store used for publicly settable workbench preferences. Constants for these preferences are defined on `IWorkbenchPreferenceConstants`.

Returns:
  the workbench public preference store
Since:
  3.0

### getDialogSettingsProvider

public static IDialogSettingsProvider getDialogSettingsProvider(Bundle bundle)
Returns the dialog settings provider for the passed bundle. The dialog settings is used to hold persistent state data for the various wizards and dialogs of the bundle in the context of a workbench.

If an error occurs reading the dialog store, an empty one is quietly created and returned (errors are logged).

Parameters:
  `bundle` - the bundle for which the dialog settings are to be returned
Returns:
  the dialog settings provider
Since:
  3.122

### createPreferenceStore

public static IPreferenceStore createPreferenceStore(Class<?> clazz)
Creates a `IPreferenceStore` store for the bundle that loaded that class

Parameters:
  `clazz` - the class to use for determining the responsible bundle
Returns:
  the instance scoped preference store for the given class
Since:
  3.117

### getApplication

public static Optional<MApplication> getApplication()
This methods allows code of eclipse.ui to gracefully migrate to E4 as it has the following properties:

1. It does not throw an exception but returns an empty optional if something is not ready (yet or anymore) so code can choose how to handle this (e.g. use `Optional.orElseThrow()` if required or `Optional.orElse(Object)` if a fallback exits.
2. If this is is actually a (ui) Workbench running, this is returned and could be used
3. If not the service registry is searched for an org.eclipse.e4.ui.workbench.IWorkbench so code can run inside a pure E4 (e.g. RCP) application as well.
4. With the Application at hand, it is possible to get access to the `IEclipseContext` (see `MContext.getContext()` to further interact with the plain E4 Application Model.

The following example fails if run inside an E4 Application:

`PlatformUI.getWorkbench().getExtensionTracker()`

and could be rewritten as:

`PlatformUI.getApplication().map(MApplication::getContext).map(ctx -> ctx.get(IExtensionTracker.class)).orElseThrow(PlatformUI.NO_WORKBENCH);`

Returns:
  a reference to the `MApplication` running the Workbench or an empty optional if currently no Workbench is available.
Since:
  3.126

### setHelp

public static void setHelp(Composite control, String helpContextId)
Sets the given help id on the given control in a way that works both for E3/E4 applications

Parameters:
  `control` - the control on which to register the id
  `helpContextId` - the id to use when F1 help is invoked
Since:
  3.131