KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > PlatformUI


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-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 JavaDoc 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 JavaDoc(WorkbenchMessages.PlatformUI_NoWorkbench);
93         }
94         return Workbench.getInstance();
95     }
96
97     /**
98      * Returns whether {@link #createAndRunWorkbench createAndRunWorkbench} has
99      * 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 }
190
Popular Tags