doc/awt/AWT.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content= "text/html; charset=windows-1252"> <title> Abstract Windowing Toolkit </title> <link href="../harmony.css" rel="stylesheet" type="text/css"> </head> <body> <h1 style="text-align: center"> <a name="top"></a>Abstract Window Toolkit Framework </h1> <a href="#Revision_History">Revision History</a> <a href="#Disclaimer_and_Legal_Information">Disclaimer and Legal Information</a> <a href="#About_This_Document">About this Document</a> <a href="#Purpose">Purpose</a> <a href="#Intended_Audience">Intended Audience</a> <a href="#Documentation_Conventions">Documentation Conventions</a> <a href="#Introduction to AWT">Introduction to AWT</a> <a href="#AWTDRL">AWT in DRL</a> <a href="#Event_Handling">Event Handling</a> <blockquote> <a href="#EventTypeDefinition">Native and AWT Events</a> <a href="#EDT">Event Dispatch Thread</a> <a href="#EventPriority">Native and AWT Events Priority</a> <a href="#NativeEvents">Native Events Handling</a> <a href= "#Native_and_AWT_Event_Handlers_Cooperation">Native and AWT Event Handlers Cooperation</a> </blockquote> <a href="#Focus_Subsystem">Focus Subsystem</a> <blockquote> <a href="#Focus_Dispatcher">Focus Dispatcher</a> <a href="#AWT_higher_level">AWT Level</a> <a href="#DRL_Focus_Implementation_Specifics">DRL Focus Implementation Specifics</a> </blockquote> <a href="#Visual_Themes_in_AWT">Visual Themes in AWT</a> <blockquote> <a href="#Default_theme">Default Theme</a> <a href="#Delivered_themes">Derived Themes</a> <a href="#Implementation_details">Implementation Specifics</a> <a href= "#Using_State_Interfaces_in_a_Standard_Component">Using State Interfaces in a Standard Component</a> <a href="#Windows theme">Windows* Theme</a> </blockquote> <a href="#Multi-Threading_support">Multi-threading Support</a> <blockquote> <a href="#WhySynchronize">Why Synchronize</a> <a href="#HowtoSync">How to Synchronize</a> <a href="#WhentoSync">When to Synchronize</a> <a href="#Synchronizer">Synchronizer</a> </blockquote> <a href="#References">References</a> <h1> <a name="Revision_History"></a>Revision History </h1> <table border="0" cellpadding="0" width="100%"> <tr> <td class="TableHeading"> Version </td> <td class="TableHeading"> Version Information </td> <td class="TableHeading"> Date </td> </tr> <tr> <td class="TableCell"> Initial version </td> <td class="TableCell"> Nadya Morozova, Pavel Dolgov: document created. </td> <td class="TableCell"> May 10, 2006 </td> </tr> </table> <h1> <a name="Disclaimer_and_Legal_Information"></a>Disclaimer and Legal Information </h1> Copyright 2005-2006 The Apache Software Foundation or its licensors, as applicable. 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>. 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. <h1> <a name="About_This_Document"></a>About This Document </h1> <h2> <a name="Purpose"></a>Purpose </h2> 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. <h2> <a name="Intended_Audience"></a>Intended Audience </h2> 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. <h2> <a name="Documentation_Conventions"></a>Documentation Conventions </h2> This document uses the <a href="conventions.htm" target= "_blank">unified conventions</a> for the DRL documentation kit. <a href="#top">Back to Top</a> <h1> <a name="Introduction to AWT"></a>Introduction to AWT </h1> 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. In AWT, GUI consists of components, such as buttons, menus, and top-level windows. One of the main AWT features is that all its built-in components are heavy-weight, that is, every Java<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. <h1> <a name="AWTDRL"></a>AWT in DRL </h1> This document describes major design features and internal specifics of the DRL AWT implementation. Further in this document, AWT denotes the DRL implementation for convenience. To summarize, DRL AWT has the following key features: <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> <a href="#top">Back to Top</a> <h2> <a name="Event_Handling"></a>Event Handling </h2> AWT helps applications react to user's actions and traces the system state and the AWT internal state by means of events. Subsequent sections describe the AWT event handling implementation in DRL with focus on the interaction between AWT and the native system, specifically, the GUI subsystem of OS. For information on application events handling, consult the AWT specification [<a href= "#AWTSpec">1</a>]. <h3> <a name="EventTypeDefinition"></a>Native and AWT Events </h3> The DRL AWT framework deals with the following types of events: <ul> <li> Native events generated by the operating system: XEvents on Linux<a href="#*">*</a> and Windows messages (MSG) on Windows<a href="#*">*</a>. </li> <li> AWT events generated and handled by the AWT framework. All AWT events are subclasses of the <code>AWTEvent</code> class and are stored in the AWT event queue represented by the�<code>EventQueue</code> class. </li> </ul> <h3> <a name="EDT"></a>Event Dispatch Thread </h3> AWT has the event dispatch thread (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. <img alt="AWT and native event handling order" src= "images/EventFlow.gif"> Figure 1: Native and AWT Events Handling In more detail, EDT performs the following event loop: <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 name="EventPriority"></a>Native and AWT Events Priority </h3> <ul> <li> AWT events have a higher logical priority than native events. 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> After handling all AWT and native events, EDT waits for a new native event. 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> <a href="#top">Back to Top</a> <h3> <a name="NativeEvents"></a>Native Events Handling </h3> This section defines native events types and the way AWT handles these events based on their type. <a name="Native_Event_classification"></a>Native Events Classification Figure 3 below demonstrates how native events can be classified by their role in the AWT framework. <img alt="Native events: 4 subtypes" src= "images/NativeEventCL.gif"> Figure 3: Native Events Classification <ul> <li> State events signify that a native object corresponding to an AWT object has changed its state. For example, when the user minimizes the window, the window state change native event is generated. </li> <li> Events-signals indicate a sporadic occurrence in the OS, usually, caused by user's actions. For instance, the event caused by a mouse wheel rotation is signal information. </li> <li> Invisible events do not cause AWT event generation and are used only to update the internal data structure. </li> <li> Unused events are concerned to specific OS features that are not supported by AWT, so these events are ignored. </li> </ul> Abstracting the Native Platform Native events handling goes in two stages: the first stage depends on the native platform, and the second stage is the same on all supported platforms. Platform-dependent functionality comprises the Window Toolkit, WTK, in the�<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. <img alt= "Interfaces depending and not depending on the underlying platform" src="images/ImplementationDetails.gif"> Figure 2: Interfaces for Abstracting the Native Platform � 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. <a href="#top">Back to Top</a> <a name="Native_Event_Dispatching"></a>Native Event Dispatching 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. AWT handles relevant native events by following these steps: <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> 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). <img alt="Native events handling by the 4 subtypes" src= "images/NativeEvent.gif"> Figure 4: Native Events Handling by Type <a href="#top">Back to Top</a> <h3> <a name="Native_and_AWT_Event_Handlers_Cooperation"></a> Native and AWT Event Handlers Cooperation </h3> 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. 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. 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. Handling a single event 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*. <img alt="Native events handling by the 4 subtypes" src= "images/EventHanglingInAWT.gif"> Figure 5: Mouse Click Event Handling Numbers in the figure above correspond to the following steps in the event handling flow: <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> <a href="#top">Back to Top</a> Handling nested events Figure 6 is an example of mouse click event handling with the event listener requests keyboard focus on the clicked component. <img alt="Nested Event handling" src= "images/EventHandling.gif"> Figure 6: Mouse Click Event Handling with a Nested Event Numbers in the figure above correspond to the following steps in the event handling flow: <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> 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. <a href="#top">Back to Top</a> <h2> <a name="Focus_Subsystem"></a>Focus Subsystem </h2> The AWT focus subsystem is a set of classes for managing keyboard input focus responsible for: <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> In the DRL implementation, the focus subsystem functionality is distributed among several internal layers: <ul> <li> Window Toolkit (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> <a href="#Focus_Dispatcher">Focus Dispatcher</a> 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> <a href="#AWT_higher_level">AWT level</a> 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> The interaction between user code and these levels of the focus subsystem is shown on Figure 7 below. <img alt="Detailed event handling schema" src= "images/FocusFramework.gif"> Figure 7. Focus Event Data Flow The following code entities perform the major focus subsystem tasks: <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> 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>]. <a href="#top">Back to Top</a> <h3> <a name="Focus_Dispatcher"></a>Focus Dispatcher </h3> 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. <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 focus proxy 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>. <img alt="Events and Output in Event Proxying" src= "images/FocusProxying.gif"> Figure 8. Focus Proxy If the active window is the focused window, no proxying occurs. In this case, the nearest heavyweight ancestor of the focus owner or the focus owner native window itself (if focus owner is a heavy-weight component) has native focus. </dd> </dl> <a href="#top">Back to Top</a> <h3> <a name="AWT_higher_level"></a>AWT Level </h3> 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: <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> 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. After receiving a notification from the native system, WTK requests the AWT level to update the focus state via an internal request. For example, if the native system reports an unsuccessful focus change, a component might lose focus. Note Only certain native focus-related events cause a Java<a href="#*">*</a> focus state update. For example: <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> <a href="#top">Back to Top</a> <h3> <a name="DRL_Focus_Implementation_Specifics"></a>DRL Focus Implementation Specifics </h3> Below, the specific features of DRL implementation are listed compared to the focus specification grouped by their function. <dl> <dt> <a name="KFM"></a>Replacing the DefaultKeyboardFocusManager class </dt> <dd> The keyboard focus manager handles all events in the required order and never synthesizes window activation events. Instead, the focus manager skips the events that do not correspond to the current focus state. Such events can be generated by the private API of this class in response to native events. For example, the keyboard focus manager ignores events sent to the window that has failed to become the focused window because the corresponding AWT event was dispatched and vetoed. When handling the�<code>WINDOW_GAINED_FOCUS</code> event, private methods in the keyboard focus manager set focus on the appropriate child component of the window. </dd> <dt> <a name="Programmatic Traversal"></a> Programmatic Traversal </dt> <dd> Disabling any ancestor of the focus owner, both light-weight and heavy-weight, automatically initiates a focus traversal. </dd> </dl> <a href="#top">Back to Top</a> <h2> <a name="Visual_Themes_in_AWT"></a> Visual Themes in AWT </h2> 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. <h3> <a name="Default_theme"></a>Default theme </h3> 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. The�<code>org.apache.harmony.awt.Theme</code> class implements the default theme. Methods of this class do the following: <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> 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. <a href="#top">Back to Top</a> <h3> <a name="Delivered_themes"></a> Derived themes </h3> 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. 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. <img alt= "OS specific themes as subclasses to the major theme" src= "images/ThemesHierachy.gif"> Figure 9: Hierarchy of Theme Classes � 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. 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. <a href="#top">Back to Top</a> <h3> <a name="Implementation_details"></a>Implementation details </h3> 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. Standard components delegate the painting and size calculation to the currently active theme and pass their state field value as a parameter to every method of the theme. Platform-specific and component-specific code is concentrated in separate helper classes, such as�<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. <a name="ExampleButton"></a>Example 1 This is an example with the�<code>Button</code> component. <pre> public void drawButton(Graphics g, ButtonState s) { drawButtonBackground(g, s); drawButtonText(g, s); } protected void drawButtonBackground(Graphics g, ButtonState s) { DefaultButton.drawBackground(g, s); } protected void drawButtonText(Graphics g, ButtonState s) { DefaultButton.drawText(g, s); } </pre> When designing a custom theme, you may need to override some of these protected methods. 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>. <img alt= "Methods and classes related to state change operations" src="images/ThemesStates.gif"> Figure 10: Inheritance and Composition for Components' State <a href="#top">Back to Top</a> <h3> <a name= "Using_State_Interfaces_in_a_Standard_Component"></a>Using State Interfaces in a Standard Component </h3> 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. This is a part of the�<code>java.awt.Button</code> code that illustrates how to use visual themes in standard components. <pre> class State extends Component.ComponentState implements ButtonState { … } final transient State state = new State(); void prepaint(Graphics g) { toolkit.theme.drawButton(g, state); } </pre> 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. <a href="#top">Back to Top</a> <h3> <a name="Windows theme"></a>Windows<a href="#*">*</a> theme </h3> 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>. 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. The implementation also includes several helper classes: <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> Note 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. <a href="#top">Back to Top</a> <h2> <a name="Multi-Threading_support"></a>Multi-Threading support </h2> 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. <h3> <a name="WhySynchronize"></a>Why synchronize </h3> The main purpose of synchronization is keeping the component hierarchy consistent when component properties are queried and/or modified, so that it potentially affects other components. This includes the parent-child relationships, the child component order, inherited properties, such as the font and the background color, the size and position related properties, as well as visibility, focusable state and other conditions relevant for message handling. Concurrent modifications of these properties can make the AWT framework state inconsistent. For example, if a thread adds a component to a list of child components for a container without updating this component’s field�<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. <a href="#top">Back to Top</a> <h3> <a name="HowtoSync"></a>How to synchronize </h3> When a method or a block of code deals with the data that must not be modified concurrently, a synchronized section is used. The DRL implementation uses a special monitor AWT lock more powerful than built-in Java<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. Example 2 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. <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> 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. <a href="#top">Back to Top</a> <h3> <a name="WhentoSync"></a>When to synchronize </h3> AWT synchronization covers the following classes: <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> The total number of synchronized classes nears 40. Simple data structures, for example,�<code>Rectangle</code> or�<code>Point</code>, are not protected from concurrent modifications for performance reasons. General rules on how to use synchronized sections <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> <a name="SyncExceptions"></a>Exceptions <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> Note 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. <a href="#top">Back to Top</a> <h3> <a name="Synchronizer"></a>Synchronizer </h3> 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. 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. <img alt= "Windows and Linux synchronizers are subclasses of Synchronizer" src="images/threadsMajorClasses.gif"> Figure 11: Synchronizer Classes 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. <a href="#top">Back to Top</a> Synchronizer for Linux<a href="#*">*</a> 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>. <img alt= "user threads access native resources independently of the EDT thread" src="images/ThreadEDT1.gif"> Figure 12: Access to the Native System on Linux<a href= "#*">*</a> <a href="#top">Back to Top</a> Synchronizer for Windows<a href="#*">*</a> 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. 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. <img alt= "user threads access native resources via of the EDT thread" src="images/ThreadEDT2.gif"> Figure 13: Access to the Native System on Windows<a href= "#*">*</a> with EDT 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. 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. <img alt="thread execution flows with deadlock illustrated" src="images/ThreadDeadlock.gif"> Figure 14: Deadlock with the user thread and EDT t1: The user thread starts. t2: EDT starts. t3: The user thread obtains the AWT lock. t4: EDT tries to obtain the AWT lock and gets blocked. t5: The user thread requests a service from EDT via the�<code>NativeServer</code> interface and gets blocked forever because EDT is blocked too. 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. <img alt="EDT modes" src="images/ThreadAWTLock.gif"> Figure 15. EDT Operation 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. <img alt="Thread execution flow with no deadlock" src= "images/ThreadNoDeadlock.gif"> Figure 16: Deadlock Resolution by WinSynchronizer t1: The user thread starts. t2: EDT starts. t3: The user thread obtains the AWT lock. t4: EDT tries to obtain the AWT lock and gets blocked. t5: The user thread requests EDT service and also gets blocked. EDT starts processing the request. t6: EDT finishes processing request. The user thread resumes. t7: The user thread releases the AWT lock, EDT obtains it. t8: The user thread may continue its work or exit. t9: EDT releases the AWT lock. t10: EDT continues operation. <a href="#top">Back to Top</a> <h2> <a name="References"></a> References </h2> [<a name="AWTSpec"></a>1] AWT spec, <a href= "http://java.sun.com/j2se/1.5.0/docs/guide/awt/index.html" target= "_blank">http://java.sun.com/j2se/1.5.0/docs/guide/awt/index.html</a> [<a name="SwingRef"></a>2] Swing Library Description, <a href= "http://java.sun.com/j2se/1.5.0/docs/guide/swing/index.html" target= "_blank">http://java.sun.com/j2se/1.5.0/docs/guide/swing/index.html</a> [<a name="FocusRef"></a>3] AWT Focus Subsystem specification, <a href= "http://java.sun.com/j2se/1.5.0/docs/api/java/awt/doc-files/FocusSpec.html" target= "_blank">http://java.sun.com/j2se/1.5.0/docs/api/java/awt/doc-files/FocusSpec.html</a> � <a href="#top">Back to Top</a> <a name="*">*</a> Other brands and names are the property of their respective owners. </body> </html>

doc/awt/AWT.html (1,580 lines of code) (raw):