archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-09-18 01:54:47 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html

Browse source 
8183508: multi_tsc.html should be updated
8181289: Invalid HTML 5 in AWT/Swing docs

Reviewed-by: prr, jjg
This commit is contained in:
Sergey Bylokhov 2017-11-29 15:11:37 -08:00
parent 625c3fd013
commit f968e1a670
18 changed files with 1235 additions and 1210 deletions
Download patch file Download diff file Expand all files Collapse all files

51
src/java.desktop/share/classes/java/awt/doc-files/AWTThreadIssues.html
View file

@ -1,5 +1,11 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>AWT Threading Issues</title>
</head>
<!--
Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved.
Copyright (c) 2002, 2017, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
@ -23,16 +29,11 @@
questions.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title></title>
</head>
<body bgcolor=white>
<body>
<h1 align=center>AWT Threading Issues</h1>
<h1>AWT Threading Issues</h1>
<a name="ListenersThreads"></a>
<a id="ListenersThreads"></a>
<h2>Listeners and threads</h2>
Unless otherwise noted all AWT listeners are notified on the event
@ -41,7 +42,7 @@ during dispatching, but the changes only effect subsequent notification.
<br>For example, if a key listeners is added from another key listener, the
newly added listener is only notified on subsequent key events.
<a name="Autoshutdown"></a>
<a id="Autoshutdown"></a>
<h2>Auto-shutdown</h2>
According to
@ -53,7 +54,7 @@ The virtual machine terminates all its activity and exits when
one of two things happens:
<ul>
<li> All the threads that are not daemon threads terminate.
<li> Some thread invokes the <code>exit</code> method of class
<li> Some thread invokes the <code>exit</code> method of class
<code>Runtime</code> or class <code>System</code>, and the exit
operation is permitted by the security manager.
</ul>
@ -84,13 +85,15 @@ this machinery are as follows:
posted to the <code>EventQueue</code> can be coalesced) are
dispatched:
<ul>
<li> Sequentially.
<dl><dd> That is, it is not permitted that several events from
<li>
<dl><dt>Sequentially.
<dd> That is, it is not permitted that several events from
this queue are dispatched simultaneously. </dd></dl>
<li> In the same order as they are enqueued.
<dl><dd> That is, if <code>AWTEvent</code>&nbsp;A is enqueued
<li>
<dl><dt>In the same order as they are enqueued.
<dd> That is, if <code>AWTEvent</code>&nbsp;A is enqueued
to the <code>EventQueue</code> before
<code>AWTEvent</code>&nbsp;B then event B will not be
<code>AWTEvent</code>&nbsp;B then event B will not be
dispatched before event A.</dd></dl>
</ul>
<li> There is at least one alive non-daemon thread while there is at
@ -98,7 +101,7 @@ this machinery are as follows:
application (see
<a href="../Component.html#isDisplayable()"><code>Component.isDisplayable</code></a>).
</ul>
The implications of the third restriction are as follows:
The implications of the third restriction are as follows:
<ul>
<li> The JVM will exit if some thread invokes the <code>exit</code>
method of class <code>Runtime</code> or class <code>System</code>
@ -108,8 +111,8 @@ The implications of the third restriction are as follows:
displayable component.
</ul>
It depends on the implementation if and when the non-daemon helper
threads are terminated once all components are made undisplayable.
The implementation-specific details are given below.
threads are terminated once all components are made undisplayable.
The implementation-specific details are given below.
<h3>
Implementation-dependent behavior.
@ -147,7 +150,7 @@ cleanly without calling <code>System.exit</code> must:
</ul>
Note, that while an application following these recommendations will
exit cleanly under normal conditions, it is not guaranteed that it
will exit cleanly in all cases. Two examples:
will exit cleanly in all cases. Two examples:
<ul>
<li> Other packages can create displayable components for internal
needs and never make them undisplayable. See
@ -156,7 +159,7 @@ will exit cleanly in all cases. Two examples:
<a href="http://bugs.sun.com/view_bug.do?bug_id=4671025">
4671025</a>, and
<a href="http://bugs.sun.com/view_bug.do?bug_id=4465537">
4465537</a>.
4465537</a>.
<li> Both Microsoft Windows and X11 allow an application to send native
events to windows that belong to another application. With this
feature it is possible to write a malicious program that will
@ -165,10 +168,10 @@ will exit cleanly in all cases. Two examples:
</ul>
On the other hand, if you require the JVM to continue running even after
the application has made all components undisplayable you should start a
non-daemon thread that blocks forever.
non-daemon thread that blocks forever.
<pre>
<...>
&lt;...&gt;
Runnable r = new Runnable() {
public void run() {
Object o = new Object();
@ -183,7 +186,7 @@ non-daemon thread that blocks forever.
Thread t = new Thread(r);
t.setDaemon(false);
t.start();
<...>
&lt;...&gt;
</pre>
<cite>The Java&trade; Virtual Machine Specification</cite>

33
src/java.desktop/share/classes/java/awt/doc-files/DesktopProperties.html
View file

@ -1,5 +1,11 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>AWT Desktop Properties</title>
</head>
<!--
Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
@ -23,14 +29,9 @@
questions.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title></title>
</head>
<body bgcolor=white>
<body>
<h1 align=center>AWT Desktop Properties</h1>
<h1>AWT Desktop Properties</h1>
The following refers to standard AWT desktop properties that
may be obtained via the
@ -76,7 +77,7 @@ here, and their value types.
</table>
<h2>Desktop Font Rendering Hints</h2>
<b>Desktop Property: <A name="awt.font.desktophints">"awt.font.desktophints"</A></b>
<b>Desktop Property: <a id="awt.font.desktophints">"awt.font.desktophints"</A></b>
<p>
Modern desktops support various forms of text antialiasing (font smoothing).
<p>
@ -116,7 +117,7 @@ An application can listen for changes in the property
using a <a href="../../beans/PropertyChangeListener.html">
<code>PropertyChangeListener</code></a> :
<pre><code>
tk.addPropertyChangeListener("awt.font.desktophints", pcl);
tk.addPropertyChangeListener("awt.font.desktophints", pcl);
</code></pre>
Listening for changes is recommended as users can, on rare occasions,
reconfigure a desktop environment whilst applications are running
@ -194,7 +195,7 @@ if (map != null) {
and dynamic updates will not be available. This is a typical behaviour if
the JDK does not recognise the desktop environment, or it is one which
has no such settings. The <b>Headless</b> toolkit is one such example.
Therefore it is important to test against null before using the map.
Therefore it is important to test against null before using the map.
<br><br>
<li>If non-null the value will be a <code>Map</code> of
<code>RenderingHints</code> such that every key is an instance of
@ -229,7 +230,7 @@ determine that there is a non-null return for any screen device using
the per-device property name.
</ul>
<h2>Mouse Functionality</h2>
<b>Desktop Property: <A name="sun.awt.enableExtraMouseButtons">"sun.awt.enableExtraMouseButtons"</A></b>
<b>Desktop Property: <a id="sun.awt.enableExtraMouseButtons">"sun.awt.enableExtraMouseButtons"</A></b>
<p>
This property determines if events from extra mouse buttons (if they are exist and are
enabled by the underlying operating system) are allowed to be processed and posted into
@ -245,7 +246,7 @@ Once set on application startup, it is impossible to change this value after.
Current value could also be queried using getDesktopProperty("sun.awt.enableExtraMouseButtons")
method.
<br>
If the property is set to {@code true} then
If the property is set to {@code true} then
<ul>
<li> it is still legal to create {@code MouseEvent} objects with
standard buttons and, if the mouse has more
@ -256,13 +257,13 @@ from 0 up to {@link java.awt.MouseInfo#getNumberOfButtons() getNumberOfButtons()
and {@code Robot.mouseRelease()} methods and, if the mouse has more then three buttons,
it is also legal to use masks for existing extended mouse buttons.
That way, if there are more then three buttons on the mouse then it is allowed to
use button masks corresponding to the buttons
use button masks corresponding to the buttons
in the range from 1 up to {@link java.awt.MouseInfo#getNumberOfButtons() getNumberOfButtons()}
</ul>
<br>
If the property is set to {@code false} then
If the property is set to {@code false} then
<ul>
<li> it is legal to create {@code MouseEvent} objects with standard buttons
<li> it is legal to create {@code MouseEvent} objects with standard buttons
only: {@code NOBUTTON}, {@code BUTTON1}, {@code BUTTON2} and
{@code BUTTON3}
<li> it is legal to use standard button masks only:

149
src/java.desktop/share/classes/java/awt/doc-files/FocusSpec.html
View file

@ -1,5 +1,11 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>The AWT Focus Subsystem</title>
</head>
<!--
Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
Copyright (c) 2001, 2017, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
@ -23,15 +29,8 @@
questions.
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>The AWT Focus Subsystem</title>
</head>
<body bgcolor="white">
<h1 align=center>The AWT Focus Subsystem</h1>
<body>
<h1>The AWT Focus Subsystem</h1>
<p>
Prior to Java 2 Standard Edition, JDK 1.4, the AWT focus subsystem
@ -57,8 +56,8 @@
determining the "opposite" Component involved in the focus or
activation change. For example, when a Component received a FOCUS_LOST
event, it had no way of knowing which Component was gaining
focus. Since Microsoft Windows provides this functionality for free,
developers migrating from Microsoft Windows C/C++ or Visual Basic to
focus. Since Microsoft Windows provides this functionality for free,
developers migrating from Microsoft Windows C/C++ or Visual Basic to
Java had been frustrated by the omission.
<p>
To address these and other deficiencies, we have designed a new focus
@ -101,7 +100,7 @@
<li><a href=#Incompatibilities>Incompatibilities with Previous Releases</a>
</ul>
<a name="Overview"></a>
<a id="Overview"></a>
<h3>Overview of KeyboardFocusManager</h3>
<p>
The focus model is centralized around a single class,
@ -160,7 +159,7 @@
define new focus cycle but only modifies the order by which its
children are traversed "forward" and "backward". Focus traversal
policy provider can be set using
<code>setFocusTraversalPolicyProvider</code> on the Container.
<code>setFocusTraversalPolicyProvider</code> on the Container.
</ol>
<p>
@ -180,7 +179,7 @@
descendants.
<p>
Here is an example:<br> <img src="FocusCycle.gif" align=middle
Here is an example:<br> <img src="FocusCycle.gif"
alt="Three groups as described below: ABCF BDE and DGH. "><br>
<p>Assume the following:
@ -193,7 +192,7 @@
<li><b>G</b>, <b>H</b>, <b>E</b>, and <b>F</b> are all
<code>Component</code>s.
</ul>
There are a total of three focus cycle roots in this example:
<ol>
@ -213,7 +212,7 @@
implementation in the <code>DefaultKeyboardFocusManager</code> class.
<a name="BrowserContexts"></a>
<a id="BrowserContexts"></a>
<h3>KeyboardFocusManager and Browser Contexts</h3>
<p>
Some browsers partition applets in different code bases into separate
@ -229,7 +228,7 @@ contexts there may be, however, there can never be more than one focus
owner, focused Window, or active Window, per ClassLoader.
<a name="KeyEventDispatcher"></a>
<a id="KeyEventDispatcher"></a>
<h3>KeyEventDispatcher and KeyEventPostProcessor</h3>
<p>
While the user's KeyEvents should generally be delivered to the focus
@ -272,7 +271,7 @@ Like KeyEventDispatcher, KeyboardFocusManager also implements
KeyEventPostProcessor, and similar restrictions apply to its use in
that capacity.
<a name="FocusEventAndWindowEvent"></a>
<a id="FocusEventAndWindowEvent"></a>
<h3>FocusEvent and WindowEvent</h3>
<p>
The AWT defines the following six event types central to the focus
@ -296,7 +295,7 @@ model in two different <code>java.awt.event</code> classes:
not a Frame or Dialog) when it is no longer the active Window.
</ol>
<a name="EventDelivery"></a>
<a id="EventDelivery"></a>
<h3>Event Delivery</h3>
<p>
If the focus is not in java application and the user clicks on a focusable
@ -347,7 +346,7 @@ rejects the focus change. See <a href="#FocusAndVetoableChangeListener">Focus
and VetoableChangeListener</a>.
<a name="OppositeComponents"></a>
<a id="OppositeComponents"></a>
<h3>Opposite Components and Windows</h3>
<p>
Each event includes information about the "opposite" Component or
@ -371,7 +370,7 @@ a pure Swing application can ignore this platform restriction when
using the opposite Component of a focus change that occurred within a
top-level Window.
<a name="TemporaryFocusEvents"></a>
<a id="TemporaryFocusEvents"></a>
<h3>Temporary FocusEvents</h3>
<p>
<code>FOCUS_GAINED</code> and <code>FOCUS_LOST</code> events are
@ -380,7 +379,7 @@ marked as either temporary or permanent.
Temporary <code>FOCUS_LOST</code> events are sent when a Component is
losing the focus, but will regain the focus shortly. These events
can be useful when focus changes are used as triggers for validation
of data. For instance, a text Component may want to commit its
of data. For instance, a text Component may want to commit its
contents when the user begins interacting with another Component,
and can accomplish this by responding to <code>FOCUS_LOST</code> events.
However, if the <code>FocusEvent</code> received is temporary,
@ -402,8 +401,8 @@ occur.
When a Component receives a temporary <code>FOCUS_LOST</code> event,
the event's opposite Component (if any) may receive a temporary
<code>FOCUS_GAINED</code> event, but could also receive a permanent
<code>FOCUS_GAINED</code> event. Showing a Menu or PopupMenu, or
clicking or dragging a Scrollbar, should generate a temporary
<code>FOCUS_GAINED</code> event. Showing a Menu or PopupMenu, or
clicking or dragging a Scrollbar, should generate a temporary
<code>FOCUS_GAINED</code> event. Changing the focused Window,
however, will yield a permanent <code>FOCUS_GAINED</code> event
for the new focus owner.
@ -416,7 +415,7 @@ behavior for this method can be guaranteed only for lightweight
Components. This method is not intended for general use, but exists
instead as a hook for lightweight Component libraries, such as Swing.
<a name="FocusTraversal"></a>
<a id="FocusTraversal"></a>
<h3>Focus Traversal</h3>
<p>
Each Component defines its own Set of focus traversal keys for a given
@ -428,11 +427,11 @@ a Set is not explicitly defined for a Component, that Component
recursively inherits a Set from its parent, and ultimately from a
context-wide default set on the current <code>KeyboardFocusManager</code>.
<p>
Using the <code>AWTKeyStroke</code> API, client code can specify
on which of two specific KeyEvents, <code>KEY_PRESSED</code> or
Using the <code>AWTKeyStroke</code> API, client code can specify
on which of two specific KeyEvents, <code>KEY_PRESSED</code> or
<code>KEY_RELEASED</code>, the focus traversal operation will occur.
Regardless of which KeyEvent is specified, however, all KeyEvents
related to the focus traversal key, including the associated
related to the focus traversal key, including the associated
<code>KEY_TYPED</code> event, will be consumed, and will not be
dispatched to any Component. It is a runtime error to specify a
<code>KEY_TYPED</code> event as mapping to a focus traversal operation,
@ -475,7 +474,7 @@ Components represent the next and previous Components to focus during
normal focus traversal. Thus, the current
<code>KeyboardFocusManager</code> maintains a reference to the
"current" focus cycle root, which is global across all contexts. The
current focus cycle root is used to resolve the ambiguity.
current focus cycle root is used to resolve the ambiguity.
<p>
For up-cycle traversal, the focus owner is set to the current focus
owner's focus cycle root, and the current focus cycle root is set to
@ -491,10 +490,10 @@ current focus owner. If the current focus owner is not a focus cycle
root, then no focus traversal operation occurs.
<a name="FocusTraversalPolicy"></a>
<a id="FocusTraversalPolicy"></a>
<h3>FocusTraversalPolicy</h3>
<p>
A <code>FocusTraversalPolicy</code> defines the order in which Components within
a particular focus cycle root or focus traversal policy provider are
traversed. Instances of <code>FocusTraversalPolicy</code> can be shared across
@ -524,7 +523,7 @@ five algorithms:
</ol>
<p>
A <code>FocusTraversalPolicy</code> may optionally provide an
A <code>FocusTraversalPolicy</code> may optionally provide an
algorithm for the following:
<blockquote>
Given a Window, the "initial" Component in that Window. The initial
@ -551,7 +550,7 @@ set, then a Container inherits its policy from its nearest focus-cycle-root
ancestor. Top-levels initialize their focus traversal policies using the context
default policy. The context default policy is established by using
KeyboardFocusManager. <code>setDefaultFocusTraversalPolicy</code>.
<p>
AWT provides two standard <code>FocusTraversalPolicy</code>
implementations for use by client code.
@ -573,14 +572,14 @@ implementations for use by client code.
<li><code>DefaultFocusTraversalPolicy</code>: A subclass of
<code>ContainerOrderFocusTraversalPolicy</code> which redefines
the fitness test. If client code has explicitly set the
focusability of a Component by either overriding
focusability of a Component by either overriding
<code>Component.isFocusTraversable()</code> or
<code>Component.isFocusable()</code>, or by calling
<code>Component.setFocusable(boolean)</code>, then a
<code>Component.setFocusable(boolean)</code>, then a
<code>DefaultFocusTraversalPolicy</code> behaves exactly
like a <code>ContainerOrderFocusTraversalPolicy</code>. If,
however, the Component is relying on default focusability, then a
<code>DefaultFocusTraversalPolicy</code> will reject all
<code>DefaultFocusTraversalPolicy</code> will reject all
Components with non-focusable peers.
<br>
The focusability of a peer is implementation-dependent. Sun
@ -627,7 +626,7 @@ InternalFrameFocusTraversalPolicy.
</ol>
<p>
The figure below shows an implicit focus transfer:
<br><img src="ImplicitFocusTransfer.gif" align=middle alt="Implicit focus transfer."><br>
<br><img src="ImplicitFocusTransfer.gif" alt="Implicit focus transfer."><br>
Assume the following:
<ul>
@ -653,7 +652,7 @@ Containers by default.
All other applications, including pure AWT applications, will use
<code>DefaultFocusTraversalPolicy</code> by default.
<a name="FocusTraversalPolicyProviders"></a>
<a id="FocusTraversalPolicyProviders"></a>
<h3>Focus Traversal Policy Providers</h3>
<p>
A Container that isn't a focus cycle root has an option to provide a
@ -674,7 +673,7 @@ All other applications, including pure AWT applications, will use
If focus traversal policy provider property is set on a focus cycle root, it
isn't considered a focus traversal policy provider and behaves just like any
other focus cycle root.
<p>
The main difference between focus cycle roots and focus traversal policy
providers is that the latter allow focus to enter and leave them just as all other
@ -740,7 +739,7 @@ All other applications, including pure AWT applications, will use
</ul>
</ul>
<a name="ProgrammaticTraversal"></a>
<a id="ProgrammaticTraversal"></a>
<h3>Programmatic Traversal</h3>
<p>
In addition to user-initiated focus traversal, client code can
@ -811,7 +810,7 @@ and there is no other Component to focus, then the focus owner remains
unchanged.
<a name="Focusability"></a>
<a id="Focusability"></a>
<h3>Focusability</h3>
<p>
A focusable Component can become the focus owner ("focusability") and
@ -825,7 +824,7 @@ default, all Components return true from this method. Client code can
change this default by calling Component.setFocusable(boolean).
<a name="FocusableWindows"></a>
<a id="FocusableWindows"></a>
<h3>Focusable Windows</h3>
<p>
To support palette windows and input methods, client code can prevent
@ -877,7 +876,7 @@ Since not all platforms support cross-Window focus changes (see
all such focus change requests will fail. In this case, the global
focus owner will be cleared and the focused Window will remain unchanged.
<a name="RequestingFocus"></a>
<a id="RequestingFocus"></a>
<h3>Requesting Focus</h3>
<p>
@ -949,7 +948,7 @@ The Component class also supports variants of <code>requestFocus</code> and
a temporary state.
See <a href="#TemporaryFocusEvents">Temporary FocusEvents</a>
<a name="FocusAndPropertyChangeListener"></a>
<a id="FocusAndPropertyChangeListener"></a>
<h3>Focus and PropertyChangeListener</h3>
<p>
Client code can listen to changes in context-wide focus state, or to
@ -957,7 +956,7 @@ changes in focus-related state in Components, via
PropertyChangeListeners.
<p>
The <code>KeyboardFocusManager</code> supports the following properties:
<ol>
<li><code>focusOwner</code>: the focus owner
<li><code>focusedWindow</code>: the focused Window
@ -977,7 +976,7 @@ The <code>KeyboardFocusManager</code> supports the following properties:
<p>
A <code>PropertyChangeListener</code> installed on the current
<code>KeyboardFocusManager</code> will only see these changes within
the <code>KeyboardFocusManager</code>'s context, even though the
the <code>KeyboardFocusManager</code>'s context, even though the
focus owner, focused Window, active Window, and current focus cycle
root comprise the global focus state shared by all contexts.
We believe this is less intrusive than requiring client code to pass
@ -1001,7 +1000,7 @@ In addition to the Component properties, Container supports the
following focus-related properties:
<ol>
<li><code>downCycleFocusTraversalKeys</code>: the Container's Set of
<li><code>downCycleFocusTraversalKeys</code>: the Container's Set of
<code>DOWN_CYCLE_TRAVERSAL_KEYS</code>
<li><code>focusTraversalPolicy</code>: the Container's focus
traversal policy
@ -1020,10 +1019,10 @@ Window will never see a <code>PropertyChangeEvent</code> for the
<code>focusCycleRoot</code> property.
A Window is always a focus cycle root; this property cannot change.
<p>
<a name="FocusAndVetoableChangeListener"></a>
<a id="FocusAndVetoableChangeListener"></a>
<h3>Focus and VetoableChangeListener</h3>
<p>
The <code>KeyboardFocusManager</code> also supports
The <code>KeyboardFocusManager</code> also supports
<code>VetoableChangeListener</code>s for the following properties:
<ol>
@ -1054,13 +1053,13 @@ event, a <code>KeyboardFocusManager</code> is not required to search the
<code>KeyboardFocusManager</code> is free to attempt to
dispatch this event and it is the responsibility of the
<code>VetoableChangeListener</code> to veto it as well. In addition,
during processing of the <code>FOCUS_GAINED</code> event, the
during processing of the <code>FOCUS_GAINED</code> event, the
<code>KeyboardFocusManager</code> may attempt to resync the global
focus state by synthesizing another <code>FOCUS_LOST</code> event.
This event must be vetoed just as the first <code>FOCUS_LOST</code> event was.
<p>
A <code>KeyboardFocusManager</code> may not hold any locks while
notifying <code>PropertyChangeListener</code>s of a state change.
A <code>KeyboardFocusManager</code> may not hold any locks while
notifying <code>PropertyChangeListener</code>s of a state change.
This requirement is relaxed for <code>VetoableChangeListeners</code>,
however. Therefore, client-definied <code>VetoableChangeListener</code>s
should avoid acquiring additional locks inside
@ -1089,13 +1088,13 @@ to anticipate this situation could lead to an infinite cycle of
vetoed focus changes and recovery attempts.
<a name="ZOrder"></a>
<a id="ZOrder"></a>
<h3>Z-Order</h3>
<p>
On some native windowing systems, the Z-order of a Window can affect
its focused or active (if applicable) state. On Microsoft Windows, the
top-most Window is naturally the focused Window as well. However, on
Solaris, many window managers use a point-to-focus model that ignores
its focused or active (if applicable) state. On Microsoft Windows, the
top-most Window is naturally the focused Window as well. However, on
Solaris, many window managers use a point-to-focus model that ignores
Z-order in determining the focused Window.
When focusing or activating Windows, the AWT adheres to the UI
@ -1114,8 +1113,8 @@ is platform-dependent. In JDK 1.4, the behavior of these methods on
Microsoft Windows and Solaris is as follows:
<ul>
<li><code>Window.toFront()</code>:<br>
<b>Microsoft Windows</b>: The Window is moved to front, if possible.
While we will always be able to move this Window in front of other
<b>Microsoft Windows</b>: The Window is moved to front, if possible.
While we will always be able to move this Window in front of other
Windows in the same VM, Windows 98 and Windows 2000 do not allow an
application to bring any of its windows to the front unless one
of that application's windows is already in the foreground. In
@ -1129,15 +1128,15 @@ Microsoft Windows and Solaris is as follows:
window manager, the focused Window will remain unchanged.
<li><code>Window.toBack()</code>:<br>
<b>Microsoft Windows</b>: The Window is moved to back. Note however
that Microsoft Windows insists that an owned Window always be in
front of all of its recursive owners. Thus, after the completion of
this operation, the Window may not be the lowest Java Window in the
Z-order. If the Window, or any of its owners, was the focused Window,
<b>Microsoft Windows</b>: The Window is moved to back. Note however
that Microsoft Windows insists that an owned Window always be in
front of all of its recursive owners. Thus, after the completion of
this operation, the Window may not be the lowest Java Window in the
Z-order. If the Window, or any of its owners, was the focused Window,
then the focused Window is reset to the top-most Window in the VM.
<br>
<b>Solaris</b>: The Window is moved to back. Like Microsoft Windows,
some window managers insist than an owned Window always be in front
<b>Solaris</b>: The Window is moved to back. Like Microsoft Windows,
some window managers insist than an owned Window always be in front
of all of its recursive owners. Thus, after the completion of this
operation, the Window may not be the lowest Java Window in the
Z-order. If the Window was the focused Window, it will lose
@ -1156,7 +1155,7 @@ Microsoft Windows and Solaris is as follows:
<li><code>Window.hide()/Window.setVisible(false)/Window.dispose()/
Frame.setState(ICONIFIED)</code>:<br>
<b>Microsoft Windows</b>: If the Window was the focused Window, the focused
<b>Microsoft Windows</b>: If the Window was the focused Window, the focused
Window is reset to a window chosen by the OS, or to no window. The
window may be in a native application, or a Java application in
another VM.
@ -1169,7 +1168,7 @@ Microsoft Windows and Solaris is as follows:
application in another VM.
</ul>
<a name="ReplacingDefaultKeyboardFocusManager"></a>
<a id="ReplacingDefaultKeyboardFocusManager"></a>
<h3>Replacing DefaultKeyboardFocusManager</h3>
<p>
<code>KeyboardFocusManager</code>s are pluggable at the browser context
@ -1238,7 +1237,7 @@ focused Window:
heavyweight Container, not the focus owner.
<li>A <code>FOCUS_LOST</code> event must be retargeted to the focus
owner. Again, this is necessary because the peer layer is
unaware of lightweight Components.
unaware of lightweight Components.
<li>A <code>WINDOW_LOST_FOCUS</code> event must be retargeted to
the focused Window. The implementation of the Window class
may cause the native focused Window to differ from the Java
@ -1269,7 +1268,7 @@ value just set. Rejections occur in three standard cases:
to set the global focus owner to a non-focusable Component.
<li>If the <code>KeyboardFocusManager</code> attempts
to set the global focused Window to a non-focusable Window.
<li>If the change is rejected by an installed
<li>If the change is rejected by an installed
<code>VetoableChangeListener</code>.
</ul>
<p>
@ -1302,13 +1301,13 @@ and VetoableChangeListener</a>.
recent focus owner.
<li>The <code>KeyboardFocusManager</code> must ensure that the
opposite Component or Window are as accurate as the native
windowing platform permits. For example, the
windowing platform permits. For example, the
<code>KeyboardFocusManager</code> may need to
retarget the opposite Component to a lightweight child of the
heavyweight initially specified by the peer layer.
<br>
If the peer layer states that the opposite Component or Window is
<code>null</code>, it is acceptable for the
<code>null</code>, it is acceptable for the
<code>KeyboardFocusManager</code> to propagate
this value. <code>null</code> indicates that it is highly
probably that no other Component or Window was involved
@ -1325,7 +1324,7 @@ and VetoableChangeListener</a>.
events.
</ul>
<a name="Incompatibilities"></a>
<a id="Incompatibilities"></a>
<h3>Incompatibilities with Previous Releases</h3>
<p><b>Cross-platform changes:</b>
<ol>
@ -1343,7 +1342,7 @@ and VetoableChangeListener</a>.
<li>KeyListeners installed on <code>Component</code>s
will no longer see <code>KeyEvent</code>s that map to focus
traversal operations, and
<code>Component.handleEvent()</code> will no longer be invoked
<code>Component.handleEvent()</code> will no longer be invoked
for such events. Previously, AWT Components saw these events
and had an opportunity to consume them before AWT
initiated focus traversal. Code that requires this
@ -1352,7 +1351,7 @@ and VetoableChangeListener</a>.
itself. Alternately, the code can use an
<code>AWTEventListener</code> or
<code>KeyEventDispatcher</code> to pre-listen to all
<code>KeyEvent</code>s.
<code>KeyEvent</code>s.
</ol>
<p><b>Changes specific to Microsoft Windows:</b>
<ol>

58
src/java.desktop/share/classes/java/awt/doc-files/Modality.html
View file

@ -1,5 +1,11 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>The AWT Modality</title>
</head>
<!--
Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
@ -23,19 +29,9 @@
questions.
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<body>
<html>
<head>
<title>The AWT Modality</title>
</head>
<body bgcolor="white">
<h1 align="center">The AWT Modality</h1>
<h1>The AWT Modality</h1>
<p>
This document, together with the API documentation for modality-related
@ -53,7 +49,7 @@
<li><a href="#Examples">Examples</a></li>
</ul>
<a name="Definitions"></a>
<a id="Definitions"></a>
<h3>Definitions</h3>
<p>
@ -63,7 +59,7 @@
Every window belongs to some document &mdash; its root can be found as
the closest ancestor window without an owner.
</p><p>
<a name="ModalBlocked"></a>
<a id="ModalBlocked"></a>
<u>Modal blocked window</u> - a window, that:
</p><ul>
<li>doesn't receive any user input events
@ -73,7 +69,7 @@
<blockquote>
<hr>
<b>Warning!</b> Some window managers allow users to change the window
Z-order in an arbitrary way &mdash; in that case the last requirement
Z-order in an arbitrary way &mdash; in that case the last requirement
may not be met.
<hr>
</blockquote>
@ -87,7 +83,7 @@
then all its owned windows and child components are also excluded.
</p><p>
<u>Scope of blocking (SB)</u> - the set of windows (instances of
<code>java.awt.Window</code> and all derived classes) that are blocked by
<code>java.awt.Window</code> and all derived classes) that are blocked by
the modal dialog while it is visible.
<blockquote><hr>
<b>Note</b>: Everywhere in this document the notion of "window" is equal
@ -95,7 +91,7 @@
an instance of <code>java.awt.Window</code> or any descendant class.
<hr></blockquote>
<a name="ModalityTypes"></a>
<a id="ModalityTypes"></a>
<h3>Modality types</h3>
<p>
@ -159,7 +155,7 @@
dialog may have no effect until it is hidden and then shown again.
<hr></blockquote>
<a name="ShowHideBlocking"></a>
<a id="ShowHideBlocking"></a>
<h3>Show/hide blocking</h3>
<p>
@ -171,7 +167,7 @@
</p><p>
<u>Showing the modal dialog: "M"</u><br>
When modal dialog M is shown, all the visible windows fall into one of
three distinct groups:
three distinct groups:
<ul>
<li>Blockers of M (modal dialogs that block M and
either are in M's child hierarchy, or are not blocked by M, or have
@ -260,11 +256,11 @@
If M was blocked by any other modal dialog, for example, "N",
it becomes unblocked and
is removed from N's blocked windows list. Then, all the windows and dialogs
blocked by M become unblocked, and after that the same checks
blocked by M become unblocked, and after that the same checks
(as in Showing the modal dialog: "M")
are performed for each of them in the order they were initially shown.
<a name="ModalExclusion"></a>
<a id="ModalExclusion"></a>
</p><h3>Modal exclusion</h3>
<p>
@ -290,7 +286,7 @@
may have no effect until it is hidden and then shown again.
</blockquote>
<a name="Related"></a>
<a id="Related"></a>
<h3>Related AWT features</h3>
<p>
@ -333,21 +329,21 @@
</li></ol>
If the modal dialog to be hidden does not have focus, the active window remains
unchanged.
<a name="Security"></a>
<a id="Security"></a>
<h3>Security</h3>
<p>
A special <code>AWTPermission</code>, <code>"toolkitModality"</code>,
is required to show toolkit-modal
dialogs. This would prevent, for example, blocking a browser or
dialogs. This would prevent, for example, blocking a browser or
Java Web Start (JWS) by modal dialogs shown from applets.
</p><p>
The same permission is required to exclude a window from toolkit modality.
This would prevent, for example, a dialog shown from an applet not to be
blocked by a browser's or JWS's modal dialog.
<a name="PlatformSupport"></a>
<a id="PlatformSupport"></a>
</p><h3>Platform support</h3>
<p>
@ -366,18 +362,18 @@
and a window is marked as E-excluded, this has no effect.
</li></ul>
<a name="Compatibility"></a>
<a id="Compatibility"></a>
<h3>Compatibility</h3>
<p>
The default modality type is application-modal. It is used by the API
calls: <code>Dialog.setModal(true)</code>,
calls: <code>Dialog.setModal(true)</code>,
<code>Dialog(owner, true)</code>, etc. Prior to JDK 6
the default type was toolkit-modal,
but the only distinction between application- and toolkit-modality is for
applets and applications launched from Java Web Start.
<a name="Examples"></a>
<a id="Examples"></a>
</p><h3>Examples</h3>
<table border="0">
@ -429,7 +425,7 @@
it's in the same application<br>
<li>D<sub>i</sub> is shown<br>
<li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> &mdash; it's its owner<br>
<li>D<sub>iii</sub> remains unblocked &mdash; it blocks D<sub>ii</sub> and
<li>D<sub>iii</sub> remains unblocked &mdash; it blocks D<sub>ii</sub> and
D<sub>ii</sub> blocks D<sub>i</sub><br>
</ol>
<br>