Apache Harmony is retired at the Apache Software Foundation since Nov 16, 2011.

The information on these pages may be out of date, or may refer to resources that have moved or have been made read-only.
For more information please refer to the Apache Attic

Abstract Windowing Toolkit

Abstract Window Toolkit Framework

  1. Revision History
  2. About This Document
    1. Purpose
    2. Intended Audience
    3. Documentation Conventions
  3. Introduction to AWT
  4. AWT in DRL
    1. Event Handling
      1. Native and AWT Events
      2. Event Dispatch Thread
      3. Native and AWT Events Priority
      4. Native Events Handling
      5. Native and AWT Event Handlers Cooperation
    2. Focus Subsystem
      1. Focus Dispatcher
      2. AWT Level
      3. DRL Focus Implementation Specifics
    3. Visual Themes in AWT
      1. Default Theme
      2. Derived Themes
      3. Implementation Specifics
      4. Using State Interfaces in a Standard Component
      5. Windows* Theme
    4. Multi-threading Support
      1. Why Synchronize
      2. How to Synchronize
      3. When to Synchronize
      4. Synchronizer
  5. References

Revision History

Version Version Information Date
Initial version Nadya Morozova, Pavel Dolgov: document created. May 10, 2006
Formatting update Nadya Morozova September 21, 2006
Update: event handling and synchronizer Nadya Morozova, Alexey Petrenko April, 2007

About This Document

Purpose

This document introduces the AWT (Abstract Window Toolkit) framework delivered as part of the DRL (Dynamic Run-time Layer) initiative. This document focuses on the characteristics of the current AWT implementation.

Intended Audience

The target audience for the document includes a wide community of engineers interested in further work with AWT to contribute to its development. The document assumes that readers are familiar with AWT and the Java* programming language.

Documentation Conventions

This document uses the unified conventions for the DRL documentation kit.

Back to Top

Introduction to AWT

As indicated in the specification [1], the Abstract Window Toolkit (AWT) is a part of the Java* Foundation Classes (JFC). AWT provides basic facilities to develop graphical user interfaces (GUI) and to draw simple graphics for platform-independent applets and applications.

In AWT, GUI consists of components, such as buttons, menus, and top-level windows. One of the main AWT features is that all its built-in components are heavy-weight, that is, every Java* component has a native GUI object behind it. The Swing library [2] is built on the basis of AWT and uses light-weight components, which do not have the 1:1 mapping with native resources.

AWT in DRL

This document describes major design features and internal specifics of the DRL AWT implementation. Further in this document, AWT denotes the DRL implementation for convenience.
To summarize, DRL AWT has the following key features:

Back to Top

Event Handling

AWT helps applications react to user's actions and traces the system state and the AWT internal state by means of events. Subsequent sections describe the AWT event handling implementation in DRL with focus on the interaction between AWT and the native system, specifically, the GUI subsystem of OS. For information on application events handling, consult the AWT specification [1].

Back to Top

Native and AWT Events

The DRL AWT framework deals with the following types of events:

Event Dispatch Thread

AWT has the event dispatch thread (EDT) at its basis, represented by the class java.awt.EventDispatchThread. This thread handles all generated types of events by going over the loop. EDT starts on AWT Toolkit creation and stops on application termination.

In more detail, EDT performs the following event loop:

  1. Wait for and get the native event from operating system.
  2. Decode the native event into an AWT event.
  3. Dispatch the AWT event: find the target AWT component for this event and pass it to this component through the java.awt.Dispatcher class.
  4. Push the AWT event to the event queue represented by the java.awt.EventQueue class.
  5. Pop all AWT events from the event queue.
  6. Pass the given AWT events to the appropriate AWT component by using the java.awt.Component.processXYZEvent() methods.
  7. Call the appropriate AWT component’s event listeners of the EventListener interface. Applications should implement appropriate listeners' interfaces to react to specific events.

Native and AWT Events Priority

Back to Top

Native Events Handling

This section defines native events types and the way AWT handles these events based on their type.

Native Events Classification

Figure 1 below demonstrates how native events can be classified by their role in the AWT framework.

Native events: 4 subtypes

Figure 1: Native Events Classification

  • State events signify that a native object corresponding to an AWT object has changed its state. For example, when the user minimizes the window, the window state change native event is generated.
  • Events-signals indicate a sporadic occurrence in the OS, usually, caused by user's actions. For instance, the event caused by a mouse wheel rotation is signal information.
  • Invisible events do not cause AWT event generation and are used only to update the internal data structure.
  • Unused events are concerned to specific OS features that are not supported by AWT, so these events are ignored.
