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

 * 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.EventLoop;

import org.eclipse.swt.widgets.Display;

/**

 * This class enables eSWT UI services to be used independently of the 

 * application's UI life-cycle in the implementation of the APIs. I.e. without 

 * having to know if the application has created a UI toolkit yet, if it has 

 * already destroyed it, or if it will ever create it. 

 * <p>

 * This is achieved by creating an 'internal' instance of the eSWT Display 

 * class. I.e. an instance that is not revealed to the application but is only 

 * used internally within the platform implementation. The application can 

 * create the actual 'public' Display instance. Thus there can be two Display 

 * objects but there's always only one set of UI resources such as  the native 

 * application, UI thread, native widgets, etc. These same resources are used 

 * by both the Displays. 

 * <p>

 * The users of the internal Display instance must take into account that 

 * the public eSWT APIs can never provide references to the internal Display 

 * instance. This has the implication that any other means of obtaining 

 * the Display besides the methods of this class will always use a reference 

 * to the public Display instance or null if it doesn't exist. E.g. 

 * Display.getCurrent() or Display.getDefault() can't be used to obtain the 

 * internal Display instance because they will return null if the application 

 * hasn't explicitly created the public Display instance. 

 * 

 * @see ApplicationUI

 */

final public class Toolkit {

    private static Display internalDisplay;

    /**

     * Returns an object reference to the internal Display instance. There's 

     * only one internal Display object in the process. The caller does not own 

     * the Display and must not dispose it. 

     * <p>

     * The returned Display shares the UI resources in the process with the

     * possibly existing public Display instance owned by the application. The

     * UI thread and the event loop maybe under control of the application.

     * <p>

     * This method is thread safe. 

     * 

     * @return The internal Display instance

     * 

     * @throws RuntimeException

     *             If the UI creation has failed and the Display can't be

     *             obtained.

     */

    static public synchronized Display getInternalDisplay() {

        if(internalDisplay == null) {

            internalDisplay = EventLoop.getInternalDisplay();

        }

        return internalDisplay;

    }

}