Programming Wireless Devices with the Java2 Platform

10.2 StringItem

Read-only strings can be added to a Form either directly as Strings (Java String objects) or as StringItems. StringItem is a simple class that is used to wrap Strings so they can be treated consistently with the other Items. Strings are converted to StringItems automatically when they are appended to a Form. These kinds of StringItems have null labels. When an Item that was appended as a String is retrieved from a Form, it is returned as a StringItem.

Continuing the example started in Section 9.4, "Form," the following code illustrates how to add a new StringItem to the Form:

// Note: 'getImageName' is application-specific
String imageName = getImageName();
String si = new StringItem("Photo name:",
                           imageName);
form.append(si);

When a sequence of StringItems is displayed, the text is concatenated and wrapped to as many lines as needed. This has the effect that sequential StringItems are displayed as a paragraph of text. Any newline characters within StringItems are treated as row breaks (see Section 10.9.1, "Row Breaks"). Also, a label may cause a row break either before or after the label, or both. Generally, the label is used as a paragraph title.

Here is an example that illustrates the use of concatenated StringItems:

Form form = new Form("Concatenation");
... // Add Commands and CommandListener
form.append("First");
form.append("paragraph");
form.append("of text.");
Item si = new StringItem("Label", "Another");
form.append(si);
form.append("text paragraph");
form.append("here as an example.");
display.setCurrent(form);

10.2.1 Appearance Modes

The StringItem and ImageItem (see Section 10.3, "ImageItem") classes have an appearance mode attribute that controls the presentation of these items. There are three modes available: PLAIN, HYPERLINK, and BUTTON. By default, the mode is PLAIN in both items. Other modes can be used by creating a StringItem or ImageItem with a specialized constructor that receives an appearance mode argument.

Simply having an item with HYPERLINK or BUTTON appearance mode does not do anything. When either of these modes is used, the application must also add at least one Command to the item. Preferably, the Command is set as the default Command. In addition, an ItemCommandListener must be registered that actually will implement the action for the hyperlink or button.

Here's an example that illustrates the use of the HYPERLINK appearance mode:

Form form = new Form("Appearance");
Command backCommand = new Command("Back",
                         Command.BACK, 1);
form.addCommand(backCommand);
form.setCommandListener(this);

Item link = new StringItem(null, "link",
                         Item.HYPERLINK);
Command linkCommand = new Command("Go",
                         Command.ITEM, 1);
link.setDefaultCommand(linkCommand);
link.setItemCommandListener(this);

form.append("Follow this ");
form.append(link);
form.append(".");

Note that the linkCommand variable in the above code is set to the link StringItem whereas the backCommand variable is set to the entire Form. This means that the linkCommand operation is only accessible when the user is manipulating the link item. In other words, the presence of the linkCommand operation is context-sensitive.