Abstracting the Native Platform

Native events handling goes in two stages: the first stage depends on the native platform, and the second stage is the same on all supported platforms. Platform-dependent functionality comprises the Window Toolkit, WTK, in the org.apache.harmony.awt.wtk package. This package declares interfaces and abstract classes, the platform-specific classes inherited from them.

Native Event Dispatching

AWT handles relevant native events by following these steps:

  1. The native events thread receives a native event from the operating system.
  2. The platform-specific implementation of the NativeEvent interface translates the event to a unified format described by the interface NativeEvent, puts that event to tiveEventQueue, and notifies the event dispatch thread.
  3. EDT gets a notification that an event has arrived, fetches that event from the native event queue, and passes the event to the java.awt.Dispatcher object.
  4. Depending on the event type, the dispatcher can handle the event or transmit it to a specific sub-dispatcher. For example, java.awt.MouseDispatcher works with mouse events, java.awt.Dispatcher.KeyDispatcher processes keyboard events.

The result of native event dispatching depends on the event type: state event, signal or invisible. Signal native events are translated to AWT events explicitly (Figure 2, second column). For state and invisible events, the AWT framework updates the state of the AWT object corresponding to the native object that sent the event. For state events, this implicitly generates an AWT event signaling an AWT object state change (Figure 2, third column). For invisible events, the AWT object state gets updated silently (Figure 2, fourth column).

Native events handling by the 4 subtypes

Figure 2: Native Events Handling by Type

Back to Top

Focus Subsystem

The AWT focus subsystem is a set of classes for managing keyboard input focus responsible for:

In the DRL implementation, the focus subsystem functionality is distributed among several internal layers:

The interaction between user code and these levels of the focus subsystem is shown on Figure 3 below.

Detailed event handling schema

Figure 3. Focus Event Data Flow

The following code entities perform the major focus subsystem tasks:

Subsequent sections describe the levels of focus management in more detail and give specifics of the DRL implementation compared to the focus specification [3].

Focus Dispatcher

The focus dispatcher responds to native focus events and, for those relevant to AWT, sends an internal focus change event to the higher AWT level. The dispatcher skips redundant native events and handles event proxying supported on certain native platforms. The focus dispatcher in DRL is characterized by the features listed below.

Platform independence
This component is platform-independent and handles native events in a unified way. For example, when set to skip a false event, the focus dispatcher does not change its behavior on platforms where this type of event never occurs.
Internal operation only: no interaction with user code
The dispatcher does not generate AWT events and never calls client code directly, synchronously. Instead, WTK passes event information to the upper AWT level, which includes the flag indicating whether the focus is lost or gained, the source and opposite components, and the focused window.
Focus Proxying
When the focus is on an inactive window, focus proxies are used. A focus proxy is a child of an active window that has the native focus, whereas focus and key events are redirected to the Java* focused window. This way, the native decorations indicating the active state of the window are on the active window. At the same time, keyboard input and focus AWT events go to the focused window, whereas the native focused window is the focus proxy. The focus dispatcher transfers the native focus to the focus proxy and back when necessary. Events are redirected by the keyboard focus manager.

Events and Output in Event Proxying

Figure 4. Focus Proxy

If the active window is the focused window, no proxying occurs. In this case, the nearest heavyweight ancestor of the focus owner or the focus owner native window itself (if focus owner is a heavy-weight component) has native focus.

Back to Top

AWT Level

The higher level of the focus subsystem generates and posts all necessary AWT events to the event queue. This level keeps track of the following focus states:

The AWT level of the focus subsystem handles focus requests synchronously on every successful focus change request. When the method requestFocus() is called, the keyboard focus manager posts all necessary AWT events in the required order irrespective of the success or failure of the native focus request. In other words, the AWT subsystem does not wait until the native focus request gets confirmed and the corresponding native events are received.

After receiving a notification from the native system, WTK requests the AWT level to update the focus state via an internal request. For example, if the native system reports an unsuccessful focus change, a component might lose focus.

Note

Only certain native focus-related events cause a Java* focus state update. For example:

DRL Focus Implementation Specifics

Below, the specific features of DRL implementation are listed compared to the focus specification grouped by their function.

