doc/awt/AWT.html - harmony-classlib - Git at Google


            
            <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"

            
            "http://www.w3.org/TR/html4/loose.dtd">

            
            <html>

            
               <head>

            
                  <meta http-equiv="Content-Type" content=

            
                  "text/html; charset=windows-1252">

            
                  <title>

            
                     Abstract Windowing Toolkit

            
                  </title>

            
                  <link href="../harmony.css" rel="stylesheet" type="text/css">

            
               </head>

            
               <body>

            
                  <h1 style="text-align: center">

            
                     <a name="top"></a>Abstract Window Toolkit Framework

            
                  </h1>

            
                  <p class="TOCHeading">

            
                     <a href="#Revision_History">Revision History</a>

            
                  </p>

            
                  <p class="TOCHeading">

            
                     <a href="#Disclaimer_and_Legal_Information">Disclaimer and

            
                     Legal Information</a>

            
                  </p>

            
                  <p class="TOCHeading">

            
                     <a href="#About_This_Document">About this Document</a>

            
                  </p>

            
                  <p class="TOC">

            
                     <a href="#Purpose">Purpose</a>

            
                  </p>

            
                  <p class="TOC">

            
                     <a href="#Intended_Audience">Intended Audience</a>

            
                  </p>

            
                  <p class="TOC">

            
                     <a href="#Documentation_Conventions">Documentation

            
                     Conventions</a>

            
                  </p>

            
                  <p class="TOCHeading">

            
                     <a href="#Introduction to AWT">Introduction to AWT</a>

            
                  </p>

            
                  <p class="TOCHeading">

            
                     <a href="#AWTDRL">AWT in DRL</a>

            
                  </p>

            
                  <p class="TOC">

            
                     <a href="#Event_Handling">Event Handling</a>

            
                  </p>

            
                  <blockquote>

            
                     <p class="TOC">

            
                        <a href="#EventTypeDefinition">Native and AWT Events</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#EDT">Event Dispatch Thread</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#EventPriority">Native and AWT Events

            
                        Priority</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#NativeEvents">Native Events Handling</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href=

            
                        "#Native_and_AWT_Event_Handlers_Cooperation">Native and

            
                        AWT Event Handlers Cooperation</a>

            
                     </p>

            
                  </blockquote>

            
                  <p class="TOC">

            
                     <a href="#Focus_Subsystem">Focus Subsystem</a>

            
                  </p>

            
                  <blockquote>

            
                     <p class="TOC">

            
                        <a href="#Focus_Dispatcher">Focus Dispatcher</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#AWT_higher_level">AWT Level</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#DRL_Focus_Implementation_Specifics">DRL Focus

            
                        Implementation Specifics</a>

            
                     </p>

            
                  </blockquote>

            
                  <p class="TOC">

            
                     <a href="#Visual_Themes_in_AWT">Visual Themes in AWT</a>

            
                  </p>

            
                  <blockquote>

            
                     <p class="TOC">

            
                        <a href="#Default_theme">Default Theme</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#Delivered_themes">Derived Themes</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#Implementation_details">Implementation

            
                        Specifics</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href=

            
                        "#Using_State_Interfaces_in_a_Standard_Component">Using

            
                        State Interfaces in a Standard Component</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#Windows theme">Windows* Theme</a>

            
                     </p>

            
                  </blockquote>

            
                  <p class="TOC">

            
                     <a href="#Multi-Threading_support">Multi-threading

            
                     Support</a>

            
                  </p>

            
                  <blockquote>

            
                     <p class="TOC">

            
                        <a href="#WhySynchronize">Why Synchronize</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#HowtoSync">How to Synchronize</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#WhentoSync">When to Synchronize</a>

            
                     </p>

            
                     <p class="TOC">

            
                        <a href="#Synchronizer">Synchronizer</a>

            
                     </p>

            
                  </blockquote>

            
                  <p class="TOCHeading">

            
                     <a href="#References">References</a>

            
                  </p>

            
                  <h1>

            
                     <a name="Revision_History"></a>Revision History

            
                  </h1>

            
                  <table border="0" cellpadding="0" width="100%">

            
                     <tr>

            
                        <td class="TableHeading">

            
                           Version

            
                        </td>

            
                        <td class="TableHeading">

            
                           Version Information

            
                        </td>

            
                        <td class="TableHeading">

            
                           Date

            
                        </td>

            
                     </tr>

            
                     <tr>

            
                        <td class="TableCell">

            
                           Initial version

            
                        </td>

            
                        <td class="TableCell">

            
                           Nadya Morozova, Pavel Dolgov: document created.

            
                        </td>

            
                        <td class="TableCell">

            
                           May 10, 2006

            
                        </td>

            
                     </tr>

            
                  </table>

            
                  <h1>

            
                     <a name="Disclaimer_and_Legal_Information"></a>Disclaimer

            
                     and Legal Information

            
                  </h1>

            
                  <p>

            
                     Copyright 2005-2006 The Apache Software Foundation or its

            
                     licensors, as applicable.

            
                  </p>

            
                  <p>

            
                     Licensed under the Apache License, Version 2.0 (the

            
                     License); you may not use this file except in compliance

            
                     with the License. You may obtain a copy of the License at <a

            
                     href=

            
                     "http://www.apache.org/licenses/LICENSE-2.0" target="_blank">http://www.apache.org/licenses/LICENSE-2.0</a>.

            
                  </p>

            
                  <p>

            
                     Unless required by applicable law or agreed to in writing,

            
                     software distributed under the License is distributed on an

            
                     AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,

            
                     either express or implied. See the License for the specific

            
                     language governing permissions and limitations under the

            
                     License.

            
                  </p>

            
                  <h1>

            
                     <a name="About_This_Document"></a>About This Document

            
                  </h1>

            
                  <h2>

            
                     <a name="Purpose"></a>Purpose

            
                  </h2>

            
                  <p>

            
                     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.

            
                  </p>

            
                  <h2>

            
                     <a name="Intended_Audience"></a>Intended Audience

            
                  </h2>

            
                  <p>

            
                     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<a href="#*">*</a>

            
                     programming language.

            
                  </p>

            
                  <h2>

            
                     <a name="Documentation_Conventions"></a>Documentation

            
                     Conventions

            
                  </h2>

            
                  <p>

            
                     This document uses the <a href="conventions.htm" target=

            
                     "_blank">unified conventions</a> for the DRL documentation

            
                     kit.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h1>

            
                     <a name="Introduction to AWT"></a>Introduction to AWT

            
                  </h1>

            
                  <p>

            
                     As indicated in the specification [<a href=

            
                     "#AWTSpec">1</a>], the Abstract Window Toolkit (AWT) is a

            
                     part of the Java<a href="#*">*</a> Foundation Classes (JFC).

            
                     AWT provides basic facilities to develop graphical user

            
                     interfaces (GUI) and to draw simple graphics for

            
                     platform-independent applets and applications.

            
                  </p>

            
                  <p>

            
                     In AWT, GUI consists of <em>components</em>, 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<a href="#*">*</a>

            
                     component has a native GUI object behind it. The Swing

            
                     library [<a href="#SwingRef">2</a>] is built on the basis of

            
                     AWT and uses light-weight components, which do not have the

            
                     1:1 mapping with native resources.

            
                  </p>

            
                  <h1>

            
                     <a name="AWTDRL"></a>AWT in DRL

            
                  </h1>

            
                  <p>

            
                     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.<br>

            
                      To summarize, DRL AWT has the following key features:

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        <a href="#Event_Handling">Event handling</a> mechanism

            
                     </li>

            
                     <li>

            
                        <a href="#Focus_Subsystem">Focus dispatching</a> flow

            
                     </li>

            
                     <li>

            
                        AWT components' appearance handling in custom <a href=

            
                        "#Visual_Themes_in_AWT">visual themes</a>

            
                     </li>

            
                     <li>

            
                        Support for <a href=

            
                        "#Multi-Threading_support">multi-threading</a>

            
                     </li>

            
                  </ul>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h2>

            
                     <a name="Event_Handling"></a>Event Handling

            
                  </h2>

            
                  <p>

            
                     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 <em>native system</em>, specifically, the GUI

            
                     subsystem of OS. For information on application events

            
                     handling, consult the AWT specification [<a href=

            
                     "#AWTSpec">1</a>].

            
                  </p>

            
                  <h3>

            
                     <a name="EventTypeDefinition"></a>Native and AWT Events

            
                  </h3>

            
                  <p>

            
                     The DRL AWT framework deals with the following types of

            
                     events:

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        <i>Native events</i> generated by the operating system:

            
                        XEvents on Linux<a href="#*">*</a> and Windows messages

            
                        (MSG) on Windows<a href="#*">*</a>.

            
                     </li>

            
                     <li>

            
                        <i>AWT events</i> generated and handled by the AWT

            
                        framework. All AWT events are subclasses of the

            
                        <code>AWTEvent</code> class and are stored in the AWT

            
                        event queue represented by the <code>EventQueue</code>

            
                        class.

            
                     </li>

            
                  </ul>

            
                  <h3>

            
                     <a name="EDT"></a>Event Dispatch Thread

            
                  </h3>

            
                  <p>

            
                     AWT has the <i>event dispatch thread</i> (EDT) at its basis,

            
                     represented by the

            
                     class <code>java.awt.EventDispatchThread</code>. This thread

            
                     handles all generated types of events by going over the loop

            
                     shown in Figure 1. EDT starts on AWT Toolkit creation and

            
                     stops on application termination.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt="AWT and native event handling order" src=

            
                     "images/EventFlow.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 1: Native and AWT Events Handling

            
                  </p>

            
                  <p>

            
                     In more detail, EDT performs the following <em>event

            
                     loop</em>:

            
                  </p>

            
                  <ol>

            
                     <li>

            
                        Wait for and get the native event from operating system.

            
                     </li>

            
                     <li>

            
                        Decode the native event into an AWT event.

            
                     </li>

            
                     <li>

            
                        Dispatch the AWT event: find the target AWT component for

            
                        this event and pass it to this component through

            
                        the <code>java.awt.Dispatcher</code> class.

            
                     </li>

            
                     <li>

            
                        Push the AWT event to the event queue represented by

            
                        the <code>java.awt.EventQueue</code> class.

            
                     </li>

            
                     <li>

            
                        Pop all AWT events from the event queue.

            
                     </li>

            
                     <li>

            
                        Pass the given AWT events to the appropriate AWT

            
                        component by using

            
                        the <code>java.awt.Component.processXYZEvent()</code>

            
                        methods.

            
                     </li>

            
                     <li>

            
                        Call the appropriate AWT component&rsquo;s event

            
                        listeners of the&nbsp;<code>EventListener</code> interface.

            
                        Applications should implement appropriate listeners'

            
                        interfaces to react to specific events.

            
                     </li>

            
                  </ol>

            
                  <h3>

            
                     <a name="EventPriority"></a>Native and AWT Events Priority

            
                  </h3>

            
                  <ul>

            
                     <li>

            
                        <strong>AWT events have a higher logical priority than

            
                        native events.</strong><br>

            
                         EDT does not wait for a new native event or fetch a

            
                        ready native event unless all existing AWT events have

            
                        been handled.

            
                     </li>

            
                    <li>

            
                        <strong>After handling all AWT and native events, EDT

            
                        waits for a new native event.</strong><br>

            
                        If a non-EDT thread generates an AWT event when EDT is

            
                       waiting for a native event, a new native event is

            
                       required to wake EDT and make it handle the AWT event.

            
                       Every time a non-EDT thread adds an event to the queue,

            
                       the method <code>awake()</code> of

            
                        the <code>NativeEventQueue</code> interface is called.

            
            			This method produces a native auxiliary event so that  EDT becomes ready to handle AWT events. EDT

            
            			treats this auxiliary event as <a href="#Native_Event_classification">invisible</a>.

            
                     </li>

            
                  </ul>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="NativeEvents"></a>Native Events Handling

            
                  </h3>

            
                  <p>

            
                     This section defines native events types and the way AWT

            
                     handles these events based on their type.

            
                  </p>

            
                  <p class="class">

            
                     <a name="Native_Event_classification"></a>Native Events

            
                     Classification

            
                  </p>

            
                  <p>

            
                     Figure 3 below demonstrates how native events can be

            
                     classified by their role in the AWT framework.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt="Native events: 4 subtypes" src=

            
                     "images/NativeEventCL.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 3: Native Events Classification

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        <i>State events</i> 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.

            
                     </li>

            
                     <li>

            
                        <i>Events-signals</i> 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.

            
                     </li>

            
                     <li>

            
                        <i>Invisible events</i> do not cause AWT event generation

            
                        and are used only to update the internal data structure.

            
                     </li>

            
                     <li>

            
                        <i>Unused events</i> are concerned to specific OS

            
                        features that are not supported by AWT, so these events

            
                        are ignored.

            
                     </li>

            
                  </ul>

            
                  <p class="class">

            
                     Abstracting the Native Platform

            
                  </p>

            
                  <p>

            
                     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 <em>Window Toolkit</em>, WTK, in

            
                     the <code>org.apache.harmony.awt.wtk</code> package. The

            
                     platform-dependent and platform-independent levels cooperate

            
                     via three main interfaces of this

            
                     package: <code>NativeEventListener</code>, <code>NativeEvent</code>,

            
                     and <code>NativeEventQueue</code>, as shown in Figure 2.

            
                     Classes implementing the <code>NativeEvent</code>

            
                     and <code>NativeEventQueue</code> interfaces are

            
                     platform-specific. For example, the <code>NativeEvent</code>

            
                     interface is implemented by the

            
                     classes <code>LinuxEvent</code> and <code>WinEvent</code>

            
                     for the Linux<a href="#*">*</a> and Windows<a href=

            
                     "#*">*</a> systems respectively.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt=

            
                     "Interfaces depending and not depending on the underlying platform"

            
                      src="images/ImplementationDetails.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 2: Interfaces for Abstracting the Native Platform

            
                  </p>

            
                  <p>


                  </p>

            
                  <p>

            
                     Classes of the <code>NativeEvent</code> interface convert

            
                     information about native events to a platform-independent

            
                     format. The <code>NativeEventQueue</code> interface fetches

            
                     native events, and the <code>NativeEventListener</code>

            
                     interface of the Java<a href="#*">*</a> EDT thread handles

            
                     native events. In the DRL AWT implementation, native and AWT

            
                     events are handled by the single EDT thread. See the <a

            
                     href="#Multi-Threading_support">Multi-threading Support</a>

            
                     section for more information.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <p class="class">

            
                     <a name="Native_Event_Dispatching"></a>Native Event

            
                     Dispatching

            
                  </p>

            
                  <p>

            
                     The method <code>onEvent()</code> in the

            
                     platform-dependent <code>NativeEventListener</code>

            
                     interface processes native events. Platform-dependent

            
                     classes implementing <code>NativeEventQueue</code> call this

            
                     method to handle a relevant native event, see Figure 4.

            
                  </p>

            
                  <p>

            
                     AWT handles relevant native events by following these steps:

            
                  </p>

            
                  <ol>

            
                     <li>

            
                        The platform-specific implementation of

            
                        the <code>NativeEvent</code> interface translates the

            
                        event to a unified format described by the

            
                        interface <code>NativeEvent</code>.

            
                     </li>

            
                     <li>

            
                        The platform-specific implementation

            
                        of <code>NativeEventQueue</code> calls the EDT

            
                        method <code>onEvent()</code> and passes the decoded

            
                        event as a parameter.

            
                     </li>

            
                     <li>

            
                        EDT passes the event to the <code>java.awt.Dispatcher

            
                        class</code> identifying the type of event.

            
                     </li>

            
                     <li>

            
                        Depending on the event type, the dispatcher can handle

            
                        the event or transmit it to a specific sub-dispatcher.

            
                        For example, <code>java.awt.MouseDispatcher</code> works

            
                        with mouse

            
                        events, <code>java.awt.Dispatcher.KeyDispatcher</code>

            
                        processes keyboard events.

            
                     </li>

            
                  </ol>

            
                  <p>

            
                     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 4, 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 4, third column). For invisible events,

            
                     the AWT object state gets updated silently (Figure 4, fourth

            
                     column).

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt="Native events handling by the 4 subtypes" src=

            
                     "images/NativeEvent.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 4: Native Events Handling by Type

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="Native_and_AWT_Event_Handlers_Cooperation"></a>

            
                     Native and AWT Event Handlers Cooperation

            
                  </h3>

            
                  <p>

            
                     Native events often result in new AWT events that need to be

            
                     handled. This section describes when and how AWT event

            
                     handlers are called for this purpose.

            
                  </p>

            
                  <p>

            
                     The Windows<a href="#*">*</a> OS generates synchronous and

            
                     asynchronous native events, so that AWT must be ready to

            
                     handle nested calls to the event handler. In this case, AWT

            
                     makes an additional effort to handle AWT events one by one.

            
                     DRL AWT uses the <code>WindowProc</code> event handler

            
                     inside WTK for interaction with Windows<a href="#*">*</a>.

            
                     The OS calls this handler for handling any native event in

            
                     AWT.

            
                  </p>

            
                  <p>

            
                     The Linux<a href="#*">*</a> event handling mechanism is

            
                     different with its own method for handling native events. In

            
                     this OS, all native events are asynchronous and no nesting

            
                     happens.

            
                  </p>

            
                  <p class="class">

            
                     Handling a single event

            
                  </p>

            
                  <p>

            
                     Figure 5 is an example of mouse click event handling in AWT.

            
                     In the given case, the AWT listener does not co-operate with

            
                     the underlying native system, and, consequently, no other

            
                     native events are produced during the listener's operation.

            
                     The example demonstrates handling an event on Windows*.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt="Native events handling by the 4 subtypes" src=

            
                     "images/EventHanglingInAWT.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 5: Mouse Click Event Handling

            
                  </p>

            
                  <p>

            
                     Numbers in the figure above correspond to the following

            
                     steps in the event handling flow:

            
                  </p>

            
                  <ol>

            
                     <li>

            
                        The OS calls <code>WindowProc</code> to handle the native

            
                        event. The type of event is determined, information about

            
                        this event is gathered and passed to

            
                        the <code>onEvent()</code> method

            
                        of <code>NativeEventListener</code>.

            
                     </li>

            
                     <li>

            
                        The <code>java.awt.Dispatcher</code> class finds the

            
                        appropriate target for this event and posts an AWT event

            
                        to the AWT event queue. In this example, it

            
                        is <code>MouseEvent</code>.

            
                     </li>

            
                     <li>

            
                        The method <code>onEventNestingEnd()</code> is called to

            
                        handle all accumulated AWT

            
                        events. <code>MouseEvent</code> is fetched from the event

            
                        queue and finally dispatched. Listeners of the event's

            
                        target are called at this point.

            
                     </li>

            
                     <li>

            
                         <code>WindowProc</code> returns.

            
                     </li>

            
                  </ol>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <p class="class">

            
                     Handling nested events

            
                  </p>

            
                  <p>

            
                     Figure 6 is an example of mouse click event handling with

            
                     the event listener requests keyboard focus on the clicked

            
                     component.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt="Nested Event handling" src=

            
                     "images/EventHandling.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 6: Mouse Click Event Handling with a Nested Event

            
                  </p>

            
                  <p>

            
                     Numbers in the figure above correspond to the following

            
                     steps in the event handling flow:

            
                  </p>

            
                  <ol>

            
                     <li>

            
                        The OS calls <code>WindowProc</code>, the native event is

            
                        transformed into an AWT event and stored in the event

            
                        queue.

            
                     </li>

            
                     <li>

            
                        The event listener calls <code>requestFocus()</code>,

            
                        which indirectly results in a native API call.

            
                     </li>

            
                     <li>

            
                        The OS calls <code>WindowProc</code> to report the focus

            
                        change event. Because the previous call

            
                        to <code>WindowProc</code> is not complete yet, the new

            
                        call is recognized as nested.

            
                     </li>

            
                     <li>

            
                        The dispatcher adds another AWT

            
                        event, <code>FocusEvent</code>, to the event queue.

            
                     </li>

            
                     <li>

            
                         <code>WindowProc</code> returns without handling AWT

            
                        events because it is a nested native event handler.

            
                     </li>

            
                     <li>

            
                        The method <code>onEventNestingEnd()</code> is still

            
                        working in the first-level <code>WindowProc</code>

            
                        handler. This method fetches and dispatches

            
                        the <code>FocusEvent</code> added at step 4.

            
                     </li>

            
                     <li>

            
                        When the AWT event queue is

            
                        empty, <code>WindowProc</code> returns.

            
                     </li>

            
                  </ol>

            
                  <p>

            
                     This technique guarantees that AWT event handlers are called

            
                     sequentially. The nested native event handler does not

            
                     attempt to handle pending AWT events. Instead, these events

            
                     are collected in the event queue to be handled later. The

            
                     first-level native event handler dispatches all the AWT

            
                     events waiting in the queue.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h2>

            
                     <a name="Focus_Subsystem"></a>Focus Subsystem

            
                  </h2>

            
                  <p>

            
                     The AWT focus subsystem is a set of classes for managing

            
                     keyboard input focus responsible for:

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        Interacting with the underlying native window system,

            
                        such as <code>Win32</code> or <code>X11</code>, by way of

            
                        handling native focus events and making native focus

            
                        requests

            
                     </li>

            
                     <li>

            
                        Synchronizing the focus state with the native focus state

            
                     </li>

            
                  </ul>

            
                  <p>

            
                     In the DRL implementation, the focus subsystem functionality

            
                     is distributed among several internal layers:

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        <b>Window Toolkit</b> (WTK) is a platform-dependent

            
                        implementation of the abstract window toolkit. WTK

            
                        directly interacts with the native window system via

            
                        native library calls.

            
                     </li>

            
                     <li>

            
                        <b><a href="#Focus_Dispatcher">Focus Dispatcher</a></b>

            
                        is a platform-independent level of the focus subsystem

            
                        closely asynchronously interacting with the window

            
                        toolkit to respond to native focus events and provide

            
                        this information to the AWT upper level.

            
                     </li>

            
                     <li>

            
                        <b><a href="#AWT_higher_level">AWT level</a></b> is the

            
                        major part of the focus subsystem working synchronously

            
                        with the user application by generating and posting AWT

            
                        events to the event queue.

            
                     </li>

            
                  </ul>

            
                  <p>

            
                     The interaction between user code and these levels of the

            
                     focus subsystem is shown on Figure 7 below.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt="Detailed event handling schema" src=

            
                     "images/FocusFramework.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 7. Focus Event Data Flow

            
                  </p>

            
                  <p>

            
                     The following code entities perform the major focus

            
                     subsystem tasks:

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        The <code>java.awt.FocusDispatcher</code> class handles

            
                        focus events received from the window toolkit level.

            
                     </li>

            
                     <li>

            
                        Package-private methods of

            
                        the <code>KeyboardFocusManager</code> class manage focus

            
                        on the higher AWT level.

            
                     </li>

            
                  </ul>

            
                  <p>

            
                     Subsequent sections describe the levels of focus management

            
                     in more detail and give specifics of the DRL implementation

            
                     compared to the focus specification [<a href=

            
                     "#FocusRef">3</a>].

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="Focus_Dispatcher"></a>Focus Dispatcher

            
                  </h3>

            
                  <p>

            
                     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.

            
                  </p>

            
                  <dl>

            
                     <dt>

            
                        Platform independence

            
                     </dt>

            
                     <dd>

            
                        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.

            
                     </dd>

            
                     <dt>

            
                        Internal operation only: no interaction with user code

            
                     </dt>

            
                     <dd>

            
                        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.

            
                     </dd>

            
                     <dt>

            
                        Focus Proxying

            
                     </dt>

            
                     <dd>

            
                        When the focus is on an inactive window, focus proxies

            
                        are used. A <i>focus proxy</i> is a child of an active

            
                        window that has the native focus, whereas focus and key

            
                        events are redirected to the Java<a href="#*">*</a>

            
                        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 <a href=

            
                        "#KFM">keyboard focus manager</a>.

            
                        <p style="text-align: center">

            
                           <img alt="Events and Output in Event Proxying" src=

            
                           "images/FocusProxying.gif">

            
                        </p>

            
                        <p class="special">

            
                           Figure 8. Focus Proxy

            
                        </p>

            
                        <p>

            
                           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.

            
                        </p>

            
                     </dd>

            
                  </dl>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="AWT_higher_level"></a>AWT Level

            
                  </h3>

            
                  <p>

            
                     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:

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        The focus state visible to the user and updated after the

            
                        AWT event is dispatched by the keyboard focus manager,

            
                        [<a href="#FocusRef">3</a>].

            
                     </li>

            
                     <li>

            
                        The low-level WTK focus state reported by the underlying

            
                        WTK level and updated immediately on getting a native

            
                        event.

            
                     </li>

            
                  </ul>

            
                  <p>

            
                     The AWT level of the focus subsystem handles focus requests

            
                     synchronously on every successful focus change request. When

            
                     the method <code>requestFocus()</code> 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.

            
                  </p>

            
                  <p>

            
                     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.

            
                  </p>

            
                  <p class="note">

            
                     Note

            
                  </p>

            
                  <p class="notetext">

            
                     Only certain native focus-related events cause a Java<a

            
                     href="#*">*</a> focus state update. For example:

            
                  </p>

            
                  <ul>

            
                     <li class="notetext">

            
                        When a top-level native window gains focus, the focus

            
                        goes to a child of this window or the <code>Window</code>

            
                        component itself, in case no child elements are

            
                        available.

            
                     </li>

            
                     <li class="notetext">

            
                        When a window in another application gains focus, the

            
                        focus dispatcher calls the <code>setFocus(false)</code>

            
                        method on the focus owner to clear the focus owner value.

            
                     </li>

            
                  </ul>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="DRL_Focus_Implementation_Specifics"></a>DRL Focus

            
                     Implementation Specifics

            
                  </h3>

            
                  <p>

            
                     Below, the specific features of DRL implementation are

            
                     listed compared to the focus specification grouped by their

            
                     function.

            
                  </p>

            
                  <dl>

            
                     <dt>

            
                        <a name="KFM"></a>Replacing the

            
                        DefaultKeyboardFocusManager class

            
                     </dt>

            
                     <dd>

            
                        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.<br>

            
                         When handling the <code>WINDOW_GAINED_FOCUS</code>

            
                        event, private methods in the keyboard focus manager set

            
                        focus on the appropriate child component of the window.

            
                     </dd>

            
                     <dt>

            
                        <a name="Programmatic Traversal"></a> Programmatic

            
                        Traversal

            
                     </dt>

            
                     <dd>

            
                        Disabling any ancestor of the focus owner, both

            
                        light-weight and heavy-weight, automatically initiates a

            
                        focus traversal.

            
                     </dd>

            
                  </dl>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h2>

            
                     <a name="Visual_Themes_in_AWT"></a> Visual Themes in AWT

            
                  </h2>

            
                  <p>

            
                     This document describes the mechanism of drawing standard

            
                     AWT components with platform-independent Java<a href=

            
                     "#*">*</a> means or platform-specific native API or using

            
                     both approaches.

            
                  </p>

            
                  <h3>

            
                     <a name="Default_theme"></a>Default theme

            
                  </h3>

            
                  <p>

            
                     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 <code>java.awt.Graphics</code>. Note that the

            
                     framework must not paint standard components by the

            
                     method <code>java.awt.Component.paint()</code> because it

            
                     could be overridden. Instead, when processing a painting

            
                     event, the framework calls the package-private

            
                     method <code>java.awt.Component.prepaint()</code> just

            
                     before calling the method <code>paint()</code>.

            
                     The <code>prepaint()</code> 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.

            
                  </p>

            
                  <p>

            
                     The <code>org.apache.harmony.awt.Theme</code> class

            
                     implements the default theme. Methods of this class do the

            
                     following:

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        Paint standard components, for example, the

            
                        method <code>drawButton()</code>.

            
                     </li>

            
                     <li>

            
                        Calculate the optimal component size for each type of

            
                        component, for example, by using the

            
                        method <code>calculateButton()</code>.

            
                     </li>

            
                  </ul>

            
                  <p>

            
                     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.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="Delivered_themes"></a> Derived themes

            
                  </h3>

            
                  <p>

            
                     You can create a custom theme that inherits from the default

            
                     theme and contains specific features. The current

            
                     implementation contains the <code>WinTheme</code> class that

            
                     extends the default theme as shown in Figure 9.

            
                  </p>

            
                  <p>

            
                     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 <code>Graphics</code> class, and

            
                     explicitly call native API functions via wrappers,

            
                     see <code>org.apache.harmony.misc</code> package for

            
                     details. Figure 9 below demonstrates theme-related classes

            
                     hierarchy with methods related to the <code>Button</code>

            
                     component as an example. A block of code for extending

            
                     the <code>drawButton()</code> method is shown in <a href=

            
                     "#ExampleButton">Example 1</a> below.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt=

            
                     "OS specific themes as subclasses to the major theme" src=

            
                     "images/ThemesHierachy.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 9: Hierarchy of Theme Classes

            
                  </p>

            
                  <p>


                  </p>

            
                  <p>

            
                     After creating a derived theme, turn it on by using the

            
                     property <code>awt.theme</code>. 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.

            
                  </p>

            
                  <p>

            
                     To force the default theme, set the command-line

            
                     option <code>-Dawt.theme=0</code>. As long as zero is an

            
                     invalid class name, this does the job.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="Implementation_details"></a>Implementation details

            
                  </h3>

            
                  <p>

            
                     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 <code>org.apache.harmony.awt.state</code> contains

            
                     these interfaces, such

            
                     as, <code>TextState</code>, <code>CheckboxState</code>,

            
                     and <code>ButtonState</code>. Each standard component class

            
                     has an inner class that implements the appropriate interface

            
                     and has the state field of that class declared.

            
                     The <code>java.awt.Component</code> class stores all

            
                     functionality common for all types of standard components.

            
                     Specifically, the <code>java.awt.Component</code> class has

            
                     an inner class <code>ComponentState</code> that implements

            
                     the <code>org.apache.harmony.awt.state.State</code>

            
                     interface. This inner class enables implementing the state

            
                     of a specific component by overriding only a few methods.

            
                  </p>

            
                  <p>

            
                     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.

            
                  </p>

            
                  <p>

            
                     Platform-specific and component-specific code is

            
                     concentrated in separate helper classes, such

            
                     as <code>DefaultButton</code>, the helper to the default

            
                     theme, and <code>WinCheckbox</code>, the helper to the

            
                     Windows<a href="#*">*</a> theme. The theme class contains

            
                     only simple methods.

            
                  </p>

            
                  <p class="class">

            
                     <a name="ExampleButton"></a>Example 1

            
                  </p>

            
                  <p>

            
                     This is an example with the <code>Button</code> component.

            
                  </p>

            
            <pre>

            
            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);

            
            }

            
            </pre>

            
                  <p>

            
                     When designing a custom theme, you may need to override some

            
                     of these protected methods.

            
                  </p>

            
                  <p>

            
                     Figure 10 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,

            
            &nbsp;<code>Component</code> actually means &nbsp;<code>java.awt.Component</code>. </p>

            
                  <p style="text-align: center">

            
                     <img alt=

            
                     "Methods and classes related to state change operations"

            
                     src="images/ThemesStates.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 10: Inheritance and Composition for Components' State

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name=

            
                     "Using_State_Interfaces_in_a_Standard_Component"></a>Using

            
                     State Interfaces in a Standard Component

            
                  </h3>

            
                  <p>

            
                     This section illustrates how the state interfaces are used

            
                     in the <code>Button</code> component. In DRL AWT, all

            
                     standard components follow the same model.

            
                  </p>

            
                  <p>

            
                     This is a part of the <code>java.awt.Button</code> code that

            
                     illustrates how to use visual themes in standard components.

            
                  </p>

            
            <pre>

            
            class State extends Component.ComponentState implements ButtonState { &hellip; }

            
            final transient State state = new State();


            void prepaint(Graphics g) {

            
                toolkit.theme.drawButton(g, state);

            
            }

            
            </pre>

            
                  <p>

            
                     The framework calls the <code>prepaint()</code> 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.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="Windows theme"></a>Windows<a href="#*">*</a> theme

            
                  </h3>

            
                  <p>

            
                     In DRL, the Windows<a href="#*">*</a> theme is implemented

            
                     by the

            
                     class <code>org.apache.harmony.awt.theme.windows.WinTheme</code>,

            
                     which inherits from the

            
                     class <code>org.apache.harmony.awt.Theme</code>.

            
                  </p>

            
                  <p>

            
                     The <code>WinTheme</code> class paints components using the

            
                     Windows<a href="#*">*</a> API

            
                     function <code>DrawFrameControl()</code> in the classic mode

            
                     and <code>DrawThemeBackground()</code> in the XP mode, and

            
                     basic Windows<a href="#*">*</a> API painting functions.

            
                  </p>

            
                  <p>

            
                     The implementation also includes several helper classes:

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        The

            
                        class <code>org.apache.harmony.awt.gl.WinThemeGraphics</code>

            
                        has a set of native methods that call the Windows<a href=

            
                        "#*">*</a> API. This class is tightly coupled

            
                        with <code>org.apache.harmony.awt.gl.WinGDIPGraphics2D</code>,

            
                        which is an implementation

            
                        of <code>java.awt.Graphics</code>.

            
                        The <code>WinThemeGraphics</code> class

            
                        queries <code>WinGDIPGraphics2D</code> for the current

            
                        clip, translation and device context.

            
                     </li>

            
                     <li>

            
                        The

            
                        class <code>org.apache.harmony.awt.wtk.windows.WinEventQueue.ThemeMap</code>

            
                        that handles theme-related native events and opens and

            
                        closes handles of native theme data when needed.

            
                     </li>

            
                     <li>

            
                        The set of helper

            
                        classes <code>org.apache.harmony.awt.wtk.theme.windows</code>

            
                        responsible for specific types of components, for

            
                        example, <code>org.apache.harmony.awt.wtk.theme.windows.WinButton</code>.

            
                     </li>

            
                  </ul>

            
                  <p class="note">

            
                     Note

            
                  </p>

            
                  <p class="notetext">

            
                     If the Windows<a href="#*">*</a> 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.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h2>

            
                     <a name="Multi-Threading_support"></a>Multi-Threading

            
                     support

            
                  </h2>

            
                  <p>

            
                     Complying to the specification [<a href="#AWTSpec">1</a>],

            
                     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.

            
                  </p>

            
                  <h3>

            
                     <a name="WhySynchronize"></a>Why synchronize

            
                  </h3>

            
                  <p>

            
                     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.

            
                  </p>

            
                  <p>

            
                     For example, if a thread adds a component to a list of child

            
                     components for a container without updating this

            
                     component&rsquo;s field <code>parent</code>, another thread

            
                     working with the same component gets the wrong value of

            
                     the <code>parent</code> 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.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="HowtoSync"></a>How to synchronize

            
                  </h3>

            
                  <p>

            
                     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 <em>AWT

            
                     lock</em> more powerful than built-in Java<a href="#*">*</a>

            
                     synchronized blocks and methods. The AWT lock is similar to

            
                     the synchronization tools provided by

            
                     the <code>java.util.concurrent</code> package. The

            
                     synchronized section using the AWT lock has its own

            
                     specifics, as demonstrated by the example below.

            
                  </p>

            
                  <p class="class">

            
                     Example 2

            
                  </p>

            
                  <p>

            
                     This example provides an excerpt of code from

            
                     the <code>Component</code> class demonstrating a typical

            
                     synchronized section in the AWT code. The

            
                     methods <code>lockAWT()</code> and <code>unlockAWT()</code>

            
                     are the boundaries of the critical section. The code between

            
                     them is synchronized by the AWT lock.

            
                  </p>

            
            <pre>

            
            final transient Toolkit toolkit = Toolkit.getDefaultToolkit();

            
            &hellip;

            
            public Color getBackground() {

            
                toolkit.lockAWT();

            
                try {

            
                    if ((backColor == null) && (parent != null)) {

            
                        return parent.getBackground();

            
                    }

            
                    return backColor;

            
                } finally {

            
                    toolkit.unlockAWT();

            
                }

            
            }

            
            </pre>

            
                  <p>

            
                     From the syntactical standpoint, this is a try-finally

            
                     structure, which guarantees that

            
                     the <code>unlockAWT()</code> 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.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="WhentoSync"></a>When to synchronize

            
                  </h3>

            
                  <p>

            
                     AWT synchronization covers the following classes:

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        Components, such

            
                        as <code>Component</code>, <code>Button</code>,

            
                        and <code>Frame</code>

            
                     </li>

            
                     <li>

            
                        Layout managers, such as <code>FlowLayout</code>

            
                        and <code>GridBagLayout</code>

            
                     </li>

            
                     <li>

            
                        Auxiliary, such as <code>Toolkit</code>

            
                        and <code>KeyboardFocusManager</code>

            
                     </li>

            
                  </ul>

            
                  <p>

            
                     The total number of synchronized classes nears 40.

            
                  </p>

            
                  <p>

            
                     Simple data structures, for example, <code>Rectangle</code>

            
                     or <code>Point</code>, are not protected from concurrent

            
                     modifications for performance reasons.

            
                  </p>

            
                  <p class="class">

            
                     General rules on how to use synchronized sections

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        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 <a href=

            
                        "#SyncExceptions">exceptions</a>. For an example, see

            
                        the <code>java.awt.Toolkit</code> class.

            
                     </li>

            
                     <li>

            
                        A synchronized section of code must not call user code,

            
                        such as event listeners or frequently overridden methods.

            
                     </li>

            
                  </ul>

            
                  <p class="class">

            
                     <a name="SyncExceptions"></a>Exceptions

            
                  </p>

            
                  <ul>

            
                     <li>

            
                        Layout managers are always called with the AWT lock.

            
                     </li>

            
                     <li>

            
                        Certain methods might get overridden by user code, but

            
                        are called under the AWT lock, for example, the

            
                        method <code>addNotify()</code> in

            
                        the <code>Component</code> and <code>Container</code>

            
                        classes.

            
                     </li>

            
                     <li>

            
                        Platform-specific code of

            
                        the <code>org.apache.harmony.awt.wtk</code> package must

            
                        not use the AWT lock explicitly.

            
                     </li>

            
                  </ul>

            
                  <p class="note">

            
                     Note

            
                  </p>

            
                  <p class="notetext">

            
                     In platform-specific event handling code, the event listener

            
                     uses this lock by calling

            
                     methods <code>onEventBegin()</code>

            
                     and <code>onEventEnd()</code>. These methods

            
                     call <code>lockAWT()</code> and <code>unlockAWT()</code>

            
                     respectively. This is done to ensure that the dispatcher can

            
                     find the event target and that the data is not modified by

            
                     another thread.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h3>

            
                     <a name="Synchronizer"></a>Synchronizer

            
                  </h3>

            
                  <p>

            
                     The <code>org.apache.harmony.awt.wtk.Synchronizer</code>

            
                     class implements the AWT lock. The <code>Toolkit</code>

            
                     class holds the reference to the synchronizer instance. In a

            
                     standalone application, <code>Toolkit</code>

            
                     and <code>Synchronizer</code> are singleton classes. In the

            
                     multi-context mode, AWT provides

            
                     independent <code>Toolkit</code>

            
                     and <code>Synchronizer</code> instances per each context.

            
                  </p>

            
                  <p>

            
                     Figure 11 shows the inheritance relationship of synchronizer

            
                     classes. The Linux<a href="#*">*</a> and Windows<a href=

            
                     "#*">*</a> operating systems have their own classes.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt=

            
                     "Windows and Linux synchronizers are subclasses of Synchronizer"

            
                      src="images/threadsMajorClasses.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 11: Synchronizer Classes

            
                  </p>

            
                  <p>

            
                     The base class <code>Synchronizer</code> represents a mutex

            
                     with a high-priority <a href="#Event_Handling">event

            
                     dispatch thread</a>. All user threads are served in the FIFO

            
                     (first in first out) order, whereas EDT has higher priority

            
                     and is served in the LIFO (last in first out) order.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <p class="class">

            
                     Synchronizer for Linux<a href="#*">*</a>

            
                  </p>

            
                  <p>

            
                     AWT uses the Xlib library to access native window resources

            
                     on Linux<a href="#*">*</a>. The Xlib library is thread-safe

            
                     and all user and EDT threads can freely access the native

            
                     system through the AWT interface, as shown in Figure 12. As

            
                     a result, the

            
                     class <code>org.apache.harmony.awt.wtk.linux.LinuxSynchronizer</code>

            
                     contains no extensions

            
                     to <code>java.awt.Synchronizer</code>.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt=

            
                     "user threads access native resources independently of the EDT thread"

            
                      src="images/ThreadEDT1.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 12: Access to the Native System on Linux<a href=

            
                     "#*">*</a>

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <p class="class">

            
                     Synchronizer for Windows<a href="#*">*</a>

            
                  </p>

            
                  <p>

            
                     Synchronization on Windows<a href="#*">*</a> is different

            
                     due to Windows<a href="#*">*</a> libraries specifics.

            
                     Firstly, changing the state of a native window usually

            
                     produces a synchronous event that reports this change.

            
                     Secondly, only the thread that created a window receives

            
                     native events related to that window.

            
                  </p>

            
                  <p>

            
                     In DRL AWT, the <a href="#Event_Handling">event dispatch

            
                     thread</a> handles all native events and, consequently, is

            
                     the only thread that can create windows. EDT also changes

            
                     the window&rsquo;s state to simplify the native events

            
                     handling scheme. Non-EDT threads can create and manipulate

            
                     native windows by giving tasks to EDT. User and EDT

            
                  threads cooperation is shown in Figure 13. </p>

            
                  <p style="text-align: center">

            
                     <img alt=

            
                     "user threads access native resources via of the EDT thread"

            
                     src="images/ThreadEDT2.gif">

            
                  </p>

            
                  <p class="special">

            
                     Figure 13: Access to the Native System on Windows<a href=

            
                     "#*">*</a> with EDT

            
                  </p>

            
                  <p>

            
                     The <code>org.apache.harmony.awt.wtk.windows.WinSynchronizer</code>

            
                     class, the extension of <code>Synchronizer</code>,

            
                     implements the interface <code>NativeServer</code>, which

            
                     enables user threads to query EDT for access to native

            
                     resources.

            
                  </p>

            
                  <p>

            
                     However, delegating access to native resources to EDT

            
                     requires a more complicated synchronization mechanism. Using

            
                     the <code>Synchronizer</code> logic as is results in a

            
                     potential deadlock while handling native Windows<a href=

            
                     "#*">*</a> events. Figure 14 shows the scenario of the

            
                     deadlock.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt="thread execution flows with deadlock illustrated"

            
                     src="images/ThreadDeadlock.gif">

            
                  </p>

            
                  <p class="special" style="text-align: center">

            
                     Figure 14: Deadlock with the user thread and EDT

            
                  </p>

            
                  <p>

            
                     <em>t1</em>: The user thread starts.

            
                  </p>

            
                  <p>

            
                     <em>t2</em>: EDT starts.

            
                  </p>

            
                  <p>

            
                     <em>t3</em>: The user thread obtains the AWT lock.

            
                  </p>

            
                  <p>

            
                     <em>t4</em>: EDT tries to obtain the AWT lock and gets

            
                     blocked.

            
                  </p>

            
                  <p>

            
                     <em>t5</em>: The user thread requests a service from EDT via

            
                     the <code>NativeServer</code> interface and gets blocked

            
                     forever because EDT is blocked too.

            
                  </p>

            
                  <p>

            
                     The <code>WinSynchronizer</code> class resolves the deadlock

            
                     issue by combining the synchronizer&rsquo;s protocol and the

            
                     native server protocol. For that, EDT switches between handling events and providing access to native resources for other running threads, as shown in Figure 15.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt="EDT modes" src="images/ThreadAWTLock.gif">

            
                  </p>

            
                  <p class="special">

            
                  Figure 15. EDT Operation </p>

            
                  <p>

            
                     This algorithm  enables detecting a

            
                     potential deadlock and resolving it. When EDT is requested

            
                     to provide access to native resources while it is waiting to obtain the AWT

            
                     lock, EDT awakes, serves the request and resumes waiting.

            
                     Serving the native resource request is transparent for the

            
                     event-handling side of EDT because this operation is

            
                     performed while EDT is inside of <code>lockAWT()</code>

            
                     method. The deadlock is resolved, as shown in Figure 16.

            
                  </p>

            
                  <p style="text-align: center">

            
                     <img alt="Thread execution flow with no deadlock" src=

            
                     "images/ThreadNoDeadlock.gif">

            
                  </p>

            
                  <p class="special" style="text-align: center">

            
                     Figure 16: Deadlock Resolution by WinSynchronizer

            
                  </p>

            
                  <p>

            
                     <em>t1</em>: The user thread starts.

            
                  </p>

            
                  <p>

            
                     <em>t2</em>: EDT starts.

            
                  </p>

            
                  <p>

            
                     <em>t3</em>: The user thread obtains the AWT lock.

            
                  </p>

            
                  <p>

            
                     <em>t4</em>: EDT tries to obtain the AWT lock and gets

            
                     blocked.

            
                  </p>

            
                  <p>

            
                     <em>t5</em>: The user thread requests EDT service and also

            
                     gets blocked. EDT starts processing the request.

            
                  </p>

            
                  <p>

            
                     <em>t6</em>: EDT finishes processing request. The user

            
                     thread resumes.

            
                  </p>

            
                  <p>

            
                     <em>t7</em>: The user thread releases the AWT lock, EDT

            
                     obtains it.

            
                  </p>

            
                  <p>

            
                     <em>t8</em>: The user thread may continue its work or exit.

            
                  </p>

            
                  <p>

            
                     <em>t9</em>: EDT releases the AWT lock.

            
                  </p>

            
                  <p>

            
                     <em>t10</em>: EDT continues operation.

            
                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <h2>

            
                     <a name="References"></a> References

            
                  </h2>

            
                  <p>

            
                     [<a name="AWTSpec"></a>1] AWT spec, <a href=

            
                     "http://java.sun.com/j2se/1.5.0/docs/guide/awt/index.html"

            
                     target=

            
                     "_blank">http://java.sun.com/j2se/1.5.0/docs/guide/awt/index.html</a>

            
                  </p>

            
                  <p>

            
                     [<a name="SwingRef"></a>2] Swing Library Description, <a

            
                     href=

            
                     "http://java.sun.com/j2se/1.5.0/docs/guide/swing/index.html"

            
                     target=

            
                     "_blank">http://java.sun.com/j2se/1.5.0/docs/guide/swing/index.html</a>

            
                  </p>

            
                  <p>

            
                     [<a name="FocusRef"></a>3] AWT Focus Subsystem

            
                     specification, <a href=

            
                     "http://java.sun.com/j2se/1.5.0/docs/api/java/awt/doc-files/FocusSpec.html"

            
                      target=

            
                     "_blank">http://java.sun.com/j2se/1.5.0/docs/api/java/awt/doc-files/FocusSpec.html</a>

            
                  </p>

            
                  <p>


                  </p>

            
                  <p class="backtotop">

            
                     <a href="#top">Back to Top</a>

            
                  </p>

            
                  <p>

            
                     <a name="*">*</a> Other brands and names are the property of

            
                     their respective owners.

            
                  </p>

            
               </body>

            
            </html>