Overview  Package  Class  Use  Tree  Deprecated  Index  Help 
JSR-209 (Proposed Final Draft 2)
 PREV   NEXT FRAMES    NO FRAMES    

Advanced Graphics and User Interface Optional Package Specification (JSR-209), revision 060413

This is the specification of the Java 2 Micro Edition (J2ME) Advanced Graphics and User Interface, version 1.0.

See:
          Description

Packages
java.awt Contains all of the classes for creating user interfaces and for painting graphics and images.
java.awt.font Provides classes and interface relating to fonts.
java.awt.geom Provides the Java 2D classes for defining and performing operations on objects related to two-dimensional geometry.
java.awt.image Provides classes for creating and modifying images.
java.nio Defines buffers, which are containers for data, and provides an overview of the other NIO packages.
javax.imageio The main package of the Java Image I/O API.
javax.imageio.event A package of the Java Image I/O API dealing with synchronous notification of events during the reading and writing of images.
javax.imageio.metadata A package of the Java Image I/O API dealing with reading and writing of images
javax.imageio.stream A package of the Java Image I/O API dealing with low-level I/O from files and streams.
javax.microedition.agui.event Provides classes and interfaces including functionality specifically related to user interface events in the Advanced Graphics and User Interface Optional Package Specification.
javax.microedition.plaf Provides the basis for the implementation of Swing pluggable look-and-feel capabilities for JSR-209.
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.border Provides classes and interface for drawing specialized borders around a Swing component.
javax.swing.event Provides for events fired by Swing components.
javax.swing.plaf Provides the basis for the implementation of Swing pluggable look-and-feel capabilities for JSR-209.
javax.swing.table Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.tree Provides classes and interfaces for dealing with javax.swing.JTree.
javax.swing.undo Allows developers to provide support for undo/redo in applications such as text editors.

 

This is the specification of the Java 2 Micro Edition (J2ME) Advanced Graphics and User Interface, version 1.0.

Introduction

The Advanced Graphics and User Interface (AGUI) Optional Package migrates many of the core APIs for advanced graphics and user interface facilities from the J2SE(tm) platform to the J2ME(tm) platform. These facilities include much of the functionality from Swing, Java 2D Graphics and Imaging, and Image I/O. Applications can use this functionality to develop advanced applications for consumer devices such as mobile terminals and home devices.

For the purposes of the Public Review Draft version of the specification we will identify the areas of the specification with specific restrictions over the corresponding J2SE classes in the overview. All other changes or restrictions will be noted in the overview.

JSR-209 Specification Draft: Note to the Reader

Disclaimer

This is a draft of the specification for JSR-209. As such, it represents a work in progress; therefore, the details of this draft are subject to change before the final release. However, this draft represents the Proposed Final Draft stage of the specification and it is expected that the differences between this draft of the specification and final release will be small.

Feedback

Your feedback is appreciated. Please send comments and corrections to jsr209-review-comments@sun.com. 

General Requirements

Relationship to Other J2ME Profiles and Optional Packages

The Advanced Graphics and User Interface (AGUI) 1.0 Optional Package is an extension of either Personal Basis Profile (JSR-217) or Personal Profile (JSR-216). All the programming interfaces included in JSR-209 are subsets of the those included in Java 2 Standard Edition version 1.4.2 (J2SE) except for JSR-209 specific pluggable look and feel API and device keys interface.

Required Packages

Implementations of JSR-209 can be deemed compliant in two ways:
  1. Java 2D for Java ME Optional Package
  1. Advanced Graphics and User Interface Package 

Image Formats

Implementations of JSR-209 must support the following image file formats:

Restrictions applied to JSR-209 implementations

Implementations of the Advanced Graphics and User Interface Optional Package exhibit certain restrictions relative to the Java 2 Platform, Standard Edition (J2SE). Many of the packages and classes of this Optional Package are subsets of their full counterparts in J2SE. Additionally, the semantics of the following APIs are subject to mandatory and optional restrictions:

For each optional restriction, an implementation of this Profile describes its behavior by means of a system property.

