001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui;
011:
012: import org.eclipse.jface.preference.IPreferenceStore;
013: import org.eclipse.swt.widgets.Display;
014: import org.eclipse.ui.application.WorkbenchAdvisor;
015: import org.eclipse.ui.internal.Workbench;
016: import org.eclipse.ui.internal.WorkbenchMessages;
017: import org.eclipse.ui.internal.util.PrefUtil;
018: import org.eclipse.ui.testing.TestableObject;
019:
020: /**
021: * The central class for access to the Eclipse Platform User Interface.
022: * This class cannot be instantiated; all functionality is provided by
023: * static methods.
024: *
025: * Features provided:
026: * <ul>
027: * <li>creation of the workbench.</li>
028: * <li>access to the workbench.</li>
029: * </ul>
030: * <p>
031: *
032: * @see IWorkbench
033: */
034: public final class PlatformUI {
035: /**
036: * Identifies the workbench plug-in.
037: */
038: public static final String PLUGIN_ID = "org.eclipse.ui"; //$NON-NLS-1$
039:
040: /**
041: * Return code (value 0) indicating that the workbench terminated normally.
042: *
043: * @see #createAndRunWorkbench
044: * @since 3.0
045: */
046: public static final int RETURN_OK = 0;
047:
048: /**
049: * Return code (value 1) indicating that the workbench was terminated with
050: * a call to <code>IWorkbench.restart</code>.
051: *
052: * @see #createAndRunWorkbench
053: * @see IWorkbench#restart
054: * @since 3.0
055: */
056: public static final int RETURN_RESTART = 1;
057:
058: /**
059: * Return code (value 2) indicating that the workbench failed to start.
060: *
061: * @see #createAndRunWorkbench
062: * @see IWorkbench#restart
063: * @since 3.0
064: */
065: public static final int RETURN_UNSTARTABLE = 2;
066:
067: /**
068: * Return code (value 3) indicating that the workbench was terminated with
069: * a call to IWorkbenchConfigurer#emergencyClose.
070: *
071: * @see #createAndRunWorkbench
072: * @since 3.0
073: */
074: public static final int RETURN_EMERGENCY_CLOSE = 3;
075:
076: /**
077: * Block instantiation.
078: */
079: private PlatformUI() {
080: // do nothing
081: }
082:
083: /**
084: * Returns the workbench. Fails if the workbench has not been created yet.
085: *
086: * @return the workbench
087: */
088: public static IWorkbench getWorkbench() {
089: if (Workbench.getInstance() == null) {
090: // app forgot to call createAndRunWorkbench beforehand
091: throw new IllegalStateException(
092: WorkbenchMessages.PlatformUI_NoWorkbench);
093: }
094: return Workbench.getInstance();
095: }
096:
097: /**
098: * Returns whether {@link #createAndRunWorkbench createAndRunWorkbench} has
099: * been called to create the workbench, and the workbench has yet to
100: * terminate.
101: * <p>
102: * Note that this method may return <code>true</code> while the workbench
103: * is still being initialized, so it may not be safe to call workbench API
104: * methods even if this method returns true. See bug 49316 for details.
105: * </p>
106: *
107: * @return <code>true</code> if the workbench has been created and is
108: * still running, and <code>false</code> if the workbench has not
109: * yet been created or has completed
110: * @since 3.0
111: */
112: public static boolean isWorkbenchRunning() {
113: return Workbench.getInstance() != null
114: && Workbench.getInstance().isRunning();
115: }
116:
117: /**
118: * Creates the workbench and associates it with the given display and workbench
119: * advisor, and runs the workbench UI. This entails processing and dispatching
120: * events until the workbench is closed or restarted.
121: * <p>
122: * This method is intended to be called by the main class (the "application").
123: * Fails if the workbench UI has already been created.
124: * </p>
125: * <p>
126: * Use {@link #createDisplay createDisplay} to create the display to pass in.
127: * </p>
128: * <p>
129: * Note that this method is intended to be called by the application
130: * (<code>org.eclipse.core.boot.IPlatformRunnable</code>). It must be
131: * called exactly once, and early on before anyone else asks
132: * <code>getWorkbench()</code> for the workbench.
133: * </p>
134: *
135: * @param display the display to be used for all UI interactions with the workbench
136: * @param advisor the application-specific advisor that configures and
137: * specializes the workbench
138: * @return return code {@link #RETURN_OK RETURN_OK} for normal exit;
139: * {@link #RETURN_RESTART RETURN_RESTART} if the workbench was terminated
140: * with a call to {@link IWorkbench#restart IWorkbench.restart};
141: * {@link #RETURN_UNSTARTABLE RETURN_UNSTARTABLE} if the workbench could
142: * not be started;
143: * {@link #RETURN_EMERGENCY_CLOSE RETURN_EMERGENCY_CLOSE} if the UI quit
144: * because of an emergency; other values reserved for future use
145: * @since 3.0
146: */
147: public static int createAndRunWorkbench(Display display,
148: WorkbenchAdvisor advisor) {
149: return Workbench.createAndRunWorkbench(display, advisor);
150: }
151:
152: /**
153: * Creates the <code>Display</code> to be used by the workbench.
154: * It is the caller's responsibility to dispose the resulting <code>Display</code>,
155: * not the workbench's.
156: *
157: * @return the display
158: * @since 3.0
159: */
160: public static Display createDisplay() {
161: return Workbench.createDisplay();
162: }
163:
164: /**
165: * Returns the testable object facade, for use by the test harness.
166: * <p>
167: * IMPORTANT: This method is only for use by the test harness.
168: * Applications and regular plug-ins should not call this method.
169: * </p>
170: *
171: * @return the testable object facade
172: * @since 3.0
173: */
174: public static TestableObject getTestableObject() {
175: return Workbench.getWorkbenchTestable();
176: }
177:
178: /**
179: * Returns the preference store used for publicly settable workbench preferences.
180: * Constants for these preferences are defined on
181: * {@link org.eclipse.ui.IWorkbenchPreferenceConstants}.
182: *
183: * @return the workbench public preference store
184: * @since 3.0
185: */
186: public static IPreferenceStore getPreferenceStore() {
187: return PrefUtil.getAPIPreferenceStore();
188: }
189: }
|