1 /*******************************************************************************

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

     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  *     Nokia Corporation - initial implementation

    10  *******************************************************************************/

    11 

    12 package org.eclipse.swt.internal.extension;

    13 

    14 import org.eclipse.swt.internal.qt.EventLoop;

    15 import org.eclipse.swt.widgets.Display;

    16 

    17 /**

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

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

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

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

    22  * <p>

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

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

    25  * used internally within the platform implementation. The application can 

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

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

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

    29  * by both the Displays. 

    30  * <p>

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

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

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

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

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

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

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

    38  * hasn't explicitly created the public Display instance. 

    39  * 

    40  * @see ApplicationUI

    41  */

    42 final public class Toolkit {

    43     

    44     private static Display internalDisplay;

    45 

    46     /**

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

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

    49      * the Display and must not dispose it. 

    50      * <p>

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

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

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

    54      * <p>

    55      * This method is thread safe. 

    56      * 

    57      * @return The internal Display instance

    58      * 

    59      * @throws RuntimeException

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

    61      *             obtained.

    62      */

    63     static public synchronized Display getInternalDisplay() {

    64         if(internalDisplay == null) {

    65             internalDisplay = EventLoop.getInternalDisplay();

    66         }

    67         return internalDisplay;

    68     }

    69 }