Listening to Item Changes
Your application UI may require dynamic updating based on values provided by the user, or may need extended data validation beyond what's automatically provided by some devices. The High-Level UI API lets you specify ItemListeners
objects notified of data changes based on user input.
To listen to item state changes you implement the ItemStateChange method of the javax.microedition.lcdui.ItemListener interface and register it with a Form instance by passing your class to the Form's setItemStateListener method. Subsequent calls to setItemStateListener replace the existing listener with the new listener; only one listener can be registered at any one time. The item that generated the event will be passed in as an argument, so you can use the item's accessor methods to get and change the data.
You need to be aware that not all items notify item listeners. In addition, the conditions under which items notify listeners are item-specific. The following items do notify listeners:
- TextField. The specification requires only that a TextField notify listeners of changes no later than after the focus moves away from the item. Unfortunately, the actual time at which the ItemListener is notified is implementation-dependent.
- Gauges. Gauges notify ItemListeners of state changes every time the value of the gauge changes. Some implementations of the Gauge widget don't render the current value, and a change in the value might not be noticeable on the gauge itself, so tying notifications to updates of a StringItem can provide the user with the exact value of the Gauge. On the other hand, if the value is rendered in that platform then by using a separate StringItem to track changes, you're duplicating information on the screen and potentially taking up valuable real estate. Regardless, to be on the safe side I recommend always adding a peer StringItem to clearly specify the value.
- ChoiceGroup. ChoiceGroups come in two flavorsmultiple and exclusive&3151;consequently, they notify ItemListeners differently based on the type of choice group. In multiple, group notification occurs when an element is selected or deselected. In exclusive, group notification occurs when one element is selected. Even though any currently selected choice in an exclusive group will be deselected when a user selects a different choice, the item issues only one notification per change.
Now that you know how to add items to a form and listen to changes on user input you have to provide a way for users to navigate between the various screens in your application. You achieve this with the use of Commands associated with forms. You implement the CommandListener interface to respond to commands issued by the current form.
|Figure 6: On the left, the two available commands, Back and Quit, are mapped to the softkeys typically available on cell phones while on the Palm OS the commands are rendered as buttons on the screen and also added to drop down menus.
You construct commands from the concrete javax.microedition.lcdui.Command class, passing its constructor a label, a type, and a priority. The command uses the label for display. The type and priority provide placement hints to the device. If you associate more than one command of the same type with a form, the device uses the command's priority to determine placement. You add the command to the Form (or Displayable) by calling the Form's addCommand method. You can remove Commands by calling the removeCommand method. You can share the same commands between forms.
How devices render and place commands varies widely from device to device; some cell phones will map two commands to the softkeys on a cell phone and put the rest in a menu that users can access from one of the softkeys. In contrast, a Palm Pilot will place the commands into drop-down menus or on-screen buttons. You have no control over command placement, you can only provide hints to the device.
Listening to commands on a screen is simple. Implement the CommandListener interface and put your command processing code or action delegation in the commandAction method of the class. The commandAction method receives the Command object to which it should respond and the Displayable associated with the command. You set the current command listener for a form by calling its setCommandListenermethod. You can have only one CommandListener associated with each form. Setting a new CommandListener replaces the existing one; passing null to getCommandListener removes the current Command.