harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ge...@apache.org
Subject svn commit: r448759 [2/8] - in /incubator/harmony/standard/site: ./ docs/ docs/documentation/ docs/subcomponents/buildtest/ docs/subcomponents/classlibrary/ docs/subcomponents/drlvm/ docs/subcomponents/jchevm/ docs/subcomponents/stresstest/ xdocs/ xdoc...
Date Fri, 22 Sep 2006 01:09:40 GMT
Modified: 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=diff&rev=448759&r1=448758&r2=448759
==============================================================================
--- incubator/harmony/standard/site/docs/subcomponents/classlibrary/awt.html (original)
+++ incubator/harmony/standard/site/docs/subcomponents/classlibrary/awt.html Thu Sep 21 18:09:38 2006
@@ -36,7 +36,7 @@
             
             <title>Apache Harmony - Apache Harmony</title>
 
-                                <link rel="Stylesheet" type="text/css" href="/harmony/site.css"/>
+                                <link rel="Stylesheet" type="text/css" href="site.css"/>
         </head>
 
         <body>        
@@ -204,1515 +204,1515 @@
                     <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&rsquo;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 { &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 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&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 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();
-&hellip;
-public Color getBackground() {
-    toolkit.lockAWT();
-    try {
-        if ((backColor == null) &amp;&amp; (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&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 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>
-
+<!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&rsquo;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>

[... 896 lines stripped ...]


Mime
View raw message