/*******************************************************************************

 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

 * 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:

 *     Nokia Corporation - initial implementation

 *******************************************************************************/

package org.eclipse.swt.internal.extension;

import org.eclipse.swt.internal.qt.midp.UIThreadLauncher;

import org.eclipse.swt.widgets.Display;

import org.eclipse.swt.widgets.Internal_PackageSupport;

/**

 * A class that encapsulates services that enable the use of eSWT UI before the

 * application has initialized its UI. This is achieved by utilizing an

 * 'internal' instance of the Display class. I.e. an instance that is not

 * revealed to the application but is only used internally within the API

 * implementation.

 * 

 * The same rules apply to the internal Display instance that apply to the

 * Display normally. When the Display is created then the creating thread

 * becomes the UI thread of the process. The application needs to be able to

 * obtain control of the UI thread. The services for interfacing with the

 * application are provided by the class ApplicationUI.

 * 

 * @see ApplicationUI

 */

public final class InternalUI {

	/**

	 * Obtains the platform specific UI thread where SWT UI APIs can be accessed

	 * in and calls the provided Runnable in it. This method instantly returns

	 * leaving two threads running concurrently: the calling thread and the UI

	 * thread. Only one UI thread can exist per process and this method can be

	 * called only once to obtain it. Subsequent calls will result in an

	 * exception being thrown. This method can be called by any thread.

	 * 

	 * @param runnable

	 *            A Runnable to call back in the UI thread.

	 * @exception RuntimeException

	 *                If starting the UI thread fails

	 */

	public static void startInUIThread(Runnable runnable) {

		if(!UIThreadLauncher.startInUIThread(runnable)) {

			throw new RuntimeException("Failed to start the UI thread");

		}

	}

	/**

	 * Creates the internal instance of Display. Must be called only once.

	 * 

	 * This means that the native resources required by the eSWT UI will be

	 * initialized and a Display instance is returned that can be used to access

	 * them normally via the public eSWT APIs. 

	 * 

	 * @return The internal Display instance

	 * @see getInternalDisplayInstance

	 */

	public synchronized static Display createInternalDisplay() {

		if(getInternalDisplayInstance() != null) {

			throw new RuntimeException("Display already exists");

		}

		return Internal_PackageSupport.internalInstance();

	}

	/**

	 * Returns the internal Display instance or null if it doesn't exist. 

	 * @return The internal Display instance or null

	 */

	public synchronized static Display getInternalDisplayInstance() {

		return Internal_PackageSupport.getInternalDisplayInstance();

	}

}