The Java ME GUI APIs at a Glance

Print-friendly Version

When Java ME technology started in 2000 (back then it was called J2ME) there weren't many choices available for developers for graphical API at that time. In fact, the only API that was available was the standard LCD user interface packages of javax.microediation.lcdui of the Mobile Information Device Profile (MIDP). At that time, MIDP was only at version 1.0, and there weren't any tools available like the Sun Java Wireless Toolkit, Netbeans Mobility Pack, or Websphere Device Developer. Now, with so many graphical Java ME APIs available today, mobile developers have a different problem: API overload. Today, the current and upcoming APIs of the mobile Java platform allow you create a wide array of user experiences ranging from vector graphics manipulation to 3D object rendering. Did you know that certain Java SE applications (even with a Swing user interface) can run on some mobile devices? Did you know that the JCP (Java Community Process) has standardized multiple APIs for 3D object rendering? Are you familiar with the upcoming graphical capabilities of the MIDP 3.0 API? The purpose of this article is take a snapshot of the graphical APIs of the Java ME platform that are currently available and under specification. I'm going to cover both configurations of Java ME (CLDC and CDC) and discuss what will be available in the near future, like the much anticipated MIDP 3.0 API. I'll start things of by looking first at the profiles built upon the Java ME configurations, and then discuss the many optional packages that are built upon them. In this article, we're going to take a look at the following APIs:

• MIDP 1.0 (JSR-37)
• MIDP 2.0 (JSR-118)
• MIDP 3.0 (JSR-271)
• Personal Basis Profile 1.0 (JSR-129)
• Personal Basis Profile 1.1 (JSR-217)
• Personal Profile 1.0 (JSR-62)
• Personal Profile 1.1 (JSR-216)
• Scalable 2D Vector Graphics 1.0 (JSR-226)
• Scalable 2D Vector Graphics 2.0 (JSR-287)
• Mobile 3D Graphics 1.0 (JSR-184)
• Mobile 3D Graphics 2.0 (JSR-297)
• Java Binding for OpenGL ES (JSR-239)
• Advanced Graphics and User Interface (JSR-209)

A majority of these APIs have been finalized and are available in mobile devices today, but some of them are still under specification in JCP. So now that all the preliminaries are out of the way, let's get started!

With billions of mobile devices running Java ME technology, by far the most common devices are phone handsets running the Mobile Information Device Profile (MIDP). Figure 1, below shows the minimum screen requirements for MIDP 1.0, 2.0, and 3.0 devices and provides relative sizes for comparison purposes.

Figure 1: Minimum Screen Requirements for MIDP 1.0, 2.0, and 3.0 Devices

The graphical capabilities of the MIDP 1.0 and 2.0 specifications were designed to support the multi-color displays of today's mobile phones, but also (at a minimum) support two-way pagers or devices with monochrome displays. MIDP 3.0 devices will be geared towards a richer mobile experience, and requires that mobile devices support at least 64k colors. All MIDP implementations support high-level and low-level user interface components. If you're new to Java ME, then that probably didn't mean a lot to you, so let me clarify things. All user interface classes for MIDP devices can be found in the javax.microedition.lcdui package, but the high-level user interface components are subclasses of the Screen and Item classes. Now, by combining the subclasses of Screen and Item, you can create powerful business applications for mobile devices, like the application shown below in Figures 2 and 3.

Figure 2: A simple application using the MIDP high-level APIs shown in the Java ME Wireless Toolkit's Emulator

Figure 3: A simple application using the MIDP high-level APIs shown in the Nokia Series 60 Emulator

One of the major advantages of the high-level API is the fact that high-level GUI components are rendered by the mobile device, thus allowing the device to present the components in an appropriate manner (which could either be native look-and-feel on the handset or something else). Figures 2 and 3 are both running the same application, and as you can clearly see each MIDP implementation rendered the insurance claim application interface differently (you should notice that the image in Figure 3 has a scrollbar, while the one in Figure 2 does not).

All MIDP implementations have and support the usage of the following high-level components:

