OpenJDK Challenge

External Toolkit Implementation, a walkthrough

Introduction

Using the public and semipublic peer interfaces it is possible to implement graphics backends for AWT and Java2D. This requires the implementation of the complete graphics stack, including the Toolkit, Graphics, and part of or all of fonts and image support. This can be quite a large task, but has the advantage that there are no assumptions about the underlying platform.

This tutorial illuminates the external interfaces and classes that are relevant for implementing a graphics backend for a new system. A JavaDoc description of the API is available as part of the project.

Summary

Toolkit implementation

The starting point for implementing a graphics backend is the java.awt.Toolkit.

The Toolkit abstract class provides many abstract methods that are meant to create the native peers for the AWT widgets and implement general toolkit functionality such as image handling, some font support, and some printing support.

A large part of implementing java.awt.Toolkit is the implementation of the AWT peer interfaces in the package java.awt.peer. One should follow the API documentation for Toolkit and the required peer interfaces.

In order to use a new Toolkit implementation, pass a system property to the VM like this:

java -Dawt.toolkit=your.toolkit.Classname

Note: that one may also need to provide a dedicated GraphicsEnvironment.

GraphicEnvironent, GraphicsDevice and GraphicsConfiguration

The java.awt.GraphicsEnvironment class is the other central entry point for implementing a graphics backend. It provides the graphics devices and graphics configuration information.

In order to implement java.awt.GraphicsEnvironment, you will also have to provide implementations of java.awt.GraphicsDevice and java.awt.GraphicsConfiguration. Please review the API documentation for those classes as reference.

In order to use your own GraphicsEnvironment, pass a system property to the VM like this:

java -Djava.awt.graphicsenv=your.graphicsenv.ClassName

Note: that you will most likely also want to use your own Toolkit implementation.

Graphics2D

As part of implementing the AWT peers and the GraphicsEnvironment, one also must provide an implementation for java.awt.Graphics, to be able to draw on the AWT components or images. While the API only mandates implementing java.awt.Graphics, it is very advisable to actually provide a java.awt.Graphics2D implementation, because many applications expect the Graphics object to actually be a Graphics2D object. Please refer to the API documentation of these two abstract classes for reference.

Fonts

The Toolkit is also resposible for creating a Font peer. However, this interface is not actively used anymore. There is an internal API for implementing fonts, which consist of a couple of classes and interfaces:


sun.font.Font2D
sun.font.FontManager
sun.awt.FontConfiguration

In order to implement a new font backend one has to provide a FontManager and all the referenced support classes.

It is possible to reuse part of the existing FontManager code even in newly written toolkit, even if this is not portable to different implementation (see the internal interfaces documentation). For the most portable approach, just implement the methods described in the FontManager interface. Currently, there is an ongoing project to make this interface more portable and improve its documentation.

Note that there is no public/semipublic API (like the AWT widget peers) for fonts right now.

To use a new FontManager implementation, pass a system property to the VM:

java -Dsun.font.fontmanager=your.fontmanager.ClassName

it is also possible to set this property in the static initializer of the GraphicsEnvironment implementation:


  static
  {
    System.setProperty("sun.font.fontmanager", "your.fontmanager.ClassName");
  }

KeyboardFocusManagerPeer

It is possible to reuse the FocusManagerPeer in OpenJDK. Currently, a process is underway to make it more portable and this functionality should be ported into the Toolkit. For now, if one would like to provide a KeyboardFocusManager, one can set the "sun.font.keyboardfocusmanager" system property to point to a valid implementation of KeyboardFocusManagerPeer.

Further Readings

Please, refer to the Internal Toolkit Implementation Tutorial for more details on how to implement the Toolkit Interface, without needing to reimplement everything from scratch, and reuse most of the existing code in OpenJDK. Refer to the API documentation of the relevant classes and interfaces for details of the implementation.

Relevant classes


java.awt.Toolkit
java.awt.GraphicsEnvironment
java.awt.GraphicsDevice
java.awt.GraphicsConfiguration
java.awt.Graphics
java.awt.Graphics2D
sun.font.Font2D
sun.font.FontManager
sun.awt.FontConfiguration
sun.awt.KeyboardFocusManagerPeerImpl

in java.awt.peer:


ButtonPeer
CanvasPeer
CheckboxMenuItemPeer
CheckboxPeer
ChoicePeer
ComponentPeer
ContainerPeer
DesktopPeer
DialogPeer
FileDialogPeer
FontPeer
FramePeer
KeyboardFocusManagerPeer
LabelPeer
LightweightPeer
ListPeer
MenuBarPeer
MenuComponentPeer
MenuItemPeer
MenuPeer
MouseInfoPeer
PanelPeer
PopupMenuPeer
RobotPeer
ScrollbarPeer
ScrollPanePeer
SystemTrayPeer
TextAreaPeer
TextComponentPeer
TextFieldPeer
TrayIconPeer
WindowPeer