TUTORIAL: Control issues of Java MIDlets – all secrets of button handling
Lately, with the advent of Opera Mini
and the really excellent and highly recommended Gmail MIDlet
and some quality games (see their list in the 10/19/2007 update of my 3D MIDlet article
), there has been a tremendous increase in the demand for MIDlet-related information. This is certainly shown by the sheer number of MIDlet-related questions asked at XDA-Developers, probably the best, most lively Windows Mobile hardcore user community with the most posts. For example, today, I’ve answered at least 20 different MIDlet-related questions there. Quite a few, isn’t it?
Let me give you all another modest present: in addition to my already-published previews (for example, the 3D Gaming Bible
, the 4pda.ru Download Bible
etc.), another excerpt – a full chapter – from the forthcoming Bible. Yes, it’s coming and yes, I do
try to get it ready tomorrow or the day after – everything, all accompanying screenshots and charts (the main chart
; 3D games Compatibility Chart
and JBenchmark Chart
) are ready, I only need to consolidate all my thoughts into an all-in-one, still-somewhat-comprehensive Bible, which will, I promise, be MUCH better, will contain MUCH more information and MUCH more up-to-date than that of the Russian-only 4pda.ru
. Now, look at the length of the 4Pda tutorial
(and all the linked-in ones) to see how much information it contains
Not very easy to come up with something that has even more info, is it?
Note that the MIDlet managers I refer to in the article can all be found in the main chart of the Bible
1. Control issues
If you stick to either IBM J9
or TAO Intent
(two well-known, established MIDlet managers with versions running even under WM2003(SE)), you’ll inevitably encounter major control problems with several titles. Either the WM5 softkeys or the D-pad won’t work, or none of them. If you, for some reason, stick to these MIDlet managers (also referred to as Kilobyte Virtual Machines, KVM
’s), this chapter will be of extreme importance to you. Note that now that all WM5+ devices, Smartphones (Windows Mobile Standard
), plain Pocket PC’s (Windows Mobile Classic
) and Pocket PC Phone Edition (Windows Mobile Pro
) devices alike support the, in general, vastly superior Esmertec
KVM’s, you should only do this if you really don’t have any chance of running Esmertec’s KVM’s or Jblend – that is, for example, if you have a WM2003 or WM2003SE Pocket PC or Smartphone.
However, even with the, in this regard, flawless Esmertec KVM’s and Jblend, you may still encounter problems with titles (mostly games) not supporting the D-Pad or situations (most importantly, Opera Mini and its modded version) where a MIDlet heavily depends on the hardware buttons. This means the chapter will be useful for non-TAO / J9 users as well.
There are three related (two of them being pretty huge and thorough) articles / tutorials at 4pda.ru
explaining these problems and the way you can fix them. They all are linked from the main, first article in the main MIDlet manager thread
. In general, they recommend the usage of a Chinese tool JavaMagic
, which is supposed to help J9 and/or TAO users run their titles. In addition, the also recommend some always-on-screen numeric keypads to help numeric input and, finally, two other tools as well for MIDlet conversions. We’ll soon see whether JavaMagic is able to help at all and what you should do instead of using on-screen virtual keyboards. In addition, I – a veteran Java programmer and instructor – also explain what the control problems are caused by and why TAO and IBM J9 behave so strangely.
1.1 How it does work behind the curtains & fixing the problems with external hardware button assignment
First, let’s take a look at what problems you will face. This section will contain some references to Java; that is, the language the MIDlets are written in. Note that you can safely skip this section if you don’t know the language. If you do know it, or, at least, have some knowledge of how programming languages work, you might find this section pretty interesting.
A MIDlet, in general, implements the callback method ("function" in the traditional, non-OOP parlance) keyPressed()
, which is called back when a button is pressed. This method is passed an integer (numeric) parameter denoting the actual ASCII character (or, with non-character input, scan, denoted by negative numbers) code of the button that has been pressed. If you’ve done any actual programming in any language (or are just computer-savvy), you will certainly recognize the ASCII character code values 48, 49, 50 etc. it typically has: yes, they correspond to the 0, 1 and 2 buttons, respectively (and the list continues).
Most MIDlets don’t directly act on this direct code, but give a call to the getGameAction()
(a method in the superclass javax.microedition.lcdui.Canvas
) to make the MIDlet manager convert this code to a symbolic constant. This is, in most cases, a much safer way to decide what has happened (what button was pressed). The sole reason for this is the following: D-pad-less phones (and many users) use dialpads (2 for up, 8 for down, 4 for left and 6 for right) instead of D-pads. This, unfortunately, results in different ASCII character / button scancodes returned. Using getGameAction()
guarantees that these different codes (for example, except for TAO, the scancode -2
(with TAO, -57378
) for the down arrow of the D-pad and the ASCII code 56
for the numeric button on the dialpad) are reported as DOWN events, independent of their original (numeric) value.
There are, unfortunately, some MIDlets that, at least in the menus, don’t adhere to this convention – that is, they don’t give an additional call to getGameAction()
but try to directly process the parameter passed to keyPressed()
. One example is Andreotti Racing
(see "!!!3D_Andretti_ Racing_240x320.jar
" in the main game compatibility chart
), where the menus MUST be controlled by the dialpad (or numeric hardware keys), NOT the D-pad.
Also note that, regarding the special case of TAO, some games (for example, "!!3D_Micro_Counter_Strike_Beta.jar
") might be hard-wired to both, most common D-pad and dialpad codes (again, -2 and 56 for downwards), instead of calling getGameAction()
. These games will work just great with most MIDlet managers utilizing; however, TAO, which uses special D-pad scancodes (for example, -57378 for the "down" arrow, as opposed to the standard -2), D-pad-based control won’t work, only that of the (even virtual) dialpad. This is why this particular game can’t be controlled by the D-pad, only the hardware dialpad (or any software button input solution) under TAO, while, under all the other M3G-capable MIDlet managers (Nokia N95, Jblend, Jeodek M3G
), you can use the D-pad for steering the car.
Fortunately, there is a very easy solution for all these problems. If you encounter a MIDlet that can only be controlled by (virtual) numeric keys (because, again, the game doesn’t use the additional getGameAction() call to be compatible with as many different KVM’s as possible), you might still add D-pad controllability by just using a button enhancer tool capable of redefining the four D-pad directions (currently, they’re PQzII, AEBPlus and the non-WM5-compliant buttonMax) and either the (slower) MortScript or the faster VJKeyPress to generate the actual keypresses – or, if you go with PQzII, the built-in keypress simulation feature.
This also applies to the great Web browser MIDlets Opera Mini
and Opera Mini Mod
, which add a lot of (with the Mod version, freely redefinable) shortcut functionality to (numeric) phone buttons. As they are inaccessible on Pocket PC’s without any kind of keyboard and pretty hard to access on phones with a slide-out keyboard (you always need to slide it open to be able to access the numeric row), in these cases, you WILL want to use external tools to simulate the dialpad button press using the hardware application buttons.
You can find extensive information on all this (assigning the simulation of dialpad keypresses to hardware application buttons or D-pad arrows) in the Button Enhancer Bible
. Please do make sure you read it very thoroughly
. Here, therefore, I don’t spend more time on this question.