• Alert (used for showing dialog boxes and warnings)
• ChoiceGroup (used for showing group of checkboxes or radio buttons)
• DateField (used for selecting dates and times)
• Form (used for displaying the subclasses of Item)
• Gauge (used to showing the progress of an operation or process, but it can also be used to represent the percent of a whole)
• ImageItem (used for showing images in high-level UI applications)
• List (used for showing lists and combo boxes)
• StringItem (used for showing simple text strings)
• TextBox (used for entering text)
• TextField (an alternate method used for entering text)

In contrast, the low-level APIs for MIDP applications allow the developer to have greater control of the user interface, and therefore the developer has the responsibility for drawing and rendering the display. The major low-level API classes are Canvas and Graphics, and of course, those classes are better suited for creating gaming applications. Please note that the low-level MIDP API is not exclusively used for gaming applications, and in fact, the 2D and 3D APIs that will be discussed later in this article use the MIDP low-level API for binding to the display. Figure 3 shows a gaming application using the low-level APIs.

Figure 4: The JBricks Game Demonstrating the MIDP low-level APIs

The MIDP 2.0 specification added a bridge between the high-level and low-level APIs: the CustomItem class. MIDP 2.0 also enhanced the capabilities of the low-level APIs by creating the MIDP Game API, javax.microediton.lcdui.game. The Game API includes the GameCanvas class, which is a child of Canvas. In the MIDP 3.0 specification, there have been several additions to the high-level APIs including:

• AnimatedImage (which allows the creation and rendering of animated images)
• FileSelector (a mechanism for browsing directories and selecting files on the file system)
• TabbedPane (a mechanism for creating and displaying a tabbed pane)

MIDP 3.0 also supports the Midlet concurrency (where more than one Midlet can run at the same time, which is a handy feature) and Inter-Midlet Communication (where two concurrently Midlets can communicate with each other).

Although all MIDP versions support the displaying of rasterized images (in PNG format only) MIDP 3.0 finally adds support for GIF images.

The Connected Device Configuration (CDC) was created to address the class of devices that fall in to the following category:

1. a device that has more computing power than a phone (i.e. too big for the CLDC), but
2. has less computing power than a desktop computer (i.e. too small for the Java SE).

So what's a typical CDC device? Well, that's kinda hard to say. The CDC is available for certain high-end mobile phones with the Symbian OS, but it's also available for PDAs and other mobile devices that run the Windows Mobile OS. It's available in certain network access points, but it's also embedded in every Blu-ray Disc player -- and that includes the Sony Playstation 3 game console! So despite the fact that there isn't a "typical" CDC device, the Personal Basis and Personal Profiles were created to provide graphical interfaces for a group of devices that encompasses a broad range of mobile and embedded devices.

The Personal Basis Profile (regardless if you're using version 1.0 or 1.1) incorporates a very small subset of the Java SE Abstract Windowing Toolkit (AWT) libraries. The Personal Basis Profile is very lightweight, so classes for rendering simple UI components like buttons, menus, list, textboxes, scrollbars, etc. have been removed. The Personal Profile (regardless if you're using version 1.0 or 1.1) is almost a complete implementation of the Java SE AWT, and even provides support for applets. So then what's the difference between versions 1.0 and 1.1 of the Personal Basis and Personal Profiles? Version 1.0 of both profiles is based upon the Java SE 1.3 AWT API, while version 1.1 is based upon the Java SE 1.4.2 AWT. Figure 5 shows a simple application based upon the Personal Profile.

Figure 5: An example Golf Score Tracking application using the IBM J9 VM with Personal Profile 1.0

Scalable Vector Graphics (SVG) is an XML-based vector graphics framework. SVG images are vastly different from rasterized (i.e bitmapped) graphics formats like GIF, JPEG, or PNG due to the fact that SVG images are calculated (like a mathematical formula) and displayed rather than pixels placed on a screen. SVG images are scalable, so they are really handy if you need to zoom in for more detail, or zoom out to show more data. SVG images are stored as XML documents, and that brings along several advantages, namely, you can modify them programmatically simply by changing fields within the XML tags. Being XML documents, it also makes it pretty easy to search for text embedded within the image, which is currently pretty difficult for rasterized images. SVG supports animation and transformations, and you can imagine it being a W3C standardized version of Adobe Flash, but based upon XML rather than Adobe's proprietary format.

