Overview  Package  Class  Use  Tree  Deprecated  Index  Help 
back to j2megame.org
 PREV   NEXT FRAMES    NO FRAMES    

Advanced Graphics and User Interface (AGUI) Optional Package for Java Platform, Micro Edition (JSR-209), revision 060920

This is the specification of Advanced Graphics and User Interface (AGUI) Optional Package for the Java Platform, Micro Edition, 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 This package provides a typesafe enumeration for byte-order; either big-endian or little-endian.
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 AGUI provides a Pluggable Look and Feel architecture, similar to that which is defined in Java SE (from which AGUI is subset).
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 AGUI.
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 Advanced Graphics and User Interface (AGUI) Optional Package for the Java Platform, Micro Edition, version 1.0.

Introduction

The Advanced Graphics and User Interface (AGUI) Optional Package for the Java Platform, Micro Edition version 1.0 (also referred to as AGUI in this specification) Optional Package migrates many of the core APIs for advanced graphics and user interface facilities from the Java Platform, Standard Edition (tm)  to the Java Platform, Micro Edition (tm). 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 this specification we will identify the areas of the specification with specific restrictions over the corresponding Java Platform, Standard Edition classes in the overview. All other changes or restrictions will be noted in the overview.

AGUI Specification: Note to the Reader

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 AGUI specification must be used in conjunction with a Java ME Profile with at least the capabilities of Personal Basis Profile, version 1.1 (JSR-217). All the programming interfaces included in AGUI are subsets of the those included in Java 2 Standard Edition version 1.4.2 (J2SE) except for AGUI the specific pluggable look and feel API and device keys interface.

Required Packages

Implementations of AGUI 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 AGUI must support the following image file formats:

Restrictions applied to AGUI implementations

Implementations of the AGUI specification 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

AlphaComposite
Xlet Management Single-Frame Restriction on Personal Basis 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 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 AGUI 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 AGUI architecture represents a slightly modified version of the pluggable look and feel (referred to as micro-PLAF) included in J2SE.  The goals of the pluggable look and feel architecture are as follows:
 AGUI is NOT trying to provide J2SE compatibility for look and feel implementations:
 The AGUI pluggable look and feel API is divided into 2 packages:

Serialization support in AGUI

Serialization in the AGUI specification is as defined in JavaTM 2 Platform, Standard Edition, v 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.   Note that AGUI may be used in conjunction with a Java ME Profile that includes heavyweight components (such as Personal Profile, JSR-216).  Developers of applications using AGUI are encouraged to understand the limitations of mixing of component types  in environments where it is possible. (See the article "Mixing heavy and light components" for more information.)  In addition, Swing components should always have a Swing container as their parent, rather than java.awt.Frame.  Placing Swing components in a non-Swing top-level container may cause unexpected results.

Usage of JList in AGUI

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 AGUI implementation of  JList with respect to Cell Rendering is as follows:
Description of the JList Specification in AGUI
In AGUI 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 AGUI 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.

Usage of Borders In AGUI

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 implemented on native toolkits,  (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.



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.

 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. In these cases the appropriate system property can be set indicating that the implementation may approximate the defined appearence of a border.
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.

An implementation is not required to honor the background and foreground colors of a standard component, but getter methods should 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 AGUI are effected by these restrictions:

Restrictions on Tooltips in AGUI

In the Java SE specification from which the AGUI specification is derived, the tooltip functionality is flexible and featureful. A full tooltip system is not appropriate for all mobile devices so this part of the specification has been subset providing a mechanism to allow implementations to attach a text string to a JComponent which may be used by an AGUI implementation to provide additional information to a user. A system property has been defined to allow implementations to indicate if they support this functionality. The following methods are used to get and set the tooltip:

Restrictions on the use of setMnemonic()

Restrictions on the use of the method setMnemonic(): Applications may test if these restrictions of the setMnemonic() method are in force by testing the value of a system property.

Restrictions on the use of setFocusAccelerator()

Restrictions on the use of the method setFocusAccelerator(): Applications may test if these restrictions of the setFocusAccelerator() method are in force by testing the value of a system property.

Application Contexts

In order to protect UI elements that are shared between multiple applications, AGUI implementations must prohibit access to resources that belong to a different application context than the calling thread. To accomplish this: See: Methods Affected by Application Context Boundaries

The Swing Paint Algorithm

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

Double Buffering

Implementations of AGUI 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 AGUI 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 AGUI 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 AGUI 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:
AGUI 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.  AGUI is not intended to support the traditional pluggable look and feel architecture and the entire Java programming language paint model from J2SE. Instead AGUI defines a pluggable look and feel architecture similar to the Java SE model, yet provides more flexibility to implementations. AGUI'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 AGUI for small devices

Swing Client Properties for Input Constraints

This section describes Input Constraints for AGUI. 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 AGUI on devices where the primary mode of input is a keypad.

The text component (javax.swing.text.JTextComponent) in AGUI 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 AGUI 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 AGUI 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 AGUI

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 AGUI 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 AGUI 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
AGUI 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 the class description.
DeviceKeyEvent Usage
The class DeviceKeyEvent is a subclass of java.awt.event.KeyEvent and indicates that a keystroke has occurred in a component but can not be described by key codes included in the KeyEvent class.  If key event listener will receives a key event which indicates that the type is VK_UNDEFINED,  the application can then check the type using instanceof to determine if the key event is an instance of DeviceKeyEvent and cast the object to that type. If the event object is of type DeviceKeyEvent, then it represents a keystoke that can not be represented by KeyEvent. The device key code can then be determined by calling DeviceKeyEvent.getDeviceKeyCode().

Support for device "Soft Keys" in AGUI

Many consumer and home devices include 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 some cases these keys can trigger a menu to be presented to a user (soft menu). In order to support soft menu functionality within the AGUI specification the AGUI EG has added optional behavior to the the JMenuBar class to support this feature.

Relationship between "Softkeys" and "Device Keys"

Two properties have been added to the specification to help application developers integrate with the capabilities of a device. Different devices can include different numbers of soft keys, and allow different numbers of soft menus. In order to allow developers to optimize their use of the available menus and soft keys, two system properties have been defined.

Initial Focus Owner Recommended Practice

Applications implemented using AGUI should programatically select the initial  focus owner (java.awt.Component.requestFocus() ) to ensure that an appropriate 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 by the application, so an implementation should choose a component to be the initial focus owner if the application does not.  Implementations wishing to select initial focus owners for applications must implement the following behavior:

 Overview  Package  Class  Use  Tree  Deprecated  Index  Help 
JSR-209 (Final Release)
 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.