1 import javax.microedition.lcdui.Command;
 2 import javax.microedition.lcdui.CommandListener;
 3 import javax.microedition.lcdui.Displayable;
 4 import javax.microedition.midlet.MIDlet;
 5 import garcer.j2megui.GUICanvas;
 6 import garcer.j2megui.Resources;
 7 import garcer.j2megui.Container;
 8 import garcer.j2megui.Label;
 9 
10 public class HelloWorld extends MIDlet implements CommandListener {
11 
12     public GUICanvas guiCanvas;
13     public Container form;
14 
15     public HelloWorld() {
16         guiCanvas = new GUICanvas("[YOUR LICENSE KEY GOES HERE]",
17                 "/garcer/j2megui/resources/default.csf");
18         int r = Resources.getInstance().getErrorState();
19         if (r != Resources.ERROR_OK) {
20             System.out.println("Error code " + r + " loading resources, line " +
21                     Resources.getInstance().getLastLineCounter());
22             notifyDestroyed();
23         }
24 
25         guiCanvas.start(this);
26         form = guiCanvas.getForm();
27         guiCanvas.suspendLayout();
28 
29         Command c = new Command("Exit", Command.EXIT, 1);
30         guiCanvas.addCommand(c);
31         guiCanvas.setCommandListener(this);
32 
33         Label lbl = new Label("Hello world");
34         lbl.getBounds().setLocation(5, 5);
35         form.addComponent(lbl);
36 
37         guiCanvas.resumeLayout();
38     }
39 
40     public void startApp() {
41         guiCanvas.resumeLayout();
42     }
43 
44     public void pauseApp() {
45         guiCanvas.suspendLayout();
46     }
47 
48     public void destroyApp(boolean unconditional) {
49     }
50 
51     public void commandAction(Command command, Displayable displayable) {
52         notifyDestroyed();
53     }
54 
55 }
56 

Even though Jpeg images are widely supported on mobile handsets, only the PNG image format is available on all devices capable of displaying images. The extent to which it is supported may vary, though. Some devices do not allow transparent images. Others may only support a 1-bit transparency mask (pixel is either transparent or opaque) and not full 8-bit alpha blending.

Some devices also restrict the file size of the image. Try to avoid images larger than 64Kb. There might also be restrictions on dimensions where some devices do not allow images larger than the size of its screen. It is also recommended that you use a PNG optimizer to reduce the size of your images even further.

Keep in mind that loading images in memory at runtime will store the images in an uncompressed format, using much more memory than the actual image. The amount of bytes allocated is roughly height X width X 4. Manipulating images usually require two to three times that amount for temporary buffers.

Certain devices have issues with fullscreen mode and can vary from not being able to use fullscreen mode to incorrectly reporting dimensions or not taking the command menu into account. Furthermore, some devices will always display the command menu in fullscreen mode, even though this is not the default behavior. Some touch screen devices also rely on the command menu to display its virtual keyboard, but fullscreen mode will remove the command menu bar, preventing user input.

J2ME GUI uses fullscreen mode by default, but this can be changed based on your needs.  Unfortunately, a wide range of newer Nokia devices have problems with their keypads if not using fullscreen mode.  If you wish to maintain compatibility with older model handsets with issues regarding fullscreen mode, you will have to detect these older models in your code and switch to windowed mode when necessary.

The most unregulated area of the J2ME specification is the mapping of device keys to specific key codes. The specification only requires that all ASCII keys be mapped to their proper values on the standard ASCII table with values ranging from 0 to 255 and that any other special device keys should be mapped to negative values. It does not specify to which key codes these should be mapped. Java does offer a way to return the key name of each key code, but this function fails on some devices and the return string is not regulated either, so the value could be any one of several possibilities. For example, the left soft key could return "left soft key", "LeftSoft", "Left Softkey", "Left menu button", "Soft key 1", etc.

This means that there is no reliable way of determining the key codes of even the most standard keys, such as the navigational buttons and the soft menu keys. There are several attempted solutions to this problem on the web, but no viable option. Some rely on trying to detect phone API's to determine the phone model and thereby trying to map the keys to known values and others attempt to interpret the key names returned for each key code. Furthermore, there is no reliable way of detecting whether the handset is a QWERTY device or not. Inevitably, multiple builds is the only real solution.

If you wish to avoid multiple builds, an alternative option is to prompt the user to map the keys used by your application the first time it starts up and to save these settings on the device. The minor once-off inconvenience to the user will avoid endless support requirements for new devices.

A Frames-per-second counter is included with J2ME GUI and can be turned on or off by calling the setShowFPSCounter() function. The getFPSCounter() function will return the last reported frame rate. Please note that by default J2ME GUI will not redraw the screen on each thread cycle. It will only repaint when necessary. This will result in a false FPS report with very high values. These values should rather be considered a measure of how responsive the interface will be to user interaction. To report the actual frame rate, use the setAlwaysRedraw(true) function. This will redraw on each thread cycle.

Also note that J2ME GUI is not set to run at full performance by default. The graphics engine thread is idled for 1 millisecond on each thread cycle. If the thread is not idled, the handset's processor will run at 100% CPU load and will quickly drain battery life. This setting will have a slight impact on FPS performance, but will significantly reduce CPU load and save battery life. If you wish to do a performance test at full speed, use the setRefreshDelay(0) function to set the idle time to 0ms.

You can also use this function to slow down the system to simulate slower devices or regulate the speed of any animation effects. Please note that this is not the preferred way to regulate animations. Use the Timer event along with the system timer to regulate animation timing. Not doing so will result in animation speed being dependant on system performance rather than predetermined time intervals.

J2ME GUI will automatically determine when to repaint the canvas, but certain operations such as those performed on timers outside the graphics engine thread could result in undetected changes in components that would normally require a canvas repaint. Such occurrences should be minimal, but should it arise, you can request a repaint by calling the resumeLayout() or performLayout() functions. This will ensure that the canvas will be repainted on the next graphics engine thread cycle.

In some circumstances, you might want to wait for a canvas repaint before continuing execution. This is usually necessary in a scenario as described above, but where you need to rely on properties involving the position or dimension of components you are currently manipulating. If this situation occurs, use the waitForRepaint() function instead. It will suspend execution and wait until the canvas has been repainted.

Most of the time, repaint requests and demands are not necessary and could be an indication that you need to reconsider your application's execution flow.