Considerations for Implementation on Personal Basis Profile and Personal Profile

Support for Native Toolkits

Some members of the Java Community wish to support this specification on a native toolkit. Specifically, this would involve replacing some or all of the traditional Java programming language based rendering engine in the pluggable look and feel implementation for the Swing user interface toolkit with either a native rendering implementation of pluggable look and feel, or perhaps thin wrappers on a native user interface toolkit. This approach may yield a number of benefits including fidelity with native applications, reduced memory usage, reduced static footprint, and higher performance. The approach taken is left to the implementor. There are a number of areas within the Swing API that imply the use of Java programming language renderers and it is the desire of the EG to restrict the portions of the specification where these implications are found in order to simplify the implementation of JSR-209 on native toolkits as well as continue to allow a traditional (Java programming language rendered) implementation of the Swing user interface toolkit. The following restrictions were added to the spec to support native toolkits:

Pluggable Look and Feel

The pluggable look and feel api in JSR-209 architecture represents a slightly modified version of the pluggable look and feel (referred to as micro-PLAF) included in Java 2 Standard Edition.  The goals of the pluggable look and feel architecture are as follows:
 JSR-209 is NOT trying to provide J2SE compatibility for look and feel implementations:
 The JSR-209 pluggable look and feel API is divided into 2 packages:

Serialization support in JSR-209

Serialization in the JSR-209 specification is as defined in Java SE 1.4.2. The javax.swing package (and sub-packages) do not include serialized forms and additionally the serialized form of a class is not guaranteed to be compatible with future releases of this specification (as is noted in the class description of each effected class). 

Mixing of Lightweight and Heavyweight User Interface Components

The Java platform includes the notion of heavyweight (AWT Peer Based) and lightweight (not AWT Peer Based) user interface components. Developers are generally discouraged from the mixing of heavyweight and lightweight components in their applications.  JSR-209 can be supported on either JSR-217 Personal Basis Profile 1.1 (enough of the AWT package to support Lightweight Components) or JSR-216 Personal Profile 1.1 (full support for AWT Heavyweight Components). Although Personal Basis Profile includes no support of heavyweight user interface components Personal Profile does, JSR-209 contains no heavyweight components.  Developers of applications using JSR-209 are encouraged to understand the limitations of mixing of component types  in environments where it is possible. The article "Mixing heavy and light components" serves as an informative reference. 

Usage of JList in JSR-209

Unlike the Swing user interface toolkit in J2SE, implementations of javax.swing.JList are not guaranteed to support custom cell renderers. In other words a call to javax.swing.JList.setCellRenderer() may be ignored. The minimal guaranteed behavior of a JSR-209 implementation of  JList with respect to Cell Rendering is as follows:
Description of the JList Specification in JSR-209
In JSR-209 there is a strong desire to implement a large part of the Swing api on top of native toolkits for performance and compatibility reasons.  One of the biggest issues with this approach is the render style api's where a arbitrary component is used as a rubber stamp to paint cells. This style of api is currently provided by the following ListCellRenderer TableCellRenderer and TreeCellRenderer. This type of functionality is impossible to implement within the constraints of many native toolkits. In JSR-209 we have made the implementation of these renderer's optional and only require that at a minimum the toString method of the data in the data model is usable as a visual text only representation of the cell. Although this approach is fine as a default, most of the native toolkits are capable of handling more complex cell types in particular, an image and text string or both. Thus we propose an additional api be made available to better support traditional or native widgets that list data by providing a interface for the data that can provide optional image and string information to the native widget for more advanced drawing without requiring full support for the CellRender api. These interfaces map well to traditional native toolkits allowing more advanced optimized cell rendering.

The similar CellEditor interfaces would not be supported by this approach.

The proposed interface is similar to the existing CellRender API.

