bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/splash/AbstractSplashHandler.java

/*******************************************************************************
 * Copyright (c) 2007 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.ui.splash;

import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.NullProgressMonitor;
import org.eclipse.swt.widgets.Shell;
import org.eclipse.ui.IWorkbench;
import org.eclipse.ui.IWorkbenchPreferenceConstants;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.application.WorkbenchAdvisor;

/**
 * Baseclass for splash implementations. Please note that methods on this class
 * will be invoked while the Workbench is being instantiated. As such, any
 * resource provided by the workbench plug-in cannot be guarenteed to be
 * available to this class while executing. No attempt should be made to access
 * {@link IWorkbench} or any subordinate interfaces or resources.
 * 
 * @since 3.3
 */
public abstract class AbstractSplashHandler {

	private Shell shell;

	/**
	 * Initialize this splash implementation. This is called very early in the
	 * workbench lifecycle before any window is created. The provided shell will
	 * already have a background image provided to it but subclasses are free to
	 * customize the shell in whatever way they see fit. Subclasses should
	 * ensure that they call the base implementation of this method at some
	 * point after their own method is invoked.
	 * 
	 * <p>
	 * Calls to this method will be made from the UI thread.
	 * </p>
	 * 
	 * @param splash
	 *            the splash shell
	 */
	public void init(Shell splash) {
		this.shell = splash;
	}

	/**
	 * Signal the handler to end the splash and dispose of any resources.
	 * Subclasses should ensure that they call the base implementation of this
	 * method at some point after their own method is invoked.
	 * 
	 * <p>
	 * Calls to this method will be made from the UI thread.
	 * </p>
	 */
	public void dispose() {
		shell.close();
		shell = null;
	}

	/**
	 * Return the progress monitor responsible for showing bundle loading.
	 * Default implementation returns a null progress monitor.
	 * 
	 * <p>
	 * Calls made to methods on this progress monitor may be made from non-UI
	 * threads so implementors must take care to ensure proper synchronization
	 * with the UI thread if necessary.
	 * </p>
	 * 
	 * <p>
	 * Please note that progress will only be shown if the
	 * "org.eclipse.ui/SHOW_PROGRESS_ON_STARTUP" property has been set to
	 * <code>true</code>. Because this property defaults to <code>false</code>
	 * RCP developers must set this property via a
	 * <code>plugin_customization.ini</code> file or by setting the preference
	 * on the Platform UI perference store in the
	 * {@link WorkbenchAdvisor#initialize(org.eclipse.ui.application.IWorkbenchConfigurer)}
	 * method if they wish to have progress reported on startup.
	 * </p>
	 * 
	 * @return the progress monitor
	 * @see NullProgressMonitor
	 * @see PlatformUI#getPreferenceStore()
	 * @see IWorkbenchPreferenceConstants#SHOW_PROGRESS_ON_STARTUP
	 * @see WorkbenchAdvisor#initialize(org.eclipse.ui.application.IWorkbenchConfigurer)
	 */
	public IProgressMonitor getBundleProgressMonitor() {
		return new NullProgressMonitor();
	}

	/**
	 * Get the {@link Shell} associated with this splash screen. If this method
	 * returns a non-<code>null</code> value prior to the
	 * {@link #init(Shell)} being invoked then this shell will be used for the
	 * splash shell and it will subsequently be passed to the
	 * {@link #init(Shell)} method. In this way a splash handler may participate
	 * in splash processes prior to the workbench startup.
	 * 
	 * <p>
	 * Calls to this method may be made from any thread. Implementors must take
	 * care to ensure proper synchronization with the UI thread if necessary.
	 * </p>
	 * 
	 * @return the splash shell
	 */
	public Shell getSplash() {
		return shell;
	}
}