Monday, September 7, 2009

Lightweight User Interface Toolkit (LWUIT) API and J2ME

Hi All,

Today I am going to discuss with you LWUIT UI API. Lightweight User Interface Toolkit (LWUIT) is basically a UI library for JAVA ME Platform. It helps developer to create visually attractive or rich interfaces for mobile applications and compatible with MIDP 2.0 and CLDC 1.1 devices. It provides Swing like functionality but without the tremendous power and complexity of Swing. LWUIT offers a basic set of components, layouts, themes and animated screen transitions. The hierarchy for these UI classes is as follows:-
The architecture of LWUIT is inspired by Swing, it has some features that are not available in Swings like themes, animation and painters etc. Features like MVC, layout managers, render, and EDT(Event Dispatch Thread) are similar to Swing. The LWUIT layer is present on top of the JAVA platform, runs on the CLDC and works with LCDUI. LWUIT library uses native rendering engine of device and renders onto GameCanvas. To understand this, we need to go through from LWUITImplementation and Display class of LWUIT library; LWUITImplementation is the foundation abstract class and extends the javax.microedition.lcdui.game.GameCanvas, and defines number of critical function. Now you can understand that for LWUIT application LWUITImplementation is the starting point (which is basically an object of GameCanvas) and used to draw all the components. The Display class is that which manage the painting and event handling with LWUITImplementation as a partner. It's used to show forms and start the EDT. Before any form is shown, we must register the MIDlet, by calling static method Display.init(MIDlet myMIDlet).

Now you have dobout in your mind why we need to register MIDlet with Display class of LWUIT. The answer is very simple, the init method instantiates LWUITImplementation and invoke the init(MIDlet myMIDlet) method of LWUITImplementation and get the instance of javax.microedition.lcdui.Display class. Don't get confuse by two Display classes, we are going to use Display class of LWUIT API only for LWUIT application, because it internally call LCDUI Display class. To start you need to download LWUIT jar file. The link for downlaoding and LWUIT API documentation is :
I'll explain some components of LWUIT using small POC, so that you'll get good idea. First you need to create a project using any IDE and add LWUIT jar file to the project library, so that you are able to access LWUIT APIs.

Now create a Java class LoginMidlet and implement ActionListener interface so that every action event get handle for application.

public class LoginMidlet extends MIDlet implements ActionListener {

After that we need to register our MIDlet with LWUIT as I explain earlier,

Display.init(this);

We are going to use some components of LWUIT APIs like Container, TextArea, Label etc. We'll use LWUIT Form component and arrange all other component on it.

Form appForm = new Form("Login LWUIT Form");
appForm.setLayout(new BorderLayout());

Now we'll use Container to arrange all the other components. First we'll define the layout.

Container formContainer = new Container(new BoxLayout(BoxLayout.Y_AXIS));

Now we'll define each component one by one, Firstly Label and then I am using TextArea for input; you can also use TextField according to your requirement.

Label uName = new Label("Username");
TextArea uNameTxt = new TextArea(1, 10, TextArea.ANY);
uNameTxt.addActionListener(new ActionListener() {
    public void actionPerformed(ActionEvent actEvnt) {                    
        if (null != appForm) {
            appForm.refreshTheme();
            appForm.show();
        } 
    }
});


Label pwdLbl = new Label("Password");
TextArea pwdTxt = new TextArea(1, 10, TextArea.PASSWORD);
pwdTxt.addActionListener(new ActionListener() {
    public void actionPerformed(ActionEvent actEvnt) {
        if (null != appForm) {
            appForm.refreshTheme();
            appForm.show();
        }
    }
});

We defined the basic UI for our application now we need to arrange them and append to the Container.

formContainer.addComponent(uName);
formContainer.addComponent(uNameTxt);
formContainer.addComponent(pwdLbl);
formContainer.addComponent(pwdTxt);

After that we need to add this formContainer to appForm:-

appForm.addComponent(BorderLayout.CENTER, formContainer);

To display the current form on the screen, we'll use-

appForm.show();

Our basic POC is done and application will look like this.


Now you are thinking that why we used LWUIT, what is special about it. The main difference using LWUIT, is the Resources and UIManager section. LWUIT help us to provide good UI for application. There are two concept Styles and Themes. We use style for individual component customization means if we want to put some special customization for one label only. For e.g.

Label uName = new Label("Username");

Get the style object

Style styleObj = label.getStyle();
styleObj.setBorder(null);
styleObj.setBgTransparency(0);

Whereas, Themes are used to change the overall look and feel for application without programming. Themes are stored in resource files and loaded during runtime. We need to use this code in our application to laod a theme.

try {
    Resources res = Resources.open("/res/loginTheme.res");
    UIManager.getInstance().setThemeProps(res.getTheme("Test Theme"));
    
} catch (java.io.IOException ioe) {
    ioe.printStackTrace();

}

After using this theme our application looks like this:-


To create theme we use Resource editor. It is bundled with LWUIT library. You need to extract zip file and in util folder you'll find Resource Editor. The screenshot for Resource Editor is:-


LWUIT is in early stage but still it has really good support on devices. To browse the LWUIT Device Database, Please visit:

I hope this article help you to understand the basic architecture and features of LWUIT. Please let me know with your inputs.