How to create a custom device
By Tomas Brandalik on Jan 15, 2010
I've got a question how to create custom emulator skins several times. It can't be answered in a few words, a short tutorial with an example will be the best way of explanation. The zip bundle here contains an example of standard CLDC/MIDP device with a display of 800 x 480 pixels and a few buttons. Due to lack of creativity I call the device "Skin800x480" and I have to admit it looks quite ugly. I will use it as a reference throughout this tutorial. You can use it as a base for your further customization. Before we get to a details I need to say a few words about the installation of the device.
It is fairly simple. You just need to unzip Skin800x480.zip bundle into JMESDK 3.0 installation directory. (C:\\Program Files\\Java ME SDK 3.0 on windows or /Applications/Java_ME_SDK_3.0.app/Contents/Resources on MacOS) Restart of the device-manager is required.
Device definition and device instances
Files which you've just unzipped into JMESDK is a definition of a device. JMESDK installation directory contains only device definitions. Device definitions are during launch of the device-manager used to create device instances. After you have restarted the device-manager you can check that an instance of "Skin800x480" device has been really initialized. Have a look into your user home Library/Application Support/javame-sdk/3.0/work (MacOS) or Application Data/javame-sdk/3.0/work (windows). Device instances are identified by numbers from 1 to 6 (MacOS) or 1 to 11 (Windows). One more instance No. 7 or No.12 has been initialized by the device-manager after the "Skin800x480" installation. It's more less obvious what all files inside instance directories mean. I will let it up to you inspecting them and finding it out.
Let's check that the installation has been successful now. Open command line and and call emulator to list properties of the new device. Usually you don't have to use -Xdevice switch but because the default device is "DefaultCldcPhone1" and not our "Skin800x480" you will have to specify always device name for every emulator command. Write:
emulator -Xquery -Xdevice:Skin800x480
Command will list profile and configuration of the device along with other properties like bootclasspath, screen width and height etc. It's time to start the device now, this time star it without an application. Write:
emulator -Xjam -Xdevice:Skin800x480
or with an application
emulator -Xdescriptor:../apps/Demos/dist/Demos.jad -Xdevice:Skin800x480
Use the device and you will see how buttons behave when pressed or when mouse goes over the button.
JMESDK is highly customizable and lets you define new devices without touching a code. Flexibility is necessary since there is a big number of handsets out on the marked and they differ in many aspects. A display size or a color depth, controls, number and type of keyboards (midp, qwerty, sliding keyboard), number of displays (2 displays in case of clamshell phones), hardware modules (GPS, battery level sensor, motion sensor), external memory card just to name a few of them. JMESDK can literally assemble a device from particular components to match as close as possible desired handset. Here is what we can use as a building blocks of our device:
- skin (a picture of the handset)
- display (number of displays, size, color depth)
- device states (open, closed)
- keyboards (keyboard layout and key codes mapping)
- JVM (runtime associated with a device)
- device properties (fonts, default locale, BT address, phone number, heap size, security domain and many more)
- hardware modules (GPS, accelerometer, sensors, memory card etc.)
Making a device
Look into a zip file into devices/Skin800x480/conf. You need 3 skins (png bitmaps) of the device. 1st one displays device in "normal" state, 2nd in "highlighted" (how the button should look like when mouse goes over it) and 3rd one in "pressed" state (how button should change when it is pressed). In our case we have 4 buttons A,B,C,D and "joystick" in the middle with buttons Left, Right, Up, Down and Select. Important part is the display. You have to ensure that the size of display fits perfectly 800x480 pixels. You will need to write down boundaries of each button and of the display as well. We will use them later on in mapping of buttons and in dislpay setup.
Besides of 3 skin bitmaps mentioned above the folder contains a few other files:
- index.html, bg.jpg, skin-test-small.png - these files compose a device information page which appear in our small IDE when you double click a device in device selector.
- networkIndicatorOn.png - you need this if the device has a small light (network indicator) which blinks when there is a network traffic.
- modules file - devices are sharing some functionality across them. This file describes what support should be loaded for this device. Each row is a path to particular module. For example modules/emulator-cldc is generic cldc-hi runtime, skin/single-state-shared is a module common to all devices which have only single state, emulator/generic/ui/touch-screen-support is a module which enables touch screen support etc.
We have bitmaps with a space for display ready. What we have to do now is just to place a screen buffer properly on the bitmap and set screen buffer size. We will do this in .bean files. These files are being read when device and its runtime starts. Each .bean file represents an object with given setters.
- ScreenGraphics.bean::dimension is a setter for a width and height of a screen buffer. Proper value for our device is 800, 480
- Screen.bean::position sets x,y location of screen buffer on a skin bitmap. In our case 21,21
- NetworkIndicator.bean::bounds location and width of network inicator
- NetworkIndicator.bean::image a name of network indicator png bitmap
Our simplified device has four-way joystick, select button in the middle and four soft buttons A, B, C, D. Mapping file is called default-state.xml. It defines one single state of the device. For example Clamshell phone has 2 states opened and closed and need 2 mapping files.
Here are parts of the file:
<device-state name="Default" defaultSkin="skin-test-normal.png" pressedSkin="skin-test-pressed.png" highlightedSkin="skin-test-highlighted.png" networkIndicator="NetworkIndicator">
device-state references 3 skin bitmaps -- normal, highlighted, pressed and a network indicator object. You need to put correct bitmap names here.
<button activators="VK_F1" vmKeyCode="-6" x="259" y="509" width="88" height="22"/>
Each button is defined by its bounds (x, y, width, height) a vmKeyCode (integer sent to the runtime when button was pressed) and activator (keyboard activator for this button are VK_\* constants, as defined in java KeyEvent class)
vmKeyCodes are defined as follows:
UP = -1, DOWN = -2, LEFT = -3, RIGHT = -4, SELECT = -5, SOFT1 = -6, SOFT2 = -7, CLEAR = -8, SEND = -10 END = -11 POWER = -12 KEY_0 .. KEY_9, #, \*, etc = ASCII code of the character. (vmKeyCode for printable character is its ASCII code)
We don't have a button with printable character on our device but here is an example for number '1'.
<button activators="VK_1 VK_NUMPAD1" vmKeyCode="0x31" keyChar="1" x="36" y="493" width="76" height="31"/>
Here I will talk about files related to the device manager. Device manager recognizes any device when its corresponding device adapter is installed. For every device adapter, there is a corresponding .bean file in process/device-manager/device-adapter. Among other things adapter references runtime which should be used with this device. In our case it is cldc-hi-fx runtime (cldc/midp runtime with built-in JavaFX extension). Since there is no other option for a runtime, I won't go deeper into settings of runtime in the adapter. You will better leave adapter files untouched. Just copy all files to use them for your own device, do the search through all files and replace Skin800x480 with a name of your own device. Although one thing has left to be mentioned here. You can add as many device instances as you wish. We have 1instance for Skin800x480. Instance .bean file is in process/device-manager/device-adapter/Skin800x480/1.bean. But can be copied to 2.bean, just change the setter deviceName to for example Skin800x480_1.
I think we are done with simple customization. Definitely there's much more options to setup like device states etc. I've mentioned them all above. We can get back to them later if somebody needs them. I hope this entry will help to everyone who wants to create his own skin. Don't forget to share with us any skin you would create ...