Source code: org/eclipse/ui/PlatformUI.java
1 /*******************************************************************************
2 * Copyright (c) 2000, 2004 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v10.html
7 *
8 * Contributors:
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package org.eclipse.ui;
12
13 import org.eclipse.jface.preference.IPreferenceStore;
14 import org.eclipse.swt.widgets.Display;
15 import org.eclipse.ui.application.WorkbenchAdvisor;
16 import org.eclipse.ui.internal.Workbench;
17 import org.eclipse.ui.internal.WorkbenchMessages;
18 import org.eclipse.ui.internal.util.PrefUtil;
19 import org.eclipse.ui.testing.TestableObject;
20
21 /**
22 * The central class for access to the Eclipse Platform User Interface.
23 * This class cannot be instantiated; all functionality is provided by
24 * static methods.
25 *
26 * Features provided:
27 * <ul>
28 * <li>creation of the workbench.</li>
29 * <li>access to the workbench.</li>
30 * </ul>
31 * <p>
32 *
33 * @see IWorkbench
34 */
35 public final class PlatformUI {
36 /**
37 * Identifies the workbench plug-in.
38 */
39 public static final String PLUGIN_ID = "org.eclipse.ui"; //$NON-NLS-1$
40
41 /**
42 * Return code (value 0) indicating that the workbench terminated normally.
43 *
44 * @see #createAndRunWorkbench
45 * @since 3.0
46 */
47 public static final int RETURN_OK = 0;
48
49 /**
50 * Return code (value 1) indicating that the workbench was terminated with
51 * a call to <code>IWorkbench.restart</code>.
52 *
53 * @see #createAndRunWorkbench
54 * @see IWorkbench#restart
55 * @since 3.0
56 */
57 public static final int RETURN_RESTART = 1;
58
59 /**
60 * Return code (value 2) indicating that the workbench failed to start.
61 *
62 * @see #createAndRunWorkbench
63 * @see IWorkbench#restart
64 * @since 3.0
65 */
66 public static final int RETURN_UNSTARTABLE = 2;
67
68 /**
69 * Return code (value 3) indicating that the workbench was terminated with
70 * a call to IWorkbenchConfigurer#emergencyClose.
71 *
72 * @see #createAndRunWorkbench
73 * @since 3.0
74 */
75 public static final int RETURN_EMERGENCY_CLOSE = 3;
76
77 /**
78 * Block instantiation.
79 */
80 private PlatformUI() {
81 // do nothing
82 }
83
84 /**
85 * Returns the workbench. Fails if the workbench has not been created yet.
86 *
87 * @return the workbench
88 */
89 public static IWorkbench getWorkbench() {
90 if (Workbench.getInstance() == null) {
91 // app forgot to call createAndRunWorkbench beforehand
92 throw new IllegalStateException(WorkbenchMessages.getString("PlatformUI.NoWorkbench")); //$NON-NLS-1$
93 }
94 return Workbench.getInstance();
95 }
96
97 /**
98 * Returns whether {@link #createAndRunWorkbench createAndRunWorkbench} has been
99 * called to create the workbench, and the workbench has yet to terminate.
100 *
101 * @return <code>true</code> if the workbench has been created and is still
102 * running, and <code>false</code> if the workbench has not yet been created
103 * or has completed
104 * @since 3.0
105 */
106 public static boolean isWorkbenchRunning() {
107 return Workbench.getInstance() != null && Workbench.getInstance().isRunning();
108 }
109
110 /**
111 * Creates the workbench and associates it with the given display and workbench
112 * advisor, and runs the workbench UI. This entails processing and dispatching
113 * events until the workbench is closed or restarted.
114 * <p>
115 * This method is intended to be called by the main class (the "application").
116 * Fails if the workbench UI has already been created.
117 * </p>
118 * <p>
119 * Use {@link #createDisplay createDisplay} to create the display to pass in.
120 * </p>
121 * <p>
122 * Note that this method is intended to be called by the application
123 * (<code>org.eclipse.core.boot.IPlatformRunnable</code>). It must be
124 * called exactly once, and early on before anyone else asks
125 * <code>getWorkbench()</code> for the workbench.
126 * </p>
127 *
128 * @param display the display to be used for all UI interactions with the workbench
129 * @param advisor the application-specific advisor that configures and
130 * specializes the workbench
131 * @return return code {@link #RETURN_OK RETURN_OK} for normal exit;
132 * {@link #RETURN_RESTART RETURN_RESTART} if the workbench was terminated
133 * with a call to {@link IWorkbench#restart IWorkbench.restart};
134 * {@link #RETURN_UNSTARTABLE RETURN_UNSTARTABLE} if the workbench could
135 * not be started;
136 * {@link #RETURN_EMERGENCY_CLOSE RETURN_EMERGENCY_CLOSE} if the UI quit
137 * because of an emergency; other values reserved for future use
138 * @since 3.0
139 */
140 public static int createAndRunWorkbench(Display display, WorkbenchAdvisor advisor) {
141 return Workbench.createAndRunWorkbench(display, advisor);
142 }
143
144 /**
145 * Creates the <code>Display</code> to be used by the workbench.
146 * It is the caller's responsibility to dispose the resulting <code>Display</code>,
147 * not the workbench's.
148 *
149 * @return the display
150 * @since 3.0
151 */
152 public static Display createDisplay() {
153 return Workbench.createDisplay();
154 }
155
156 /**
157 * Returns the testable object facade, for use by the test harness.
158 * <p>
159 * IMPORTANT: This method is only for use by the test harness.
160 * Applications and regular plug-ins should not call this method.
161 * </p>
162 *
163 * @return the testable object facade
164 * @since 3.0
165 */
166 public static TestableObject getTestableObject() {
167 return Workbench.getWorkbenchTestable();
168 }
169
170 /**
171 * Returns the preference store used for publicly settable workbench preferences.
172 * Constants for these preferences are defined on
173 * {@link org.eclipse.ui.IWorkbenchPreferenceConstants}.
174 *
175 * @return the workbench public preference store
176 * @since 3.0
177 */
178 public static IPreferenceStore getPreferenceStore() {
179 return PrefUtil.getAPIPreferenceStore();
180 }
181 }