Figure 6 depicts a simple SVG weather image that I created using the Beatware Mobile Designer 2.0.

Figure 6: A screenshot of an SVG image showing the local weather

The XML needed to create the image shown in Figure 6 is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Generator: Mobile Designer 2 2.0 -->
<svg width="300" height="208" viewBox="-212 -104 300 208" stroke-miterlimit="2"
	xmlns="http://www.w3.org/2000/svg"
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xml:space="preserve" version="1.1" baseProfile="tiny">
 
<!-- Scene 1 -->
<g id="Scene_1">
	<rect x="-88" y="-104" width="175" height="29.99" fill="#a8b5b5" stroke="#000" stroke-width="2" stroke-linecap="round"/>
	<text x="-76.87" y="-82" font-size="18" font-family="Verdana" font-weight="bold" fill="#e6e4a7">Local Weather</text>
	<text x="-79" y="-58" font-size="12" font-family="Verdana" fill="#5172b7">location:</text>
	<text x="-39" y="-27" font-size="12" font-family="Verdana" fill="#384f7f">Current conditions</text>
	<text x="25" y="24" font-size="12" font-family="Verdana" fill="#f00">Sunny</text>
	<text x="25.15" y="2" font-size="12" font-family="Verdana" fill="#f00">75 F</text>
	<text x="-39" y="24" font-size="12" font-family="Verdana" fill="#384f7f">Visibility:</text>
	<text x="-40.01" y="48" font-size="12" font-family="Verdana" fill="#384f7f">Humidity:</text>
	<text x="23.98" y="48" font-size="12" font-family="Verdana" fill="#f00">45%</text>
	<text x="-40" y="2" font-size="12" font-family="Verdana" fill="#384f7f">Temp:</text>
	<text x="-10" y="77" font-size="9" font-family="Verdana" fill="#c00">last update: 4:15pm </text>
	<text x="-22.66" y="-58" font-size="12" font-family="Verdana" fill="#384f7f">Joplin, MO 64804</text>
 
</g>
 
</svg>

Now that some of the mystery of SVG has been dispelled, you should know that the SVG specification is divided into profiles. The SVG profiles serve the same purpose as Java ME specification's profiles: to provide a richer experience for more capable devices/platforms, but also provide basic functionality for limited devices/platforms. The current SVG profiles are:

• SVG Standard (the full-fledged version for desktops)
• SVG Basic (a smaller subset intended for PDAs)
• SVG Tiny (a reduced subset intended for mobile phones)

Both SVG Basic and SVG Tiny are classified as SVG Mobile Profiles. The Scalable 2D Vector Graphics API version 1.0 (JSR-226) defined the javax.microedition.m2g package and was created in order to fully support the SVG Tiny 1.1 profile. This optional package needs floating point support, so it can only run on CLDC 1.1 or CDC virtual machines. The API is pretty small, and if only defines four classes:

