Tutorial

1 Installation

• Download and extract the lwuimb-xxx.tar.gz file
• Put the lwuimb-xxx.jar, microbackend-*.jar and the "configuration" directory in your classpath
• Start coding or start the demo:

java -cp dist/microbackend.jar:dist/lwuimb-0.1-alpha1.jar:dist/lwuimb-demo.jar:configuration org.thenesis.lwuimb.demo.BaseDemo

2 Usage

LWUIMB gives to developers the ability to choose the level of control on the underlying graphics layers. The implicit mode fits well with fast development, simple application or deployment on embedded platforms, while the explicit mode provides more control (useful for integration in an IDE for example)

Common code for all examples below:

/**
 * Create a LWUIT application
 */
public Form createLWUITApp(Object m) {
    Form f = new Form("Main");
    TextArea ta = new TextArea("Sed ut perspiciatis unde omnis...", 5, 20);
    f.addComponent(ta);
    f.show();
    return f;
}

2.1 Implicit mode

When running in implicit mode, LWUIMB starts the backend by searching in the system properties or the configuration file (in that order).

It's by far the easiest mode, but you have less control on the graphics backend than with the explicit mode.

2.1.1 System properties

Just set the appropriate property in your code somewhere before initializing the LWUIT Display (i.e Display.init() method).

System.setProperty("org.thenesis.microbackend.ui.backend", "AWT");

// ...

// Create a LWUIT application
Display.init(null);
Form mainForm = createLWUITApp();

Alternatively you can set the property in the java command line:

java -Dorg.thenesis.microbackend.ui.backend=AWT -cp microbackend-core.jar:microbackend-graphics.jar:lwuimb-xxx.jar -jar lwuimb-demo.jar

2.1.2 Configuration file

Open the LWUIMB configuration file (configuration/org/thenesis/lwuit/configuration/configuration.cfg) and modify the backend property:

# Possible backend values: NULL, SDL, AWT, AWTGRABBER, SWT, X11, GTK, QT, FB
org.thenesis.microbackend.ui.backend:AWT

Java code:

// Nothing special to do !
// Create a LWUIT application
Display.init(null);
Form mainForm = createLWUITApp();

2.2 Explicit Mode

2.2.1 AWT

You can pass any AWT Container to the Display.init() method. The container must have a valid size and should not contain any component yet.

// Create an AWT Frame 
Frame frame = new Frame();
frame.setSize(320, 240);
        
// Create a LWUIT application
Display.init(frame);
Form mainForm = createLWUITApp();

// Make the frame visible    
frame.pack();
frame.setVisible(true);

2.2.2 SWT

You can pass a SWT Canvas to the Display.init() method. The canvas must have a valid size.

// Create a SWT canvas
org.eclipse.swt.widgets.Display display = new org.eclipse.swt.widgets.Display();
Shell shell = new Shell(display);
shell.setText("");
Canvas canvas = new Canvas(shell, SWT.NONE);
canvas.setSize(w, h);
        
// Create a LWUIT application
Display.init(canvas);
Form mainForm = createLWUITApp();
        
// Show the SWT canvas and start the loop event
canvas.forceFocus();
shell.pack();
shell.open();
while (!shell.isDisposed()) {
    if (!display.readAndDispatch())
        display.sleep();
}
display.dispose();

2.2.3 UIBackend

If you have special needs which don't fit in the provided backends, you can implement quite easily your own backend.

You just have to implement the org.thenesis.microbackend.UIBackend interface.

// Create an custom UIBackend
UIBackend customBackend = new MyCustomBackend();
        
// Create a LWUIT application
Display.init(customBackend);
Form mainForm = createLWUITApp();

3 Advanced instructions

3.1 Building MicroBackend and/or native parts

If you want to use other backends than AWT or SWT, like the native ones (SDL, X11, GTK, QT, FB), or (re)build MicroBackend from the sources, you have to complete some other steps.

Grab the MIDPath sources (MicroBackend is a subproject of MIDPath currently)

# svn export https://midpath.svn.sourceforge.net/svnroot/midpath/trunk
# export MIDPATH_HOME=$(pwd)/trunk

Build the sources with the appropriate options (type ./build.sh --help for a list of options). To build the Linux Framebuffer native part:

# cd $MIDPATH_HOME
# chmod u+x build.sh
# ./build.sh --fb

Grab the .so files and microbackend.jar from the dist directory and add it to your LWUIT project.

3.2 Building LWUIMB from the sources

Go in the distribution root and type:

# svn export svn://svn.evolvis.org/svnroot/lwuimb/trunk lwuimb
# cd lwuimb
# chmod u+x build.sh
# ./build.sh

You may have to change some paths in the build script to fit your environment. Alternatively, you can use command line options to do the same (type ./build.sh --help for a list of options).

For example, to use a custom J2SE class library:

./build.sh --with-j2se-jar=/path/to/my/j2se-classes.jar