LWUIT – an introduction

Have you ever tried to create a business application in Java ME? The user interface toolkit provided by MIDP 2.0 is very limited. There is now an alternative toolkit available. Read on and you will learn about this new user interface toolkit. But be aware, there will be some spiffy source code and an accompanying screen shot!

What is it?

The new Light Weight User Interface Toolkit (LWUIT) is a new UI toolkit for Java ME that is inspired by Swing. It is developed by Sun and it is available as open source (GNU GPL V2). The early access version runs on MIDP 2.0, but the upcoming versions will be available for other Java ME profiles as well. This opens up the possibility to write the same user interface code for mobile devices ranging from very simple mobile phones to advanced PDAs. The feature list for LWUIT is impressive. It includes features like:

  • pluggable look-and-feels with themes
  • layout managers
  • touch screen support
  • fonts
  • resources bundles
  • transitions
  • 3D integration

The developer could create a customized look-and-feel by creating a subclass to
the LookAndFeel or DefaultLookAndFeel class, similar to Swing. On top of that it is possible to set a theme. A theme is defined in a Java property file. You use a key in the property file that is similar to a CSS selector. For example, Button. bgColor=ff0000 is used to set all button backgrounds to red.

The developer has access to layout managers like BorderLayout, FlowLayout,
GridLayout and others known from Swing. The GridBagLayout is not present, but I doubt that many will miss it. If you ever tried it, you know what I mean. The touch screen support is also an important feature, since many mobile devices today has touch screens.

The support for fonts in MIDP is rather limited. In LWUIT it is possible to use your own fonts. You use the resource editor to convert your fonts from your favorite operating system, and the selected fonts are converted and bundled in your jar file. The editor is also used for localization strings, images and themes.

A transition is used when switching between different forms, i.e. screens, and brings a nice touch to the UI. If the phone has an implementation of JSR-184:
Mobile 3D Graphics API for J2ME, it is possible to make a cube transition. The 3D integration let us show 3D models in our 2D interface. This is realized by loading an M3G file. The M3G format is 3D format that is optimized for Mobile
Devices (for more details see the references). By connecting each M3G object to a LWUIT graphic object it is possible to implement advanced logic for your 3D interface. The M3G is supported by JSR-184. A nice side effect of this is that the 3D graphics could be rendered by your 3D hardware on your mobile device. Support for SVG is also announced, which will give even more possibilities when writing UIs for mobile devices.

How to use it

And now for the moment you all have been waiting for. The code! We start with
the classical “Hello JayView” example. The code looks like this:

package se.jayway.javame.lwuit.test;

import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException;

import com.sun.lwuit.Button;
import com.sun.lwuit.Command;
import com.sun.lwuit.Display;
import com.sun.lwuit.Form;
import com.sun.lwuit.Label;
import com.sun.lwuit.animations.Transition3D;
import com.sun.lwuit.events.ActionEvent;
import com.sun.lwuit.events.ActionListener;
import com.sun.lwuit.layouts.BorderLayout;
import com.sun.lwuit.util.Log;

public class HelloJayViewMIDlet extends MIDlet implements ActionListener {

  private Command exitCommand;
  private Command nextCommand;
  private Form formTwo;
  private Button button;