• ScalableGraphics (the fundamental class for rendering SVG images)
• ScalableImage (a class that represent images in vector format)
• SVGAnimator (a class that's used for animations)
• SVGImage (a class the represents an SVG Tiny 1.1 image)

Now version 2.0 of Scalable 2D Vector Graphics API (JSR-287) is intended to fully support SVG Tiny 1.2, and defines 5 packages and over 20 classes. The packages in the Scalable 2D Vector Graphics 2.0 API are:

• javax.microedition.m2g
• javax.microedition.vectorgraphics
• org.w3c.dom
• org.w3c.dom.events
• org.w3c.dom.svg

Version 2.0 of the specification is designed to provide a richer user experience, and incorporate video, as shown in Figure 7.

Figure 7: An example SVG application with embedded video using the Scalable 2D Vector Graphics 2.0 API 2.0 (source: JSR-287 API documentation)

The Mobile 3D Graphics API (JSR-184) version 1.0 was the first standardized Java ME API for 3D graphics development. This API defined the javax.microedition.m3g package and was intended to support wide range mobile devices, even those that could not support floating point mathematics, i.e. CLDC 1.0. The API was designed to address several use cases including gaming, map visualization, and product visualization. The Mobile 3G Graphics 1.0 API supports scene graph mode (i.e. high-level) and also immediate mode (i.e. low-level). The API includes support for a single camera (i.e. your point of view in the 3D viewing area) with fog, light, meshes, and materials. One of the most important features of the API is its ability to load external 3D models and scenes composed from 3rd party tools, such as 3ds Max or Bryce. These external applications must support the m3g file format, as defined in the JSR-184 specification. Figure 8 shows one of the sample 3D application in the Sun Wireless Toolkit.

Figure 8: An example 3D animation using the Mobile 3D Graphics 1.0 API

OpenGL and its mobile subset, OpenGL ES, are both extensible, standardized, and cross-platform 3D APIs. The Java Binding for OpenGL ES API (JSR-239) was designed to be a subset of its Java SE counterpart (JSR-231). OpenGL ES specification is also divided into profiles (like the Java ME and SVG specifications). Two profiles are:

• Common Profile (which provides support for floating point numbers)
• Common-Lite Profile (has no support for floating point numbers)

The Java Binding for OpenGL ES API implements the OpenGL ES Common profile version 1.0 and 1.1, and defines two new packages:

• javax.microedition.khronos.egl
• javax.microedition.khronos.opengles

Unlike the Mobile 3D Graphics 1.0 specification, the Java Binding for OpenGL ES API supports floating point operations, which makes this API exclusively for CLDC 1.1 devices. Additionally, this API does not support the m3g file format defined in the Mobile 3D Graphics 1.0 specification. Figure 9 shows a sample application using the Java Binding for OpenGL ES API.

Figure 9: An example 3D animation using the Java Binding for OpenGL ES API

Now, the final 3D API under the auspices of the JCP is the Mobile 3D Graphics 2.0 API (JSR-297), i.e. M3G 2.0, and below is a list of the goals of the M3G 2.0 JSR:

• The new JSR must completely supercede or subsume JSR-184
• Fragmentation of the M3G platform must be minimized
• Most OpenGL ES 2.0 and 1.1 features should be exposed

The M3G 2.0 specification will be designed to allow for implementations of the specification on mobile devices that includes OpenGL ES graphics hardware, as well as on devices without any graphics hardware, i.e. just a pure OpenGL ES 1.1 software implementation. The M3G 2.0 API should add additional functionality and bridge the gap between the two currently defined 3D graphics libraries for the Java ME platform.

The Advance Graphics and User Interface (JSR-209) API is the long-awaited solution for developers who are working with CDC-based implementations, and are trying to port Java Swing applications or frameworks to the Java ME platform. The AGUI API is dependent upon the CDC 1.1, Foundation Profile 1.1, and Personal Basis Profile 1.1. The AGUI API provides implementations for the following packages:

• java.awt
• java.awt.font
• java.awt.geom
• java.awt.image
• java.nio
• javax.imageio
• javax.imageio.event
• javax.imageio.metadata
• javax.imageio.stream
• javax.microedition.plaf
• javax.microedition.agui.event
• javax.swing
• javax.swing.border
• javax.swing.event
• javax.swing.plaf
• javax.swing.table
• javax.swing.text
• javax.swing.undo

Now, you should note that the AGUI optional package doesn't provide you with a complete implementation of the Swing API provided in Java SE 1.4.2. For instance, you can only have one JFrame at a time, so be sure to check with the release notes for AGUI to understand all of it's limitations. Figure 10 depicts the AGUI API running the quintessential SwingSet application. You should notice the tabbed panes, internal frames, scrollbars, menus, menu items, and icons.

Figure 10: The standard SwingSet application using the AGUI library running in the Sun Java Toolkit 1.0 for CDC

Hopefully this article provided you with a simple way to get up to speed on all the graphical capabilities of the Java ME platform. Figure 11 provides a handy reference for all the Java ME graphical APIs.

Figure 11: A Summary of the Java ME Graphical APIs

Please stay tuned for another article providing hands-on examples with some of the more popular API for Java ME CDC and CLDC!