Here are the three proposed data interfaces:

 
	public interface ListCellData {
 		Icon getIcon( boolean isSelected, boolean cellHasFocus );
 		String getText( boolean isSelected, boolean cellHasFocus );
	}

	public interface TableCellData extends ListCellData {
 		//No new methods
	}

	public interface TreeCellData {
 		Icon getIcon( boolean isSelected, boolean expanded, boolean cellHasFocus );
		String getText( boolean isSelected,boolean expanded, boolean cellHasFocus );
	}

Usage of Borders In JSR-209

The Swing API allows the developer to set the Border object on each JComponent.  The Border object may be one of the standard Border classes or it may be a custom Border provided by the developer. 

Border usage on custom components is not problematic since they are implemented by the developer in Java, and therefore not subject to the constraints of an underlying toolkit.  However, for standard components (i.e. those defined in the specification and implemented in native code), border effects are implicitly limited to those provided by the toolkit.  In the interests of maintaining a consistent look and feel throughout the application, it is recommended that Border behavior for developer-defined components follows that of the standard components.

In a pure Java implementation of Swing, classes implementing the Border interface embody code that renders various border styles.  However, when running on top of a native toolkit, those classes can only represent attributes that may be set on a component in the native toolkit.  As a result, Border classes having open-ended functionality cannot be supported since a static mapping to native component attributes would be impossible.  Specifically, custom Border classes, CompoundBorders, and visual settings (e.g. width, color, etc.) may not be fully supportable.

Native toolkits vary widely in terms of their support for various border styles.  However, Borders do play an important role from a usability perspective, and enabling their use for that purpose is the driving factor in determining the minimum set that must be supported.  To that end, all implementations must ensure that the following borders are visually distinct and rendered in a manner that is consistent with their descriptions:
 Note that there is no requirement for differentiation within the hierarchies of each of these classes.  For example, SoftBevelBorder may look like a BevelBorder if not supported by the toolkit.

Furthermore, the following Borders should mimic the appearance of a LineBorder if the implementation does not distinctly support them:
 CompoundBorders may be applied to standard components, however the implementation may choose to ignore the inside border if compound borders are not fully supported by the toolkit.  That is, the component will appear as though its border has been set to just the outside border.  In the case of nested CompoundBorders, the chain of outer borders is traversed until a suitable Border class is reached.

If the requested Border class is not supported by the implementation, the JComponent’s getBorder method will return an instance of the actual Border that is being displayed instead.

Some Border classes include various settings that tweak their appearance and size.  Examples include thickness, color, corner rounding, shadow effects, etc.  Such settings also present difficulties when mapping to a limited set of border attributes in a native toolkit.  Therefore, such settings may or may not be honored by the implementation.  In either case, getter methods will correctly report the values that were requested by the developer.

Border metrics such as insets must be accurately reported to reflect the size of the border as rendered.  For example, if a LineBorder is only supported for a thickness of 1 pixel, its insets should reflect that of a 1 pixel border regardless of the thickness that has been specified.
JComponent Appearance Settings
In addition to borders, other attributes of a JComponent may be set by the developer to alter its appearance.  Such attributes also present complications for native toolkits, especially if the native components are rendered using bitmap skins instead of drawing primitives.

Therefore, an implementation is not required to honor the background and foreground colors of a standard component, although getter methods will return the color that was requested by the developer.

Implementations are required to honor the Font that has been set for any component.  Due to its dynamic nature, text must be rendered using drawing primitives, and therefore it is a reasonable assumption that a native toolkit can be configured to use the appropriate font when rendering text for a component.

The following classes in JSR-209 are effected by these restrictions:

The Swing Paint Algorithm

A number of restrictions to the Swing paint algorithm to provide better support of native rendering pipeline implementations of JSR-209.

Double Buffering

Implementations of JSR-209 perform double buffering by default on user interface components which are subclasses of javax.swing.JComponent. Applications can query whether double buffering is active by calling JComponent.isDoubleBuffered(). Applications can attempt to make a user interface component single buffered by calling JComponent.setDoubleBuffered(boolean) however the system is allowed to ignore that request. User interface components that are subclasses of java.awt.Component (and not javax.swing.JComponent) will not be double buffered by default.

