Text Wrapping in MIDP

When long pieces of text are displayed on the small screens of cell phones and other small devices, they often "wrap to the next line," and this behavior can reduce the usability of wireless Java applications. Differences in screen size and wrapping behavior can cause handheld devices to break text in different places, creating unpredictable fragmentation of text.

This variability can cause problems. The user may not be able to tell whether the lines are parts of the same element, or two independent elements. The uncertainty is confusing in itself - and can lead to worse problems. If the application treats each line of text as a separate element, but the user assumes that the split is merely an artifact of text wrapping, subsequent behavior may be mystifying. For example, suppose the application splits the email address qmahmoud@javacourses.com into two lines, qmahmoud@javacours and es.com. If the application doesn't preserve the original string, it has an invalid email address. The flaw is not obvious, and may cause a problem only much later, when the user tries to send mail to the bad address.

Version 2.0 of the Mobile Information Device Profile (MIDP) enhances text wrapping in several ways. This tech tip provides some hints and guidelines on handling text wrapping in MIDP.

Recognizable Item Boundaries

MIDP provides several user-interface components, some of which wrap text automatically. For example, multiple-choice items include a checkbox at left and wrap text neatly, with a hanging indent. Implicit action items wrap and indent text the same way, with an arrow button in place of a checkbox. The List component, however, is not as helpful. Consider the following fragment of code, which uses a List to create a menu of choices:

List choices = new List("Method of Payment", Choice.IMPLICIT);
choices.append("Choice Number One", null);
choices.append("This is a really long long long long long choice", null);
choices.append("Choice Number Three", null);
choices.append("Choice Number Four", null);

As Figure 1 shows, on a typical device the second choice is likely to span two lines:

Figure 1. How Many Choices?

If the user selects the second choice, the text wrapping becomes clear, as Figure 2 shows:

Figure 2. Implicit Selection

Note this implication, however: To be sure which lines belong to which choices, and thus to be clear about the choices available, the user would need to move up and down the list. Not exactly friendly interface.

If a string of text is likely to wrap to multiple lines, you should make it clear that the second and subsequent lines are parts of the same element, and do not represent new items. If you are providing the user with a set of items, some of which may wrap to multiple lines, be sure the user can see the start of each item. One way is to add a graphic to the left of the item, and indent any wrapped text - which, conveniently, the Choice.EXPLICIT list type does for you, as Figure 3 shows:

Figure 3. Explicit Selection

Item Layout in Forms

Enhancements introduced in MIDP 2.0 offer developers more control over the appearance of their applications. MIDP now provides a more formal layout policy for arranging components within a Form. You can request that components be left-aligned, right-aligned, or centered. The Choice interface now has better text-wrapping behavior. The developer can hint to the application how to handle text that exceeds the screen width by invoking the method setFitPolicy(int fitPolicy), where fitPolicy can be one of the following values:

TEXT_WRAP_DEFAULT: No preference as to how text is displayed; the implementation will exhibit its default behavior.

TEXT_WRAP_ON: Text will extend over multiple lines if necessary.

TEXT_WRAP_OFF: No wrapping or truncation; long lines of text will be clipped.

Controlling Item Sizing

In addition, several minor changes have been made to the Item class. For example, each Item has a preferred and minimum size that's based on its contents, label, and layout policy. The minimum size includes just the essentials to display the Item; the preferred size eliminates any clipping, and word-wrapping is kept to a minimum. Some of the new methods to help you work with Item sizes include:

setPreferredSize(int width, int height)
getPreferredHeight()
getPreferredWidth()
getMinimumWidth()
getMinimumHeight()

The setPreferredSize() is an interesting method, as it allows you to lock the width of an Item, or its height, or both. For example, you can choose to keep one dimension at a particular size by passing that number of pixels, and have the application compute the other dimension by passing -1, which is used to unlock the width or height.

Finally, here are some guidelines to keep in mind regarding text wrapping:

Remember that your applications will be running on devices from different vendors that have different display sizes.

Make text easier to read by starting new lines at familiar line breaks, or on word boundaries.

When working with items that are long strings, ensure that the user will find it easy to see the start of each item.

Use the enhanced APIs of MIDP 2.0 where you can, but keep your applications backward-compatible with MIDP 1.0.

For more information

- JSR 118: MIDP 2.0
- Wireless BluePrints

About the author

Qusay H. Mahmoud provides Java consulting and training services. He has published dozens of articles on Java, and is the author of Distributed Programming with Java (Manning Publications, 1999) and Learning Wireless Java (O'Reilly, 2002).