Using eSWT

Like LCDUI MIDlets, eSWT MIDlets must implement the common MIDlet lifecycle methods.

The eSWT UI runs in its own thread and its functions can be only accessed from within this thread. Every eSWT MIDlet requires the following components:

• A Display object created in the eSWT UI thread. This object acts as a resource manager, sharing the system resources necessary to run the eSWT UI.

• An event loop that redirects Events to their listeners.

• A Shell to be displayed on the screen. You can also have controls on the Shell to provide control over the UI.

The eSWT widget structure is hierarchical. Each widget can only have one parent, and the widget is added to that parent at creation.

eSWT MIDlets must also meet the following requirements:

• Display instance

  • When using eSWT for creating the MIDlet UI, the org.eclipse.swt.widgets.Display class represents the connection point between Java™ ME and the native UI functionality.

  • A MIDlet can create either an instance of LCDUI Display or an instance of eSWT Display, but not both. If a MIDlet tries to create one when the other already exists, or tries to create multiple eSWT Display instances, a runtime exception is thrown.

  • MIDlets in the same MIDlet suite can all use eSWT. In this case, each MIDlet must create its own Display instance.

• Lifecycle

  • When an eSWT MIDlet enters the active state for the first time by calling the MIDlet.startApp method, the MIDlet must create the eSWT UI thread as its first step.

  • To avoid hanging the event dispatcher, MIDlets cannot execute the eSWT event loop directly in the thread that called the MIDlet.startApp method.

  • The eSWT UI thread must construct a Display instance and enter an event loop dispatching eSWT events.

  • The Display instance for the MIDlet should be created immediately after the eSWT UI thread has been started, and it should not be disposed until the MIDlet is about to enter the destroyed state.

  • Some eSWT objects must be manually deallocated with the dispose method. As a rule of thumb, objects created by using the new constructor must be disposed manually. Also, when a parent object is deallocated, all its children are deallocated as well. Resources such as Images, Colors, GCs (Graphical Contexts), and Fonts must all be disposed manually.

In short, an eSWT MIDlet must first create the UI thread in the MIDlet.startApp method and then a Display instance in the UI thread. This Display instance must stay active until the MIDlet is destroyed.

To simplify the management of the UI thread and the MIDlet lifecycle, use the eSWT MIDlet starter for creating your eSWT MIDlet.

eSWT classes

Use the eSWT API Display class to construct the user interface thread and to implement the event loop. After constructing the user interface thread, create a top-level Shell, to which you can add widgets and UI elements. For an example of this, see HelloWorld in eSWT below.

You can invoke user interface operations only through the user interface thread. If you try accessing an SWT object outside the user interface thread, you receive an SWTException("Invalid thread access"). eSWT handles user input generated and system events with an event loop that listens for events in a message queue. The event loop dispatches these events to appropriate handlers until you dispose the user interface thread.

Figure: eSWT class diagram