  protected void startApp() throws MIDletStateChangeException {

    Form formOne = new Form(”Hello”);
    formOne.setLayout(new BorderLayout());

    Label label = new Label(”JayView”);
    formOne.addComponent(BorderLayout.CENTER, label);

    button = new Button(”Help Me”);
    formOne.addComponent(BorderLayout.SOUTH, button);

    exitCommand = new Command(”Exit”);
    nextCommand = new Command(”Next->”);

    formOne.setTransitionOutAnimator(Transition3D.createCube(750, false));

    formTwo = new Form(”Hello Again”);
    // TODO: Add components and Commands to fromTwo

  protected void destroyApp(boolean unconditional)
      throws MIDletStateChangeException {
    // TODO: Add code that release all out resource

  protected void pauseApp() {
    // TODO: Do stuff when we pause the MIDlet

   * Implementation of the <code>ActionListener</code> interface.
  public void actionPerformed(ActionEvent event) {
    Log.p(”actionPerformed()”, Log.INFO);
    Command command = event.getCommand();

    if (command == exitCommand) {
    } else if (command == nextCommand) {

    Object source = event.getSource();
    if(source == button){
      // TODO: Show some help to the user


At a first glance this looks like a normal MIDP application. You may recognize
Command, Form & Display classes. If you look close, you notice that these are
not the same classes. They are in fact classes found in the LWUIT toolkit and
actually work a little bit different. This is where the similarities end.

Let us take a look at the differences instead. We start by initializing our display
with Display.init(). This takes a reference to our MIDlet object, which in turn
takes care of all the initialization. We continue by creating a Form object which
occupies the whole screen. The Form object is populated with a Label that
is placed in center of the screen. The alignment of the label is set to center.
As you can see we have good control of the placement of our components,
unlike MIDP where you are dependent on the underlying implementation. A
Label object can have a text and/or an icon. When we have both, it is of course
possible to align the text relative to the icon.

A Button object is like a button that you are used to from your desktop
applications. However it is something that is not found in MIDP. Just
like a Label you could have an icon and/or a String in each Button. You
add an ActionListener to the Button, which in our case is the MIDlet that
implements the ActionListener interface. The ActionListener consists of the
actionPerfomed() method, which is like Swing, not like MIDP. The Button is
added to the south of the Form. It occupies the whole width of the Form since
that is how BorderLayout works like. In a real world example we could use
nested layouts to fix this problem. It should be noted that there are still some
peculiarities in this early access release. For example it is possible set the colors
of a Label object, but not on a Button object.

The next thing to do is to create our Command objects. Each Command
object corresponds to an item in one of the menus. We add them to the Form.
The action could be the user pressing a button or selecting a command. The
Command that triggered a call to actionPerformed() is fetched using the event.
getCommand() method. We use an if-else statement to check which Command
that was used. If you have more Command objects than this, you should consider
using the Command pattern as described in JayView 10, Take Command in
Java ME. We must also check if the event was received from the button. We
get the source with a call to event.getSource(), just like in Swing. We finish off
the actionPerformed() method by checking if the event was received from our

In our example we call notifyDestroyed() to signal to the platform that we are
finished. In the other case we show our second Form. By the way, did you notice
that we did call a method called setTransitionOutAnimator()? This is used to
create a 3D cube transition when switching between the first and the second
Form. It is not something that is available in MIDP.

The LWUIT toolkit contains some utilities like a logging utility, as seen in
actionPerformed(). This is an easy way to do some simple logging. But I would
recommend that you use a proper Java ME logging framework, like Microlog.
Voila! This is how it looks like in an emulator.

Voila! This is how it looks like in an emulator.

Some Final Words

My first impression of LWUIT was very positive. Since I consider myself a fluent
writer in “Swinglish”, I was happy when I could re-use my programming skills
for LWUIT. Many Swing lovers will have the same feeling, I guess. Since it is
open source I think that the toolkit could reach a wide audience and hopefully
it will have a large community with all its benefits. A big advantage is that we
now have a large set of components available. One thing missing in MIDP is
a tabbed pane, which is included in LWUIT. Another thing to consider is of
course the size that the LWUIT adds to your application. The full size of the
jar-file is about 230 KB. In practice you will not use all the classes, and with
an obfuscator the size will be reduced even further. According to the LWUIT
development team the average overhead when using LWUIT is around 100 KB.
In any case an obfuscator should always be part of your Java ME toolbox.

On the downside is the performance. I have tested it on a Sony Ericsson W910,
which contains a high performance JVM. Although some of the components
were not as fast as I would like them to be it has to be pointed out that this is
only an early access release and the performance will probably be much better.
Another possible disadvantage is the type of open source license that has been
chosen. Many people would argue that the Apache License would be a better
license. However this is a minor issue.

I think that this could be a practical alternative when developing MIDP
applications. Its success depends on the performance and a large developer
community. If both of these get satisfied we will see many mobile applications
developed with LWUIT, at least according to my opinion.


  • The LWUIT homepage
  • GNU GPL V2
  • JSR 184: Mobile 3D Graphics API for J2ME
  • M3G on Wikipedia
  • Java Mobility Podcast 46: LWUIT – Lightweight UI Toolkit
  • The MicroLog homepage
  • This Post Has 2 Comments

    1. Uma

      Hi Johan,
      Thanks for the tutorial.I would like to clear one doubt.I am a begginer in android.
      Is it possible to use LWUIT classes in android.LWUIT contains the form classes. I need to import This in android so that i can create forms in android this way like:
      Form form1=new Form();

      Or any alternative available.
      Could u pls help me with this?

    2. Faiz

      Absence of GridBagLayout giving too much pain to me.

    Leave a Reply