Replacing the DefaultKeyboardFocusManager class
The keyboard focus manager handles all events in the required order and never synthesizes window activation events. Instead, the focus manager skips the events that do not correspond to the current focus state. Such events can be generated by the private API of this class in response to native events. For example, the keyboard focus manager ignores events sent to the window that has failed to become the focused window because the corresponding AWT event was dispatched and vetoed.
When handling the WINDOW_GAINED_FOCUS event, private methods in the keyboard focus manager set focus on the appropriate child component of the window.
Programmatic Traversal
Disabling any ancestor of the focus owner, both light-weight and heavy-weight, automatically initiates a focus traversal.

Back to Top

Visual Themes in AWT

This document describes the mechanism of drawing standard AWT components with platform-independent Java* means or platform-specific native API or using both approaches.

Default theme

You can paint standard components in many ways, including drawing the component parts (text, background, shadows and all other elements) by the means of class java.awt.Graphics. Note that the framework must not paint standard components by the method java.awt.Component.paint() because it could be overridden. Instead, when processing a painting event, the framework calls the package-private method java.awt.Component.prepaint() just before calling the method paint(). The prepaint() method does the actual painting for all standard components by delegating the painting task to the theme. This approach might not seem optimal, but it works on all supported platforms without any changes.

The org.apache.harmony.awt.Theme class implements the default theme. Methods of this class do the following:

The default theme class is platform-independent, non-abstract and fully functional, and it usually works when the native theme is disabled or not available, or when the native theme re-uses functionality of the standard theme.

Derived themes

You can create a custom theme that inherits from the default theme and contains specific features. The current implementation contains the WinTheme class that extends the default theme as shown in Figure 5.

To use the native API in your theme, extend the default theme overriding its painting methods. In the derived theme, you can use the additional features of specific implementation of the Graphics class, and explicitly call native API functions via wrappers, see org.apache.harmony.misc package for details. Figure 5 below demonstrates theme-related classes hierarchy with methods related to the Button component as an example. A block of code for extending the drawButton() method is shown in Example 1 below.

OS specific themes as subclasses to the major theme

Figure 5: Hierarchy of Theme Classes

After creating a derived theme, turn it on by using the property awt.theme. This property contains the name of a subclass of default theme class used as the theme by all components. If the property points to a non-existent class or if the required native library is missing, or any other error occurs, the default theme is used. If the property is not set, the native theme of the current OS is used if it exists. If no OS theme exists, the default theme is used.

To force the default theme, set the command-line option -Dawt.theme=0. As long as zero is an invalid class name, this does the job.

Back to Top

Implementation details

Painting standard components requires access to their internal state, such as the pressed state, the focused state, the background color, and the contained text. Because not all these attributes are visible through the public API, the DRL AWT module provides a set of interfaces to allow the theme to access private and public data. The package org.apache.harmony.awt.state contains these interfaces, such as, TextState, CheckboxState, and ButtonState. Each standard component class has an inner class that implements the appropriate interface and has the state field of that class declared. The java.awt.Component class stores all functionality common for all types of standard components. Specifically, the java.awt.Component class has an inner class ComponentState that implements the org.apache.harmony.awt.state.State interface. This inner class enables implementing the state of a specific component by overriding only a few methods.

Standard components delegate the painting and size calculation to the currently active theme and pass their state field value as a parameter to every method of the theme.

Platform-specific and component-specific code is concentrated in separate helper classes, such as DefaultButton, the helper to the default theme, and WinCheckbox, the helper to the Windows* theme. The theme class contains only simple methods.

Example 1

This is an example with the Button component.

public void drawButton(Graphics g, ButtonState s) { 
    drawButtonBackground(g, s); 
    drawButtonText(g, s); 
} 
protected void drawButtonBackground(Graphics g, ButtonState s) { 
    DefaultButton.drawBackground(g, s); 
} 
protected void drawButtonText(Graphics g, ButtonState s) { 
    DefaultButton.drawText(g, s); 
}

When designing a custom theme, you may need to override some of these protected methods.

Figure 6 shows an example of component classes relation, inner states and the inheritance hierarchy of component state interfaces. The figure contains short names for convenience, for example, Component actually means java.awt.Component.

Methods and classes related to state change operations

Figure 6: Inheritance and Composition for Components' State

Back to Top

Using State Interfaces in a Standard Component

This section illustrates how the state interfaces are used in the Button component. In DRL AWT, all standard components follow the same model.

This is a part of the java.awt.Button code that illustrates how to use visual themes in standard components.

