Introduction

API overview

The Lightweight UI Toolkit is a lightweight widget library inspired by Swing but designed for constrained devices, such as mobile phones. Lightweight UI Toolkit supports pluggable theme-ability, a component and container hierarchy, and abstraction of the underlying GUI toolkit. The term lightweight indicates that the widgets in the library draw their state in Java source without native peer rendering.

Internal interfaces and abstract classes provide abstraction of interfaces and APIs in the underlying profile. This allows portability and a migration path for both current and future devices and profiles. For example, Graphics would be an abstraction of the graphics object in the underlying profile.

The Lightweight UI Toolkit library tries to avoid the "lowest common denominator" mentality by implementing some features missing in the low-end platforms and taking better advantage of high-end platforms.

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 does not try to solve other UI issues related to, for example, native graphics.

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 utilisation.

Simple "Hello World" example

This is a simple "Hello World" example written on top of MIDP. As in all MIDlets, the application management system (AMS) requires a MIDlet class to exist. Note that all UI code making use of the Lightweight UI Toolkit is compatible with other Java platforms, too: instead of a MIDlet class, in a CDC environment an Xlet and in Java SE a main class would be expected.

import com.sun.lwuit.Display;
import com.sun.lwuit.Form;
import com.sun.lwuit.Label;
import com.sun.lwuit.layouts.BorderLayout;
 
public class HelloMidlet extends javax.microedition.midlet.MIDlet {
 
   public void startApp() {
       //init the LWUIT Display
       Display.init(this);
 
       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) {
   }
}

The very first line of code for any application using the Lightweight UI Toolkit library must register the main class with the display. This behaviour 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.

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 serialised 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 serialising calls on it.

LWUIT implementation

The LWUIT implementation is the foundation of LWUIT and its portability. It is a single class representing a hardware abstraction layer (HAL) that contains all the platform-specific code within LWUIT. In LWUIT for Nokia Asha and Series 40 software platform port, the implementation classes check at runtime which Nokia Asha or Series 40 software platform UI style is used in the device the application is running on.

Application developers should not need to modify LWUIT implementation or any other low-level source code.