< prev index next >
src/java.desktop/share/classes/java/awt/doc-files/Modality.html
Print this page
*** 1,7 ****
<!--
! Copyright (c) 2005, 2015, 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
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
--- 1,13 ----
+ <!doctype html>
+ <html lang="en">
+ <head>
+ <meta charset="utf-8"/>
+ <title>The AWT Modality</title>
+ </head>
<!--
! 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
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
*** 21,43 ****
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
!
! <html>
!
! <head>
!
! <title>The AWT Modality</title>
!
! </head>
!
! <body bgcolor="white">
! <h1 align="center">The AWT Modality</h1>
<p>
This document, together with the API documentation for modality-related
classes (such as <code>java.awt.Dialog</code>), briefly describes the new
modality features and how to use them. It contains the following sections:
--- 27,39 ----
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
! <body>
! <h1>The AWT Modality</h1>
<p>
This document, together with the API documentation for modality-related
classes (such as <code>java.awt.Dialog</code>), briefly describes the new
modality features and how to use them. It contains the following sections:
*** 51,71 ****
<li><a href="#PlatformSupport">Platform support</a></li>
<li><a href="#Compatibility">Compatibility</a></li>
<li><a href="#Examples">Examples</a></li>
</ul>
! <a name="Definitions"></a>
<h3>Definitions</h3>
<p>
<u>Document</u> - a window without an owner that, together with
all its child hierarchy, may be operated on as a single self-contained
document.
Every window belongs to some document — its root can be found as
the closest ancestor window without an owner.
</p><p>
! <a name="ModalBlocked"></a>
<u>Modal blocked window</u> - a window, that:
</p><ul>
<li>doesn't receive any user input events
</li><li>doesn't receive input focus
</li><li>keeps its Z-order below the modal dialog that blocks it
--- 47,67 ----
<li><a href="#PlatformSupport">Platform support</a></li>
<li><a href="#Compatibility">Compatibility</a></li>
<li><a href="#Examples">Examples</a></li>
</ul>
! <a id="Definitions"></a>
<h3>Definitions</h3>
<p>
<u>Document</u> - a window without an owner that, together with
all its child hierarchy, may be operated on as a single self-contained
document.
Every window belongs to some document — its root can be found as
the closest ancestor window without an owner.
</p><p>
! <a id="ModalBlocked"></a>
<u>Modal blocked window</u> - a window, that:
</p><ul>
<li>doesn't receive any user input events
</li><li>doesn't receive input focus
</li><li>keeps its Z-order below the modal dialog that blocks it
*** 93,103 ****
<b>Note</b>: Everywhere in this document the notion of "window" is equal
to a top-level window in the Java programming language — in other words
an instance of <code>java.awt.Window</code> or any descendant class.
<hr></blockquote>
! <a name="ModalityTypes"></a>
<h3>Modality types</h3>
<p>
There are four supported modality types :
</p><ul>
--- 89,99 ----
<b>Note</b>: Everywhere in this document the notion of "window" is equal
to a top-level window in the Java programming language — in other words
an instance of <code>java.awt.Window</code> or any descendant class.
<hr></blockquote>
! <a id="ModalityTypes"></a>
<h3>Modality types</h3>
<p>
There are four supported modality types :
</p><ul>
*** 157,167 ****
<blockquote><hr>
<b>Implementation note</b>: Changing the modality type for a visible
dialog may have no effect until it is hidden and then shown again.
<hr></blockquote>
! <a name="ShowHideBlocking"></a>
<h3>Show/hide blocking</h3>
<p>
<u>Showing the window or modeless dialog: "F"</u><br>
All the visible modal dialogs are looked through — if F is from the SB
--- 153,163 ----
<blockquote><hr>
<b>Implementation note</b>: Changing the modality type for a visible
dialog may have no effect until it is hidden and then shown again.
<hr></blockquote>
! <a id="ShowHideBlocking"></a>
<h3>Show/hide blocking</h3>
<p>
<u>Showing the window or modeless dialog: "F"</u><br>
All the visible modal dialogs are looked through — if F is from the SB
*** 262,272 ****
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
(as in Showing the modal dialog: "M")
are performed for each of them in the order they were initially shown.
! <a name="ModalExclusion"></a>
</p><h3>Modal exclusion</h3>
<p>
There are two modal exclusion types introduced as of JDK 6
</p><ul>
--- 258,268 ----
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
(as in Showing the modal dialog: "M")
are performed for each of them in the order they were initially shown.
! <a id="ModalExclusion"></a>
</p><h3>Modal exclusion</h3>
<p>
There are two modal exclusion types introduced as of JDK 6
</p><ul>
*** 288,298 ****
<hr>
<b>Implementation note</b>: Changing the modal exclusion type for a visible window
may have no effect until it is hidden and then shown again.
</blockquote>
! <a name="Related"></a>
<h3>Related AWT features</h3>
<p>
<u>Always-On-Top</u><br>
When a modal dialog that is not always-on-top blocks an always-on-top window,
--- 284,294 ----
<hr>
<b>Implementation note</b>: Changing the modal exclusion type for a visible window
may have no effect until it is hidden and then shown again.
</blockquote>
! <a id="Related"></a>
<h3>Related AWT features</h3>
<p>
<u>Always-On-Top</u><br>
When a modal dialog that is not always-on-top blocks an always-on-top window,
*** 332,342 ****
focus - if the owner of the modal dialog is absent or is blocked.
</li></ol>
If the modal dialog to be hidden does not have focus, the active window remains
unchanged.
! <a name="Security"></a>
<h3>Security</h3>
<p>
A special <code>AWTPermission</code>, <code>"toolkitModality"</code>,
is required to show toolkit-modal
--- 328,338 ----
focus - if the owner of the modal dialog is absent or is blocked.
</li></ol>
If the modal dialog to be hidden does not have focus, the active window remains
unchanged.
! <a id="Security"></a>
<h3>Security</h3>
<p>
A special <code>AWTPermission</code>, <code>"toolkitModality"</code>,
is required to show toolkit-modal
*** 345,355 ****
</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>
</p><h3>Platform support</h3>
<p>
Two <code>java.awt.Toolkit</code> methods allow you to check whether
the current platform supports specific modality features:
--- 341,351 ----
</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 id="PlatformSupport"></a>
</p><h3>Platform support</h3>
<p>
Two <code>java.awt.Toolkit</code> methods allow you to check whether
the current platform supports specific modality features:
*** 364,385 ****
Returns whether the given modal exclusion type is supported on
the current platform. If exclusion type "E" is not supported
and a window is marked as E-excluded, this has no effect.
</li></ul>
! <a name="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>,
<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>
</p><h3>Examples</h3>
<table border="0">
<tbody><tr>
<td align="left" >
--- 360,381 ----
Returns whether the given modal exclusion type is supported on
the current platform. If exclusion type "E" is not supported
and a window is marked as E-excluded, this has no effect.
</li></ul>
! <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>,
<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 id="Examples"></a>
</p><h3>Examples</h3>
<table border="0">
<tbody><tr>
<td align="left" >
< prev index next >