class State extends Component.ComponentState implements ButtonState { … } 
final transient State state = new State(); 
    
void prepaint(Graphics g) { 
    toolkit.theme.drawButton(g, state); 
}

The framework calls the prepaint() method, which paints standard components. The painting itself is done by the theme class, and all the information it requires is contained in the state variable.

Windows* theme

In DRL, the Windows* theme is implemented by the class org.apache.harmony.awt.theme.windows.WinTheme, which inherits from the class org.apache.harmony.awt.Theme.

The WinTheme class paints components using the Windows* API function DrawFrameControl() in the classic mode and DrawThemeBackground() in the XP mode, and basic Windows* API painting functions.

The implementation also includes several helper classes:

Note

If the Windows* theme does not support the combination of components attributes, it delegates painting to the default theme by calling the super class. For example, the default theme can be used when the background color of a push button differs from the theme setting.

Back to Top

Multi-Threading support

Complying to the specification [1], DRL AWT can work within multi-threaded applications. This implementation ensures consistency of AWT framework data when accessed by multiple threads. For that, AWT synchronizes its key classes.

Why synchronize

The main purpose of synchronization is keeping the component hierarchy consistent when component properties are queried and/or modified, so that it potentially affects other components. This includes the parent-child relationships, the child component order, inherited properties, such as the font and the background color, the size and position related properties, as well as visibility, focusable state and other conditions relevant for message handling. Concurrent modifications of these properties can make the AWT framework state inconsistent.

For example, if a thread adds a component to a list of child components for a container without updating this component’s field parent, another thread working with the same component gets the wrong value of the parent field. Moreover, the second thread may remove this component from the container children list, which makes the behavior of the first thread unpredictable. Synchronization helps avoid such problems.

How to synchronize

When a method or a block of code deals with the data that must not be modified concurrently, a synchronized section is used. The DRL implementation uses a special monitor AWT lock more powerful than built-in Java* synchronized blocks and methods. The AWT lock is similar to the synchronization tools provided by the java.util.concurrent package. The synchronized section using the AWT lock has its own specifics, as demonstrated by the example below.

Example 2

This example provides an excerpt of code from the Component class demonstrating a typical synchronized section in the AWT code. The methods lockAWT() and unlockAWT() are the boundaries of the critical section. The code between them is synchronized by the AWT lock.

final transient Toolkit toolkit = Toolkit.getDefaultToolkit();
…
public Color getBackground() {
    toolkit.lockAWT();
    try {
        if ((backColor == null) && (parent != null)) {
            return parent.getBackground();
        }
        return backColor;
    } finally {
        toolkit.unlockAWT();
    }
}

From the syntactical standpoint, this is a try-finally structure, which guarantees that the unlockAWT() method is always called after doing the useful work in the body of try block. Logically, it is used as an ordinary synchronized block, except when using AWT lock extended functionality.

The AWT synchronizer is similar to the object java.util.concurrent.ReentrantLock with one significant addition: it has methods storeStateAndFree() and lockAndRestoreState(), which help to implement the unsafeInvokeAndWait() functionality for opening modal dialogs and pop-up menus from a non-dispatch thread. This approach is not ideal, so suggestions on a better approach are welcome.

Back to Top

When to synchronize

AWT synchronization covers the following classes:

The total number of synchronized classes nears 40.

Simple data structures, for example, Rectangle or Point, are not protected from concurrent modifications for performance reasons.

General rules on how to use synchronized sections
  • Only public and protected methods of the public API must be synchronized by the AWT lock. Package-private methods and private method are not, with only a few exceptions. For an example, see the java.awt.Toolkit class.
  • A synchronized section of code must not call user code, such as event listeners or frequently overridden methods.
Exceptions
  • Layout managers are always called with the AWT lock.
  • Certain methods might get overridden by user code, but are called under the AWT lock, for example, the method addNotify() in the Component and Container classes.
  • Platform-specific code of the org.apache.harmony.awt.wtk package must not use the AWT lock explicitly.

References

[1] AWT spec, http://java.sun.com/j2se/1.5.0/docs/guide/awt/index.html

[2] Swing Library Description, http://java.sun.com/j2se/1.5.0/docs/guide/swing/index.html

[3] AWT Focus Subsystem specification, http://java.sun.com/j2se/1.5.0/docs/api/java/awt/doc-files/FocusSpec.html

* Other brands and names are the property of their respective owners.

Back to Top