1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 package javax.microedition.lcdui;

    19 

    20 import org.eclipse.swt.widgets.Widget;

    21 

    22 

    23 /*

    24  * Event dispatcher singleton class. Takes care of dispatching the UI callbacks

    25  * to the MIDlet in a dedicated dispatcher thread. Owns and encapsulates an

    26  * event queue of callback events.

    27  */

    28 final class EventDispatcher

    29 {

    30 

    31     private static EventDispatcher singleton;

    32     private static EventQueue eventQueue;

    33     private static Thread dispatcherThread;

    34     private static boolean terminated;

    35     private static Object wakeLock;

    36     private static Object callbackLock;

    37     private static boolean pendingWake;

    38     private static Runnable terminatedNotification;

    39     private final static String logName = "LCDUI event dispatcher: ";

    40 

    41     /*

    42      * LCDUI-internal event class for callback events.

    43      */

    44     static final class LCDUIEvent

    45     {

    46         /*

    47          * High bits of the event event type identifier are used to group the

    48          * events that are handled the same way in the Event Dispatcher.

    49          */

    50         static final int CANVASBIT = 0x80000000;

    51         static final int CUSTOMITEMBIT = 0x40000000;

    52         static final int DISPLAYABLEBIT = 0x20000000;

    53         static final int EVENTTYPEMASK = CANVASBIT|CUSTOMITEMBIT|DISPLAYABLEBIT;

    54 

    55         /*

    56          * Event type identifiers.

    57          */

    58         static final int CANVAS_HIDENOTIFY = 1|CANVASBIT;

    59         static final int CANVAS_KEYPRESSED = 2|CANVASBIT;

    60         static final int CANVAS_KEYREPEATED = 3|CANVASBIT;

    61         static final int CANVAS_KEYRELEASED = 4|CANVASBIT;

    62         static final int CANVAS_PAINT_NATIVE_REQUEST = 5|CANVASBIT;

    63         static final int CANVAS_PAINT_MIDLET_REQUEST = 6|CANVASBIT;

    64         static final int CANVAS_POINTERDRAGGED = 7|CANVASBIT;

    65         static final int CANVAS_POINTERPRESSED = 8|CANVASBIT;

    66         static final int CANVAS_POINTERRELEASED = 9|CANVASBIT;

    67         static final int CANVAS_SHOWNOTIFY = 10|CANVASBIT;

    68         static final int DISPLAYABLE_SIZECHANGED = 11|DISPLAYABLEBIT;

    69         static final int DISPLAYABLE_COMMANDACTION = 12|DISPLAYABLEBIT;

    70         static final int CUSTOMITEM_HIDENOTIFY = 13|CUSTOMITEMBIT;

    71         static final int CUSTOMITEM_KEYPRESSED = 14|CUSTOMITEMBIT;

    72         static final int CUSTOMITEM_KEYREPEATED = 15|CUSTOMITEMBIT;

    73         static final int CUSTOMITEM_KEYRELEASED = 16|CUSTOMITEMBIT;

    74         static final int CUSTOMITEM_PAINT_NATIVE_REQUEST = 17|CUSTOMITEMBIT;

    75         static final int CUSTOMITEM_PAINT_MIDLET_REQUEST = 18|CUSTOMITEMBIT;

    76         static final int CUSTOMITEM_POINTERDRAGGED = 19|CUSTOMITEMBIT;

    77         static final int CUSTOMITEM_POINTERPRESSED = 20|CUSTOMITEMBIT;

    78         static final int CUSTOMITEM_POINTERRELEASED = 21|CUSTOMITEMBIT;

    79         static final int CUSTOMITEM_SHOWNOTIFY = 22|CUSTOMITEMBIT;

    80         static final int CUSTOMITEM_SIZECHANGED = 23|CUSTOMITEMBIT;

    81         static final int CUSTOMITEM_TRAVERSE = 24|CUSTOMITEMBIT;

    82         static final int CUSTOMITEM_TRAVERSEOUT = 25|CUSTOMITEMBIT;

    83         static final int ITEM_COMMANDACTION = 26;

    84         static final int ITEMSTATELISTENER_ITEMSTATECHANGED = 27;

    85         static final int RUNNABLE_CALLSERIALLY = 28;

    86 

    87         /*

    88          * Event parameters.

    89          */

    90         int type;

    91         int x;

    92         int y;

    93         int width;

    94         int height;

    95         int keyCode;

    96         Runnable runnable;

    97         Command command;

    98         CommandListener commandListener;

    99         ItemCommandListener itemCommandListener;

   100         Item item;

   101 

   102         /*

   103          * Handler object. The object that the LCDUIEvent will be passed to

   104          * when the event is dispatched. Based on the event type it's known

   105          * what type of an object it must be. The handler object will

   106          * implement how to do the actual callback.

   107          */

   108         Object handlerObject;

   109 

   110         /*

   111          * The associated eSWT widget. Used to store the eSWT widget which

   112          * the original eSWT event was for. E.g. in Form the CustomItem's

   113          * widget may change while the event is in the queue.

   114          */

   115         Widget widget;

   116 

   117         /*

   118          * Used by EventQueue.

   119          */

   120         LCDUIEvent next;

   121 

   122         private LCDUIEvent()

   123         {

   124         }

   125     }

   126 

   127     /*

   128      * The event loop executed in a dedicated dispatcher thread. Events are

   129      * popped from the queue and dispatched oldest first until there are no

   130      * more events. Then the thread sleeps until new events are posted or

   131      * termination is requested. Any exceptions thrown from the event handlers

   132      * are let through to the runtime which should lead into termination of

   133      * all threads in the process.

   134      */

   135     private static class EventLoop implements Runnable

   136     {

   137         private boolean noException;

   138         public void run()

   139         {

   140             try

   141             {

   142                 Logger.info(logName + "Dispatcher thread started");

   143                 while(true)

   144                 {

   145                     LCDUIEvent event;

   146                     do

   147                     {

   148                         synchronized(wakeLock)

   149                         {

   150                             if(terminated)

   151                             {

   152                                 cleanup();

   153                                 noException = true;

   154                                 return;

   155                             }

   156                             event = eventQueue.pop();

   157                             pendingWake = false;

   158                         }

   159 

   160                         if(event != null)

   161                         {

   162                             synchronized(callbackLock)

   163                             {

   164                                 // No callbacks are sent if already terminating

   165                                 if(!terminated)

   166                                 {

   167                                     handleEvent(event);

   168                                 }

   169                             }

   170                         }

   171                     }

   172                     while(event != null);

   173 

   174                     // No more events

   175                     waitForWake();

   176                 }

   177             }

   178             finally

   179             {

   180                 if(noException)

   181                 {

   182                     Logger.info(logName + "Dispatcher thread exiting normally");

   183                 }

   184                 else

   185                 {

   186                     Logger.error(logName + "Dispatcher thread exiting abnormally");

   187                 }

   188                 if(terminatedNotification != null)

   189                 {

   190                     terminatedNotification.run();

   191                     terminatedNotification = null;

   192                 }

   193             }

   194         }

   195     }

   196 

   197     private EventDispatcher()

   198     {

   199         wakeLock = new Object();

   200         callbackLock = new Object();

   201         eventQueue = new EventQueue();

   202         dispatcherThread = new Thread(new EventLoop(), this.toString());

   203         dispatcherThread.start();

   204     }

   205 

   206     /*

   207      * Cleanup that is done when closing down in a controlled way.

   208      */

   209     private static void cleanup()

   210     {

   211         eventQueue = null;

   212         dispatcherThread = null;

   213     }

   214 

   215     /*

   216      * Synchronized to the EventDispatcher class to synchronize with multiple

   217      * clients requesting the instance concurrently.

   218      */

   219     static synchronized EventDispatcher instance()

   220     {

   221         if(singleton == null)

   222         {

   223             singleton = new EventDispatcher();

   224         }

   225         return singleton;

   226     }

   227 

   228     /*

   229      * LCDUIEvent factory.

   230      */

   231     LCDUIEvent newEvent(int type, Object handlerObject)

   232     {

   233         LCDUIEvent event = new LCDUIEvent();

   234         event.type = type;

   235         event.handlerObject = handlerObject;

   236         return event;

   237     }

   238 

   239     /*

   240      * UI thread and the application threads call to add an event to the queue.

   241      * Synchronized to the EventDispatcher instance to synchronize with queries about

   242      * the queue content.

   243      */

   244     synchronized void postEvent(LCDUIEvent event)

   245     {

   246         // New events ignored after terminate() has been called.

   247         if(terminated)

   248         {

   249             return;

   250         }

   251         eventQueue.push(event);

   252         wake();

   253     }

   254 

   255     /*

   256      * Asynchronously terminates the event dispatcher. If it's currently

   257      * executing a callback it will finish it but not execute any callbacks

   258      * after it. Events possibly remaining in the queue are discarded. The

   259      * method is synchronized to the EventDispatcher instance to synchronize

   260      * with queue content manipulation and query operations.

   261      *

   262      * @param runnable Called when dispatcher is out of the final callback and

   263      * is going to die.

   264      */

   265     synchronized void terminate(Runnable runnable)

   266     {

   267         synchronized(wakeLock)

   268         {

   269             wake();

   270             terminatedNotification = runnable;

   271             terminated = true;

   272         }

   273     }

   274 

   275     /*

   276      * Canvas.serviceRepaints support is implemented in EventDispatcher so that

   277      * it's possible to synchronize properly with termination and other

   278      * callbacks without exposing the event dispatcher's internal

   279      * implementation details to other classes. This method must be called

   280      * directly in the application thread calling Canvas.serviceRepaints(). It

   281      * can be either the dispatcher thread or any application thread. Never

   282      * the UI thread.

   283      */

   284     void serviceRepaints(Canvas canvas)

   285     {

   286         // Synchronizing to callbackLock guarantees that dispatcher thread is

   287         // not in a callback and is not going to make a callback until the lock

   288         // is freed from here. If this is the dispatcher thread then it already

   289         // holds the lock.

   290         synchronized(callbackLock)

   291         {

   292             // Synchronized to the EventDispatcher instance to synchronize with

   293             // terminate() calls. Lock is freed before the callback so that

   294             // it's possible to complete a terminate() call during the

   295             // callback. Event loop is going to check after acquiring the

   296             // callbackLock if terminate() was called during this callback.

   297             synchronized(this)

   298             {

   299                 if(terminated)

   300                 {

   301                     return;

   302                 }

   303             }

   304             // Canvas.paint() is called back directly in the thread that called

   305             // serviceRepaints(). Event is not really needed but is created so

   306             // that the same APIs can be used.

   307             LCDUIEvent event = newEvent(LCDUIEvent.CANVAS_PAINT_MIDLET_REQUEST, canvas);

   308             event.widget = canvas.getContentComp();

   309             canvas.doCallback(event);

   310         }

   311     }

   312 

   313     private static void wake()

   314     {

   315         synchronized(wakeLock)

   316         {

   317             wakeLock.notify();

   318             pendingWake = true;

   319         }

   320     }

   321 

   322     private static void waitForWake()

   323     {

   324         try

   325         {

   326             synchronized(wakeLock)

   327             {

   328                 // If there has been a call to wake() then one more iteration

   329                 // must be executed before entering wait().

   330                 if(!pendingWake)

   331                 {

   332                     wakeLock.wait();

   333                 }

   334             }

   335         }

   336         catch(InterruptedException interruptedException)

   337         {

   338         }

   339     }

   340 

   341     private static void handleEvent(LCDUIEvent event)

   342     {

   343         switch(event.type & LCDUIEvent.EVENTTYPEMASK)

   344         {

   345         case LCDUIEvent.CANVASBIT:

   346             handleCanvasEvent(event);

   347             break;

   348         case LCDUIEvent.CUSTOMITEMBIT:

   349             handleCustomItemEvent(event);

   350             break;

   351         case LCDUIEvent.DISPLAYABLEBIT:

   352             handleDisplayableEvent(event);

   353             break;

   354         default:

   355             handleOtherEvent(event);

   356             break;

   357         }

   358         // When returning from here all the references to the event have been

   359         // lost and the objects referenced by the event can be gc'd. No need

   360         // to set the fields to null.

   361     }

   362 

   363     private static void handleCanvasEvent(LCDUIEvent event)

   364     {

   365         Canvas canvas = (Canvas)event.handlerObject;

   366         canvas.doCallback(event);

   367     }

   368 

   369     private static void handleCustomItemEvent(LCDUIEvent event)

   370     {

   371         Form form = (Form)event.handlerObject;

   372         form.doCallback(event);

   373     }

   374 

   375     private static void handleDisplayableEvent(LCDUIEvent event)

   376     {

   377         Displayable displayable = (Displayable)event.handlerObject;

   378         displayable.doCallback(event);

   379     }

   380 

   381     private static void handleOtherEvent(LCDUIEvent event)

   382     {

   383         switch(event.type)

   384         {

   385         case LCDUIEvent.RUNNABLE_CALLSERIALLY:

   386             handleCallSerially(event);

   387             break;

   388         case LCDUIEvent.ITEM_COMMANDACTION:

   389             handleItemCommandListenerCommandAction(event);

   390             break;

   391         default:

   392             Logger.error(logName + "Unknown event type: " + event.type);

   393             break;

   394         }

   395     }

   396 

   397     private static void handleCallSerially(LCDUIEvent event)

   398     {

   399         Display display = (Display)event.handlerObject;

   400         display.doCallback(event);

   401     }

   402 

   403     private static void handleItemCommandListenerCommandAction(LCDUIEvent event)

   404     {

   405         Item item = (Item)event.handlerObject;

   406         item.doCallback(event);

   407     }

   408 }