Skinning the MicroEmulator

Part 2 - The Stand Alone Emulator

Author: Bertil Gralvik
Date: 2004-03-08

Introduction

In Part 1 - The Applet emulator of this tutorial I gave a rather comprehensive description on how to create a skin for the MicroEmulator. I used the Applet version intended for MIDlet presentations over the web. The work included crafting the basic images for the skin, the measurement of screen and button extents and positions, necessary changes to the device descriptor XML document, extending the AppletDevice class and the packaging and deployment of the new skin.

The MicroEmulator comes in three stand alone versions using different windowing systems: AWT, JFC/Swing and SWT. A version for Java WebStart is also in the pipe.

Here we will go through the steps required to use the new skin for the stand alone J2SE version of the emulator. With few differences the same work can be done for the AWT and SWT versions.

Swinging the skin

Images

To use our new T610 skin for the J2SE version of the MicroEmulator we use the same images as for the Applet version.

The device descriptor

The device descriptor contains information about the device and is read by the emulator at start up. It describes the position and extent of the screen, the placement of the device buttons and what PC keyboard keys and MIDP events they are mapped to.

For the AppletDevice this document is a somewhat relaxed XML file with the XML declaration excluded. The file is named "device.txt".

For the J2SE version it is a well formed XML file "device.xml" which includes the XML version declaration:

<?xml version="1.0" encoding="UTF-8"?>

AS for the Applet version, this file resides in the same directory as the images and the device class. We simply reuse the "device.txt" file from the AppletDevice project, include the XML declaration and rename it as "device.xml".

The device class

For the Applet version we created a device class by extending the AppletDevice class. The class is used to initiate the parent device class with the path to the device descriptor.

For the J2SE stand alone version we'll do the same, only this time we'll subclass the J2SEDevice class.

package devices.sonyericsson.t610;

import com.barteo.emulator.EmulatorContext;
import com.barteo.emulator.device.j2se.J2SEDevice;

public class T610Device
    extends com.barteo.emulator.device.j2se.J2SEDevice {
  public T610Device() {
  }

  public void init( com.barteo.emulator.EmulatorContext context ) {
    init( context, "/devices/sonyericsson/t610/device.xml" );
  }
}

The compiled class is placed in the same directory as the device descriptor and the images.

The manifest

To complete the information set for the skin, we need a manifest file "Manifest.mf" in a subdirectory META-INF. It should contain the Device.Name and Device-Class entries like this.

Manifest-Version: 1.0
Device-Name: T610 Device
Device-Class: devices.sonyericsson.t610.T610Device

Packing the device

As for the AppletDevice version, we have the archive the device in a Java Archive using the JAR tool or WinZip. The directory structure of the archive should be

├───devices
│ └───sonyericsson
│ └───t610
│ normal.png
│ over.png
│ pressed.png
│ up.png
│ down.png
│ abc_lower.png
│ abc_upper.png
│ 123.png
│ signal.png
│ java_logo.png
│ battery.png
│ device.xml
│ T610Device.class
│
└───META-INF
manifest.mf

The archive should have the file extensinon ".dev". In my case I've named it "T610device.dev".

Running as stand alone

You may run the emulator as a standalone application by issuing one of the following commands at the command line:

java com.barteo.emulator.app.Main [MIDlet application main class]
java com.barteo.emulator.app.Main [MIDlet jad file]

java -jar me-app.jar [MIDlet application main class]
java -jar me-app.jar [MIDlet jad file]

 -  me-app.jar must be in the CLASSPATH
 - [MIDlet application main class] parameter is optional. If it is used,
   the MIDlet application jar file must be in the CLASSPATH.
 - [MIDlet jad file] must have a .jad extension,

If you start the emulator without the optional MIDlet main class or *.jad argument, you can load any MIDlet by opening its JAD file from the File menu.

To set the classpath for the me-app.jar, you can use the -cp or -classpath argument to the JVM or include it in the environment variabel CLASSPATH.

To avoid crowding the the CLASSPATH variable, you may chose to instead copying the me-app.jar archive into the jre/lib/ext directory of the JDK or runtime installation directory.

If you chose to use the latter approach on a Windows system, you should be able to start the emulator by double clicking on the me-app.jar file in Windows Explorer.

SimpleDevice running SimpleDemo

java com.barteo.emulator.app.Main simpledemo.jad

Here me-app.jar is in the classpath and simpledemo.jad in current directory.
Here is the JAD file:

----------------------------------------------------------
Created-By: Bartek Teodorczyk
MIDlet-1: SimpleDemo, , com.barteo.midp.examples.simpledemo.SimpleDemo
MIDlet-Jar-Size: 15283
MIDlet-Jar-URL: simpledemo.jar
MIDlet-Name: SimpleDemo
MIDlet-Vendor: Bartek Teodorczyk
MIDlet-Version: 1.0
Manifest-Version: 1.0
--------------------------------------------------

Here the built in default device is used, but we can change device from the "Options" menu. We get the "Select device.." dialog.

The Select device dialog

Here we have only one device to select, the Default device. As a first test of how this works we may select this device. It will seem that nothing has changed, but secretly something has. Let's close the emulator and investigate.

At this point a config.xml file is saved to the users home directory, which on a Windows XP system is c:\Documents and Settings\<user>\.micromemulator, where <user> is the current username.

The contents of config.xml at this point isn't much to see:

<config><devices/></config>

However this will change when we introduce our new device. Let's finally do it.

Restart the emulator and launch the "select device" dialog.

Click the "Add" button and browse to the device archive T610devices.dev

Click the "Set as default" button and finally click "Ok"

Of everything worked according to plan, you should see something like this:

The stand alone T610 emulator running petit.T610Clock

When we selected the new device, the device archive is copied to the users home directory and given a generic name and new entries is added to the config.xml file.

<config>
   <devices>
     <device default="true">
       <name>T610 Device</name>
       <filename>dev45726.dev</filename>
       <class>devices/sonyericsson/t610/T610Device</class>
     </device>
   </devices>
</config>

Now the config file makes sense. For each device the markup informs the emulator of the device name, the device archive name and the qualified name of the device class.
Our T610 device is set as default, so that next time we start the emulator, the new T610 skin is used by default.

That's all there's to it!

Recourses

Here is the archived version of the T610 device for the J2SE version.

More resources in Skinning the MicroEmulator, Part 1

Comments, corrections and the like are appreciated!

Disclaimer: All current and future disclaimers apply, INCLUDING but NOT LIMITED to this one.

You can reach me at petit[at]petitpub[dot]com

Petit Labs