1 Introducing the Lightweight UI Toolkit Library

Scope and Portability

The Lightweight UI Toolkit library is strictly a widget UI library and does not try to abstract the underlying system services such as networking or storage. It also doesn't try to solve other UI issues related to native graphics, etcetera.

To enable portability, the Lightweight UI Toolkit library implements its own thin layer on top of the native system canvas and provides a widget abstraction. This abstraction is achieved using several key classes that hide the system specific equivalents to said classes, such as Graphics, Image and Font.

When working with the Lightweight UI Toolkit library it is critical to use the abstract classes for everything. To avoid corruption, there is no way to access the "real" underlying instances of these classes (for example, javax.microedition.lwuit.Graphics).

LWUIT strives to enable great functionality on small devices that might be incapable of anti-aliasing at runtime, or might choke under the weight of many images. To solve these problems the LWUIT library ships with an optional resource file format that improves resource utilization. For more details, see Chapter 9.

import com.sun.lwuit.Display;
import com.sun.lwuit.Form;
import com.sun.lwuit.Label;
import com.sun.lwuit.layouts.BorderLayout;
import com.sun.lwuit.plaf.UIManager;
import com.sun.lwuit.util.Resources;
 
public class HelloMidlet extends javax.microedition.midlet.MIDlet {
 
   public void startApp() {
       //init the LWUIT Display
       Display.init(this);
 
       // Setting the application theme is discussed
       // later in the theme chapter and the resources chapter
       try {
             Resources r = Resources.open("/myresources.res");
             UIManager.getInstance().setThemeProps(
               r.getTheme(r.getThemeResourceNames()[0])
              );
            } catch (java.io.IOException e) {
   }
       Form f = new Form();
       f.setTitle("Hello World");
       f.setLayout(new BorderLayout());
       f.addComponent(BorderLayout.CENTER, new Label("I am a Label"));
       f.show();
   }
 
   public void pauseApp() {
   }
 
   public void destroyApp(boolean unconditional) {
   }
} 

Hello world looks like Figure 1-2.

Figure 1-2 Hello World

Description of "Figure 1-2 Hello World"

Notice in Example 1-1 that the very first line of code for any application using the Lightweight UI Toolkit library must register the main class with the display. This behavior is tool-specific. In MIDP there is not much you can do without a reference to the parent MIDlet, so this operation must be performed in the beginning of the application.

The creation of the UI code is left within the MIDlet for simplicity but it could be separated to any class to allow full portability in any future platform to which the Lightweight UI Toolkit library would be ported.

Events and Threading

For increased compatibility, the Lightweight UI Toolkit library completely handles and encapsulates UI threading. It has a single main thread referred to as the "EDT" (inspired by the Event Dispatch Thread in Swing and AWT). All events and paint calls are dispatched using this thread. This guarantees that event and paint calls are serialized and do not risk causing a threading issue. It also enables portability for profiles that might have minor threading model inconsistencies. See the Display class (com.sun.lwuit.Display in the API documentation) for further details about integrating with the EDT and serializing calls on it.