001: /*******************************************************************************
002: * Copyright (c) 2005, 2007 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.application;
011:
012: import org.eclipse.core.runtime.Assert;
013: import org.eclipse.core.runtime.IStatus;
014: import org.eclipse.core.runtime.Status;
015: import org.eclipse.swt.widgets.Composite;
016: import org.eclipse.swt.widgets.Control;
017: import org.eclipse.swt.widgets.Shell;
018: import org.eclipse.ui.IMemento;
019: import org.eclipse.ui.IWorkbenchPreferenceConstants;
020: import org.eclipse.ui.PlatformUI;
021: import org.eclipse.ui.WorkbenchException;
022: import org.eclipse.ui.actions.ActionFactory;
023: import org.eclipse.ui.internal.WorkbenchWindowConfigurer;
024: import org.eclipse.ui.internal.util.PrefUtil;
025: import org.eclipse.ui.intro.IIntroManager;
026:
027: /**
028: * Public base class for configuring a workbench window.
029: * <p>
030: * The workbench window advisor object is created in response to a workbench
031: * window being created (one per window), and is used to configure the window.
032: * </p>
033: * <p>
034: * An application should declare a subclass of <code>WorkbenchWindowAdvisor</code>
035: * and override methods to configure workbench windows to suit the needs of the
036: * particular application.
037: * </p>
038: * <p>
039: * The following advisor methods are called at strategic points in the
040: * workbench window's lifecycle (as with the workbench advisor, all occur
041: * within the dynamic scope of the call to
042: * {@link PlatformUI#createAndRunWorkbench PlatformUI.createAndRunWorkbench}):
043: * <ul>
044: * <li><code>preWindowOpen</code> - called as the window is being opened;
045: * use to configure aspects of the window other than actions bars</li>
046: * <li><code>postWindowRestore</code> - called after the window has been
047: * recreated from a previously saved state; use to adjust the restored
048: * window</li>
049: * <li><code>postWindowCreate</code> - called after the window has been created,
050: * either from an initial state or from a restored state; used to adjust the
051: * window</li>
052: * <li><code>openIntro</code> - called immediately before the window is opened in
053: * order to create the introduction component, if any.</li>
054: * <li><code>postWindowOpen</code> - called after the window has been
055: * opened; use to hook window listeners, etc.</li>
056: * <li><code>preWindowShellClose</code> - called when the window's shell
057: * is closed by the user; use to pre-screen window closings</li>
058: * </ul>
059: * </p>
060: *
061: * @since 3.1
062: */
063: public class WorkbenchWindowAdvisor {
064:
065: private IWorkbenchWindowConfigurer windowConfigurer;
066:
067: /**
068: * Creates a new workbench window advisor for configuring a workbench
069: * window via the given workbench window configurer.
070: *
071: * @param configurer an object for configuring the workbench window
072: */
073: public WorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer) {
074: Assert.isNotNull(configurer);
075: this .windowConfigurer = configurer;
076: }
077:
078: /**
079: * Returns the workbench window configurer.
080: *
081: * @return the workbench window configurer
082: */
083: protected IWorkbenchWindowConfigurer getWindowConfigurer() {
084: return windowConfigurer;
085: }
086:
087: /**
088: * Performs arbitrary actions before the window is opened.
089: * <p>
090: * This method is called before the window's controls have been created.
091: * Clients must not call this method directly (although super calls are okay).
092: * The default implementation does nothing. Subclasses may override.
093: * Typical clients will use the window configurer to tweak the
094: * workbench window in an application-specific way; however, filling the
095: * window's menu bar, tool bar, and status line must be done in
096: * {@link ActionBarAdvisor#fillActionBars}, which is called immediately
097: * after this method is called.
098: * </p>
099: */
100: public void preWindowOpen() {
101: // do nothing
102: }
103:
104: /**
105: * Creates a new action bar advisor to configure the action bars of the window
106: * via the given action bar configurer.
107: * The default implementation returns a new instance of {@link ActionBarAdvisor}.
108: *
109: * @param configurer the action bar configurer for the window
110: * @return the action bar advisor for the window
111: */
112: public ActionBarAdvisor createActionBarAdvisor(
113: IActionBarConfigurer configurer) {
114: return new ActionBarAdvisor(configurer);
115: }
116:
117: /**
118: * Performs arbitrary actions after the window has been restored,
119: * but before it is opened.
120: * <p>
121: * This method is called after a previously-saved window has been
122: * recreated. This method is not called when a new window is created from
123: * scratch. This method is never called when a workbench is started for the
124: * very first time, or when workbench state is not saved or restored.
125: * Clients must not call this method directly (although super calls are okay).
126: * The default implementation does nothing. Subclasses may override.
127: * It is okay to call <code>IWorkbench.close()</code> from this method.
128: * </p>
129: *
130: * @exception WorkbenchException thrown if there are any errors to report
131: * from post-restoration of the window
132: */
133: public void postWindowRestore() throws WorkbenchException {
134: // do nothing
135: }
136:
137: /**
138: * Opens the introduction componenet.
139: * <p>
140: * Clients must not call this method directly (although super calls are okay).
141: * The default implementation opens the intro in the first window provided
142: * if the preference IWorkbenchPreferences.SHOW_INTRO is <code>true</code>. If
143: * an intro is shown then this preference will be set to <code>false</code>.
144: * Subsequently, and intro will be shown only if
145: * <code>WorkbenchConfigurer.getSaveAndRestore()</code> returns
146: * <code>true</code> and the introduction was visible on last shutdown.
147: * Subclasses may override.
148: * </p>
149: */
150: public void openIntro() {
151: // TODO: Refactor this into an IIntroManager.openIntro(IWorkbenchWindow) call
152:
153: // introOpened flag needs to be global
154: IWorkbenchConfigurer wbConfig = getWindowConfigurer()
155: .getWorkbenchConfigurer();
156: final String key = "introOpened"; //$NON-NLS-1$
157: Boolean introOpened = (Boolean) wbConfig.getData(key);
158: if (introOpened != null && introOpened.booleanValue()) {
159: return;
160: }
161:
162: wbConfig.setData(key, Boolean.TRUE);
163:
164: boolean showIntro = PrefUtil.getAPIPreferenceStore()
165: .getBoolean(IWorkbenchPreferenceConstants.SHOW_INTRO);
166:
167: IIntroManager introManager = wbConfig.getWorkbench()
168: .getIntroManager();
169:
170: boolean hasIntro = introManager.hasIntro();
171: boolean isNewIntroContentAvailable = introManager
172: .isNewContentAvailable();
173:
174: if (hasIntro && (showIntro || isNewIntroContentAvailable)) {
175: introManager.showIntro(getWindowConfigurer().getWindow(),
176: false);
177:
178: PrefUtil.getAPIPreferenceStore().setValue(
179: IWorkbenchPreferenceConstants.SHOW_INTRO, false);
180: PrefUtil.saveAPIPrefs();
181: }
182: }
183:
184: /**
185: * Performs arbitrary actions after the window has been created (possibly
186: * after being restored), but has not yet been opened.
187: * <p>
188: * This method is called after the window has been created from scratch,
189: * or when it has been restored from a previously-saved window. In the latter case,
190: * this method is called after <code>postWindowRestore</code>.
191: * Clients must not call this method directly (although super calls are okay).
192: * The default implementation does nothing. Subclasses may override.
193: * </p>
194: */
195: public void postWindowCreate() {
196: // do nothing
197: }
198:
199: /**
200: * Performs arbitrary actions after the window has been opened (possibly
201: * after being restored).
202: * <p>
203: * This method is called after the window has been opened. This method is
204: * called after the window has been created from scratch, or when
205: * it has been restored from a previously-saved window.
206: * Clients must not call this method directly (although super calls are okay).
207: * The default implementation does nothing. Subclasses may override.
208: * </p>
209: */
210: public void postWindowOpen() {
211: // do nothing
212: }
213:
214: /**
215: * Performs arbitrary actions as the window's shell is being closed
216: * directly, and possibly veto the close.
217: * <p>
218: * This method is called from a ShellListener associated with the window,
219: * for example when the user clicks the window's close button. It is not
220: * called when the window is being closed for other reasons, such as if the
221: * user exits the workbench via the {@link ActionFactory#QUIT} action.
222: * Clients must not call this method directly (although super calls are
223: * okay). If this method returns <code>false</code>, then the user's
224: * request to close the shell is ignored. This gives the workbench advisor
225: * an opportunity to query the user and/or veto the closing of a window
226: * under some circumstances.
227: * </p>
228: *
229: * @return <code>true</code> to allow the window to close, and
230: * <code>false</code> to prevent the window from closing
231: * @see org.eclipse.ui.IWorkbenchWindow#close
232: * @see WorkbenchAdvisor#preShutdown()
233: */
234: public boolean preWindowShellClose() {
235: // do nothing, but allow the close() to proceed
236: return true;
237: }
238:
239: /**
240: * Performs arbitrary actions after the window is closed.
241: * <p>
242: * This method is called after the window's controls have been disposed.
243: * Clients must not call this method directly (although super calls are
244: * okay). The default implementation does nothing. Subclasses may override.
245: * </p>
246: */
247: public void postWindowClose() {
248: // do nothing
249: }
250:
251: /**
252: * Creates the contents of the window.
253: * <p>
254: * The default implementation adds a menu bar, a cool bar, a status line,
255: * a perspective bar, and a fast view bar. The visibility of these controls
256: * can be configured using the <code>setShow*</code> methods on
257: * <code>IWorkbenchWindowConfigurer</code>.
258: * </p>
259: * <p>
260: * Subclasses may override to define custom window contents and layout,
261: * but must call <code>IWorkbenchWindowConfigurer.createPageComposite</code>.
262: * </p>
263: *
264: * @param shell the window's shell
265: * @see IWorkbenchWindowConfigurer#createMenuBar
266: * @see IWorkbenchWindowConfigurer#createCoolBarControl
267: * @see IWorkbenchWindowConfigurer#createStatusLineControl
268: * @see IWorkbenchWindowConfigurer#createPageComposite
269: */
270: public void createWindowContents(Shell shell) {
271: ((WorkbenchWindowConfigurer) getWindowConfigurer())
272: .createDefaultContents(shell);
273: }
274:
275: /**
276: * Creates and returns the control to be shown when the window has no open pages.
277: * If <code>null</code> is returned, the default window background is shown.
278: * <p>
279: * The default implementation returns <code>null</code>.
280: * Subclasses may override.
281: * </p>
282: *
283: * @param parent the parent composite
284: * @return the control or <code>null</code>
285: */
286: public Control createEmptyWindowContents(Composite parent) {
287: return null;
288: }
289:
290: /**
291: * Disposes any resources allocated by this window advisor.
292: * This is the last method called on this window advisor by the workbench.
293: * The default implementation does nothing.
294: * Subclasses may extend.
295: */
296: public void dispose() {
297: // do nothing.
298: }
299:
300: /**
301: * Saves arbitrary application specific state information.
302: *
303: * @param memento the storage area for object's state
304: * @return a status object indicating whether the save was successful
305: * @since 3.1
306: */
307: public IStatus saveState(IMemento memento) {
308: // do nothing
309: return Status.OK_STATUS;
310: }
311:
312: /**
313: * Restores arbitrary application specific state information.
314: *
315: * @param memento the storage area for object's state
316: * @return a status object indicating whether the restore was successful
317: * @since 3.1
318: */
319: public IStatus restoreState(IMemento memento) {
320: // do nothing
321: return Status.OK_STATUS;
322: }
323: }
|