Methods paint() and paintComponent() in Standard Swing Components

UI Toolkits, particularly on consumer and home devices may provide less flexibility than either UI Toolkits in desktop operating systems, or the Java programming language rendered UI toolkit found in J2SE. As such, the JSR-209 specification must conform to these restrictions by limiting the ability of applications to render on all top level Swing UI components. The Swing paint algorithm provides four entry points allowing the rendering of graphics on UI components, paint(),  paintComponent(), paintBorder(), and paintComponents(). In JSR-209 paint() (and related paint and print methods) have been made final to disallow the overriding of the paint mechanism on native components by applications. This change was made to facilitate implementation of JSR-209 on native toolkits and clarify implementation specific painting behavior. To summarize:

The following methods are to be marked final at the first concrete subclass encountered when going down the JComponent hierarchy:
The following method needs to be marked final on JComponent itself:
The following methods should not be modified:
JSR-209 is intended to present the high level Swing API's to allow optimized tight integration with the underlying platform. The Java2D drawing API and customization capabilities of Swing are limited to direct user subclasses of JComponent and JPanel. This allows the application programmer nearly the full API for developing custom components while also allowing the platform provider to tightly integrate the default advanced Swing widgets with the platform.

Achieving these goals has resulted in a number of restrictions on the APIs that are available in the Swing user interface toolkit. In particular the ability to paint on a concrete Swing widget such as JLabel and JButton is curtailed to allow native implementation. To this end most of the paint methods
have been finalized throughout the Swing user interface toolkit.  The biggest impact will be on developers who wish to override these methods to do
lightweightui implementation or altering of the look and feel (at the component level). Since the Pluggable Look and Feel support has already been removed, finalization of the paint methods is simply additional work needed to ensure that Swing can be easily and tightly integrated with the host platform.  JSR-209 is not intended to support the traditional pluggable look and feel architecture and the entire Java programming language paint model from J2SE. Instead JSR-209 defines a pluggable look and feel architecture similar to the Java SE model, yet provides more flexibility to implementations. JSR-209's primary aim is to provide as much of the commonly used high level API and Java 2D functionality to the application programmer on smaller platforms.

The one exception is that the paintChildren() method is not marked final. We feel that it is possible to optionally support painting via Java 2D after a
component is rendered on most platforms.

Thus the user should be able to code the following and get the desired results on most platforms
public void paintChildren( Graphics g ) {
    super.paintChildren(g); //must be first !!
    //do custom code here.
}
Why is paintChildren still available?
The platform must support user drawn non-opaque JPanels. So the implementor needs to support the concept of a JPanel overlapping
potentially native components. Drawing in this overlapped panel is equivalent to painting at the tail of the paintChildren() method and in fact the paintChildren() method could be implemented via the use of a temporary overlapped JPanel.  Thus although some platforms may choose not to support this method there seems to be no overriding reason not to.

Possible implementation:
JPanel temp = new JPanel();
temp.setBounds(getBounds());
getLayeredPane().add(temp);
Graphics g = PrivateAPI.getGraphics(this);
paintChildren(g);
g.dispose();

//remove the temp component without repaint
PrivateAPI.removeNoPaint(temp);

Special Considerations for J2ME Devices

This section enumerates some of the considerations made in JSR-209 for small devices

Swing Client Properties for Input Constraints

This section describes Input Constraints for JSR-209. This specification was adopted from the Mobile Information Device Profile Specification version 2 (MIDP version 2, JSR-118) and assist the user in entering text. This functionality is intended to improve the usability of JSR-209 on devices where the primary mode of input is a keypad.

The text component (javax.swing.text.JTextComponent) in JSR-209 may implement the following input constraints originally described in MIDP version 2. These input constraints assist the user in entering text and allow an application to request that the user's input be restricted in a variety of ways. The text displayed in a text component may differ from the text accessible via the  API's (for instance a phone number may include formatting information in the display but not in the String returned by a call to TextComponent.getText())Applications may indicate a hint to a JSR-209 implementation interested in using these input constraints by setting the client property via the Client Property mechanism as described by putClientProperty(java.lang.Object key, java.lang.Object value). If an application requests a mode that is NOT supported, the implementation may choose to ignore the request. In JSR-209 a text component MAY support the following properties:

