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

     2  * Copyright (c) 2009, 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 package org.eclipse.ercp.swt.midp;

    12 

    13 import org.eclipse.swt.SWT;

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

    15 

    16 /**

    17  * <p>

    18  * To use eSWT API a MIDlet needs to dedicate a thread as the UI thread for

    19  * running the event loop. This can't happen in the MIDlet.startApp() because

    20  * it's required by the MIDP specification that the call to startApp() returns

    21  * quickly. Additionally, many native UI toolkits have restrictions for the

    22  * thread that can be used as the UI thread. Thus, a random Java thread can't be

    23  * used either.

    24  * </p>

    25  * <p>

    26  * This class provides means to obtain a thread that can be used as the UI

    27  * thread on the platform. All MIDlets must use this class to obtain the UI

    28  * thread. If a MIDlet uses some other thread as the UI thread then the behavior

    29  * is undefined.

    30  * </p>

    31  * 

    32  * @see MIDlet

    33  * @see MIDlet#startApp

    34  */

    35 public class UIThreadSupport {

    36 

    37 private static boolean started;

    38 

    39 /**

    40  * <p>

    41  * Calls back the given Runnable in a thread that can be used as the UI thread.

    42  * The method must not be called more than once as there might be only one

    43  * thread in the process capable of being used as the UI thread.

    44  * </p>

    45  * 

    46  * An example: <code><pre>

    47  * ...

    48  * class MyMIDlet extends javax.microedition.midlet.MIDlet {

    49  *     ...

    50  *     public void startApp() {

    51  *         UIThreadSupport.startInUIThread(new Runnable() {

    52  *             public void run() {

    53  *                 Display display = new Display();

    54  *                 ...

    55  *             }

    56  *          });

    57  *     }

    58  *     ...

    59  * }

    60  * </pre></code>

    61  * 

    62  * @param runnable The Runnable object to call back

    63  * @exception SWTError <ul>

    64  *                <li>ERROR_NULL_ARGUMENT if the runnable is null</li>

    65  * @exception SWTError <ul>

    66  *                <li>ERROR_NO_HANDLES if a handle could not be obtained for

    67  *                thread creation</li>

    68  * @exception SWTError <ul>

    69  *                <li>ERROR_FAILED_EXEC if called more than once</li>

    70  * @see MIDlet

    71  * @see MIDlet#startApp

    72  */

    73 public static void startInUIThread(Runnable runnable) {

    74 	if(runnable == null) {

    75 		SWT.error(SWT.ERROR_NULL_ARGUMENT);

    76 	}

    77     synchronized(UIThreadSupport.class) {

    78         if(started) {

    79             SWT.error(SWT.ERROR_FAILED_EXEC);

    80         }

    81         started = true;

    82     }

    83     if(!UIThreadManager.startInUIThread(runnable)) {

    84         SWT.error(SWT.ERROR_NO_HANDLES);

    85     }

    86 }

    87 

    88 }