Added: incubator/harmony/standard/site/docs/subcomponents/classlibrary/awt.html
URL: http://svn.apache.org/viewvc/incubator/harmony/standard/site/docs/subcomponents/classlibrary/awt.html?view=auto&rev=448575
==============================================================================
--- incubator/harmony/standard/site/docs/subcomponents/classlibrary/awt.html (added)
+++ incubator/harmony/standard/site/docs/subcomponents/classlibrary/awt.html Thu Sep 21 07:56:21 2006
@@ -0,0 +1,1754 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+<!--
+Copyright 1999-2004 The Apache Software Foundation
+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
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+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.
+-->
+
+
+<!-- start the processing -->
+ <!-- ====================================================================== -->
+ <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+ <!-- Main Page Section -->
+ <!-- ====================================================================== -->
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+
+ <meta name="author" value="Harmony Documentation Team">
+ <meta name="email" value="harmony-dev@incubator.apache.org">
+
+
+
+
+
+
+
+ <title>Apache Harmony - Apache Harmony</title>
+
+ <link rel="Stylesheet" type="text/css" href="/harmony/site.css"/>
+ </head>
+
+ <body>
+ <table width="100%" cellspacing="0">
+ <!-- TOP IMAGE -->
+ <tr>
+ <td align='LEFT'>
+ <table><tr><td>
+ <td>
+<a href="http://incubator.apache.org/harmony/"><img src="../../images/harmony-logo.png" alt="Apache Harmony" /></a>
+</td>
+</td>
+ </td></tr></table>
+ </td>
+ <td align='RIGHT'>
+ <a href="http://incubator.apache.org/harmony/">
+ <img src="http://incubator.apache.org/harmony/images/apache-incubator-logo.png"
+ alt="Apache Harmony" /></a>
+ </td>
+ </tr>
+ </table>
+ <table width="100%" cellspacing="4">
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+
+ <tr>
+ <!-- LEFT SIDE NAVIGATION -->
+ <td class="menuItem" width="20%" nowrap="true">
+
+ <!-- special ACon Logo - leave here for next time -->
+ <a href="http://www.us.apachecon.com/">
+ <img src="http://www.apache.org/ads/ApacheCon/240x120-2006-us.gif"
+ alt="ApacheCon US 2006" />
+ </a>
+
+ <!-- regular menu -->
+
+
+ <!-- ============================================================ -->
+
+ <p class="menuItem"><strong>General</strong></p>
+ <ul>
+ <li class="menuItem"> <a href="../../index.html">Home</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../license.html">License</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../contribution_policy.html">Contribution Policy</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../guidelines.html">Project Guidelines</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="http://www.apache.org/">ASF</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../downloads.html">Downloads</a>
+</li>
+
+
+
+ </ul>
+ <p class="menuItem"><strong>Community</strong></p>
+ <ul>
+ <li class="menuItem"> <a href="../../get-involved.html">Get Involved</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../contributors.html">Committers</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../mailing.html">Mailing Lists</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../documentation/documentation.html">Documentation</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../faq.html">FAQ</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="http://wiki.apache.org/harmony">Wiki</a>
+</li>
+
+
+
+ </ul>
+ <p class="menuItem"><strong>Development</strong></p>
+ <ul>
+ <li class="menuItem"> <a href="../../status.html">How Are We Doing?</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../roadmap.html">Road Map / TODO</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../svn.html">Source Code</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="http://issues.apache.org/jira/browse/HARMONY">JIRA</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../related.html">Other Projects</a>
+</li>
+
+
+
+ </ul>
+ <p class="menuItem"><strong>Subcomponents</strong></p>
+ <ul>
+ <li class="menuItem"> <a href="../../subcomponents/buildtest/index.html">Build-Test Framework</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../subcomponents/classlibrary/index.html">Class Library</a>
+</li>
+
+
+ <table>
+ <tr><td class="menuItem">
+ <a href="../../subcomponents/classlibrary/status.html">Status</a>
+ </td></tr>
+ </table>
+
+ <li class="menuItem"> <a href="../../subcomponents/drlvm/index.html">DRLVM</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../subcomponents/jchevm/index.html">JCHEVM</a>
+</li>
+
+
+
+ </ul>
+ </td>
+ <td width="80%" valign="top"><a name="top"></a>
+
+ <div>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type"
+ content="text/html; charset=windows-1252" />
+ <title>
+ Abstract Windowing Toolkit
+ </title>
+ <link href="drl.css" rel="stylesheet" type="text/css" />
+ </head>
+ <body>
+ <h1 style="text-align: center">
+ <a id="top" 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 id="Revision_History" name="Revision_History"></a>Revision History
+ </h1>
+ <table border="0" cellpadding="0" width="100%">
+ <tr>
+ <th class="TableHeading">
+ Version
+ </th>
+ <th class="TableHeading">
+ Version Information
+ </th>
+ <th class="TableHeading">
+ Date
+ </th>
+ </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>
+ <tr>
+ <td class="TableCell">
+ Formatting update
+ </td>
+ <td class="TableCell">
+ Nadya Morozova
+ </td>
+ <td class="TableCell">
+ September 21, 2006
+ </td>
+ </tr>
+ </table>
+ <h1>
+ <a id="Disclaimer_and_Legal_Information"
+ 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 id="About_This_Document" name="About_This_Document"></a>About This
+ Document
+ </h1>
+ <h2>
+ <a id="Purpose" 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 id="Intended_Audience" 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 id="Documentation_Conventions"
+ 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 id="Introduction to AWT"
+ 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 id="AWTDRL" 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 id="Event_Handling" 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 id="EventTypeDefinition" 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 id="EDT" 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’s event listeners of
+ the <code>EventListener</code> interface. Applications should
+ implement appropriate listeners' interfaces to react to specific
+ events.
+ </li>
+ </ol>
+ <h3>
+ <a id="EventPriority" 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 id="NativeEvents" 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 id="Native_Event_classification"
+ 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 id="Native_Event_Dispatching"
+ 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 id="Native_and_AWT_Event_Handlers_Cooperation"
+ 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 id="Focus_Subsystem" 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 id="Focus_Dispatcher" 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 id="AWT_higher_level" 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 id="DRL_Focus_Implementation_Specifics"
+ 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 id="KFM" 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 id="Programmatic Traversal" 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 id="Visual_Themes_in_AWT" 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 id="Default_theme" 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 id="Delivered_themes" 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 id="Implementation_details"
+ 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="example">
+ <a id="ExampleButton" name="ExampleButton"></a>Example 1
+ </p>
+ <p class="exampletext">
+ This is an example with the <code>Button</code> component.
+ </p>
+<pre class="exampletext">
+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,
+ <code>Component</code> actually means
+ <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 id="Using_State_Interfaces_in_a_Standard_Component"
+ 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 { … }
+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 id="Windows theme" 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 id="Multi-Threading_support"
+ 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 id="WhySynchronize" 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’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 id="HowtoSync" 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="example">
+ Example 2
+ </p>
+ <p class="exampletext">
+ 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();
+…
+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 id="WhentoSync" 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 id="SyncExceptions" 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 id="Synchronizer" 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’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’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 id="References" name="References"></a> References
+ </h2>
+ <p>
+ [<a id="AWTSpec" 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 id="SwingRef" 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 id="FocusRef" 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>
+ (C) Copyright 2005-2006 Intel Corporation
+ </p>
+ <p>
+ <a id="*" name="*">*</a> Other brands and names are the property of
+ their respective owners.
+ </p>
+ </body>
+</html>
+
+</div>
+ </td>
+ </tr>
+
+ <!-- FOOTER -->
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+ <tr><td colspan="2">
+ <div class="special"><em>
+ Copyright © 2003-2006, The Apache Software Foundation
+ </em></div>
+ </td></tr>
+ </table>
+ </body>
+ </html>
+<!-- end the processing -->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
|