Key

Value

Numeric Value

Description

INPUT_CONSTRAINT

ANY

0

The user is allowed to enter any text.

INPUT_CONSTRAINT

EMAILADDR

1

The user is allowed to enter an e-mail address.

INPUT_CONSTRAINT

NUMERIC

2

The user is allowed to enter only an integer value.

INPUT_CONSTRAINT

PHONENUMBER

3

The user is allowed to enter a phone number.

INPUT_CONSTRAINT

URL

4

The user is allowed to enter a URL.

INPUT_CONSTRAINT

DECIMAL

5

The user is allowed to enter numeric values with optional decimal fractions, for example "-123", "0.123", or ".5".


Introduction of Device Specific Keys into JSR-209

The current set of keys defined in the Personal Basis Profile reflects the set of keys typically found on desktop computers.  However, given the intention of using this profile for consumer and embedded devices, the set of keys that needs to be represented is not always covered by the existing codes.

In existing uses of desktop-centric toolkits, the issue of device-specific keys has been typically addressed by re-using an existing key code for the device-specific code.  For example, the 'Send' key on a wireless phone could be represented using VK_F4.  In addition to being manufacturer/product specific, this arrangement is also problematic if a newer version of the product includes the key that was re-used.  For example, if a new version of the phone is developed with a full keyboard, it may actually include an F4 key.  In terms of promoting interoperability and application portability, this arrangement is clearly sub-optimal.
Target Devices
Since JSR-209 is specifically targeted at the consumer/embedded space, it is appropriate for this specification to define additional key codes that cover the keys that are typically found on the target devices.  The set of keys to be defined should cover a range of devices including:
 In addition to making the API more appropriate for these devices, a standard set of key codes will promote application portability across manufacturers and even across device types.  Historically, each type of device has included its own set of keys; however, given the current convergence between computers, phones, and other consumer devices, the existence of a common set of keys would be extremely useful.

Existing Standards
This area has been partially addressed by other standards groups such as HAVi (Home Audio Video Interoperability, www.havi.org), but those standards have typically focused on a narrower range of devices.  The intention for JSR-209 is to leverage existing standards wherever possible and build upon them to provide a more complete set of key codes that covers a wider range of devices.
Key Codes
JSR-209 has defined a subclass of the class java.awt.event.KeyEvent in order to supplement the Java SE defined key codes with key codes normally found in consumer and home devices. See javax.microedition.agui.event.DeviceKeyEvent for more information.

Support for device "Soft Keys" in JSR-209

Many consumer and home devices include programmable soft keys which can be programmed by an application. An example of soft keys can be found on many mobile phones which have a hardware button that can be mapped to different functions as the context of an application changes. In order to support this functionality within the JSR-209 specification the JSR-209 EG has added optional behavior to the the JMenuBar class to support this feature.

Initial Focus Owner Recommended Practice

Applications implemented using JSR-209 should programatically select the initial  focus owner (java.awt.Component.requestFocus() ) to ensure that a  sensible focus owner has been selected. Applications deployed on devices which do  not include hardware support for a pointing device (such as a mouse, trackball or  touch screen) may be difficult to use if no initial focus owner is explicitly selected  so an implementation may choose a component to be the initial focus owner.  Should an implementation wish to choose an initial focus owner, the following  behavior should be observed:

Clarifications to JSR-209 Classes

  1. Clarifications on the use of the method setMnemonic(). Applications may test if these clarifications of the setMnemonic() method are in force by testing the value of a system property.
    2.

 Overview  Package  Class  Use  Tree  Deprecated  Index  Help 
JSR-209 (Proposed Final Draft 2)
 PREV   NEXT FRAMES    NO FRAMES    
Java and Java 2D are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
Copyright 1993 - 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All Rights Reserved.
Use of this specification is subject to this license.