--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/awt/doc-files/Modality.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,472 @@
+<!--
+ Copyright 2005-2006 Sun Microsystems, Inc. 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. Sun designates this
+ particular file as subject to the "Classpath" exception as provided
+ by Sun in the LICENSE file that accompanied this code.
+
+ This code is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ version 2 for more details (a copy is included in the LICENSE file that
+ accompanied this code).
+
+ You should have received a copy of the GNU General Public License version
+ 2 along with this work; if not, write to the Free Software Foundation,
+ Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+ Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ CA 95054 USA or visit www.sun.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:
+ </p><ul>
+ <li><a href="#Definitions">Definitions</a></li>
+ </li><li><a href="#ModalityTypes">Modality types</a></li>
+ <li><a href="#ShowHideBlocking">Show/hide blocking</a></li>
+ <li><a href="#ModalExclusion">Modal exclusion</a></li>
+ <li><a href="#Related">Related AWT features</a></li>
+ <li><a href="#Security">Security</a></li>
+ <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>
+ </p><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
+ </li></ul>
+ <blockquote>
+ <hr>
+ <b>Warning!</b> Some window managers allow users to change the window
+ Z-order in an arbitrary way — in that case the last requirement
+ may not be met.
+ <hr>
+ </blockquote>
+ <p>
+ <u>Modal dialog</u> - a dialog that blocks some windows while it is
+ visible. The blocked windows are determined according to the dialog's
+ scope of blocking.
+ </p><p>
+ <u>Modal excluded window</u> - a window that stays unblocked
+ while the modal dialog is visible. If a window is modal excluded
+ 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
+ the modal dialog while it is visible.
+ </p><p>
+ <blockquote><hr>
+ <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>
+ </p><h3>Modality types</h3>
+
+ <p>
+ There are four supported modality types :
+ </p><ul>
+ <li>toolkit
+ </li><li>application
+ </li><li>document
+ </li><li>modeless
+ </li></ul>
+ A dialog is, by default, modeless. A modal dialog is, by default,
+ application-modal.
+ <p>
+ </p><ol>
+ <li><u>Modeless dialogs</u><br>
+ A modeless dialog doesn't block any windows while visible.
+ </li><li><u>Document-modal dialogs</u><br>
+ A document-modal dialog blocks all windows from the same
+ document except those from its child hierarchy. The document root
+ is determined as the closest ancestor window without an
+ owner.
+ </li><li><u>Application-modal dialogs</u><br>
+ An application-modal dialog blocks all windows from the same
+ application except for those from its child hierarchy.
+ If there are several applets launched in a browser, they can be
+ treated either as separate applications or a single application.
+ This behavior is implementation-dependent.
+ </li><li><u>Toolkit-modal dialogs</u><br>
+ A toolkit-modal dialog blocks all windows that run in the same
+ toolkit except those from its child hierarchy. If there
+ are several applets launched all of them run with the same toolkit,
+ so a toolkit-modal dialog shown from an applet may affect other
+ applets and all windows of the browser instance which embeds the
+ Java runtime environment for this toolkit.
+ See the security section below.
+ </li></ol>
+ <p>
+ Modality priority is arranged by the strength of blocking: modeless,
+ document-modal, application-modal and toolkit-modal. This arrangement
+ is used when determining what dialog should remain unblocked if two
+ are visible and block each other. It naturally reflects the nesting
+ of a dialog's scope of blocking (SB): a modeless dialog has an empty SB,
+ a document-modal dialog's SB is complete in some applications,
+ and all the applications are run in one toolkit. </p><p>
+ Notes about owners:
+ </p><ul>
+ <li>Creating a document-modal dialog without an owner:<br>
+ Since <code>Dialog</code> is a class derived from
+ <code>Window</code>, a <code>Dialog</code> instance automatically
+ becomes the root of the document if it has no owner. Thus, if
+ such a dialog is document-modal, its scope of blocking is empty
+ and it behaves the same way as a modeless dialog.
+ </li><li>Creating an application-modal or toolkit-modal dialog with an
+ owner:<br>
+ The scope of blocking for an application- or toolkit-modal
+ dialog, as opposed to a document-modal dialog, doesn't depend on
+ its owner. Thus, in this case the only thing that the owner
+ affects is the Z-order: the dialog always stays on top of its owner.
+ </li></ul>
+ <p>
+ <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>
+ </p><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
+ of one of them, it becomes blocked by it. If there are several such
+ dialogs, the first shown is used. If no such dialogs exist, F remains
+ unblocked.
+ </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:
+ <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
+ a greater mode of modality, or block some other blocker of M)
+ <li>Blocked by M (windows from M's SB that are not blockers and are
+ not in child hierarchy of any blocker)
+ <li>All other windows (windows or modeless
+ dialogs outside M's SB and modal dialogs outside M's SB that do not
+ block M).
+ </ul>
+ </p><p>
+ After the modal dialog M is shown, it becomes blocked by the first shown
+ dialog from the first group (if there are any), all the windows from the
+ second one become blocked by M, and all the windows from the third group
+ remain untouched.
+ </p><p>
+ <u>In typical cases</u>, when no child dialogs are shown before their owners,
+ this rule can be simplified. (The following, simplified case, may
+ leave out some details).
+ </p><p>
+ <u>Showing the document-modal dialog: "M"</u><br>
+ All the visible application- and toolkit-modal dialogs are looked
+ through — if M is from the SB of one of them,
+ it becomes blocked by it. If there are several such dialogs,
+ the first shown is used. If no such dialogs exist, M remains unblocked.
+ </p><p>
+ <u>Showing the application-modal dialog: "M"</u><br>
+ All the visible toolkit-modal dialogs are looked through —
+ if M is from the SB of one of them, it becomes blocked by it.
+ If there are several such dialogs, the first shown is used.
+ If no such dialogs exist, M remains unblocked.
+ </p><p>
+ <u>Showing the toolkit-modal dialog: "M"</u><br>
+ M remains unblocked.
+ </p><p>
+<!-- <center> -->
+ </p>
+ <table border="1" cols="5" rows="5">
+ <caption>The Standard Blocking Matrix</caption>
+ <tbody><tr align="center">
+ <td align="center">current/shown</td>
+ <td align="center">frame & modeless</td>
+ <td align="center">document</td>
+ <td align="center">application</td>
+ <td align="center">toolkit</td>
+ </tr>
+ <tr align="center">
+ <td align="center">-</td>
+ <td align="center">-</td>
+ <td align="center">-</td>
+ <td align="center">-</td>
+ <td align="center">-</td>
+ </tr>
+ <tr align="center">
+ <td align="center">document</td>
+ <td align="center">blocked</td>
+ <td align="center">-</td>
+ <td align="center">-</td>
+ <td align="center">-</td>
+ </tr>
+ <tr align="center">
+ <td align="center">application</td>
+ <td align="center">blocked</td>
+ <td align="center">blocked</td>
+ <td align="center">-</td>
+ <td align="center">-</td>
+ </tr>
+ <tr align="center">
+ <td align="center">toolkit</td>
+ <td align="center">blocked</td>
+ <td align="center">blocked</td>
+ <td align="center">blocked</td>
+ <td align="center">-</td>
+ </tr>
+ </tbody></table>
+<!-- </center> -->
+ <p>
+ After the modal dialog is shown, all the windows from its SB are blocked,
+ except those that block this modal dialog.
+ </p><p>
+ <u>Hiding the window or modeless dialog: "F"</u><br>
+ If F was blocked by any modal dialog M, it becomes unblocked and is
+ removed from M's blocked windows list.
+ </p><p>
+ <u>Hiding the modal dialog: "M"</u><br>
+ 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
+ (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>
+ <li>Exclusion from blocking of toolkit-modal dialogs
+ </li><li>Exclusion from blocking of application-modal dialogs
+ </li></ul>
+ By default, a window's modal exclusion property is turned off.
+ <p>
+ </p><ol>
+ <li><u>Application-modal exclusion</u><br>
+ If a window is application-modal excluded, it is not blocked by any
+ application-modal dialogs. Also, it is not blocked by document-modal
+ dialogs from outside of its child hierarchy.
+ </li><li><u>Toolkit-modal exclusion</u><br>
+ If a window is toolkit-modal excluded, it is not blocked
+ by any application- or toolkit-modal dialogs. Also, it is not
+ blocked by document-modal dialogs from outside of their child hierarchy.
+ </li></ol>
+ <p>
+ <blockquote>
+ <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.
+ </hr>
+ </blockquote>
+
+ <a name="Related"</a>
+ </p><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,
+ their relative Z-order is unspecified and platform-dependent.
+ </p>
+ <p>
+ <u>The <code>toFront()</code> and <code>toBack()</code> methods</u><br>
+ A modal dialog should always be above all its blocked windows. Thus, if a blocked
+ window is brought to the front, its blocking dialog, if any, is also brought to the
+ front and remains above the blocked window. Likewise, if a modal dialog is sent to
+ the back, all of its blocked windows are sent to the back to keep them below the
+ blocking dialog.
+ </p>
+ <p>
+ <u>Minimizing, maximizing and closing blocked windows</u><br>
+ When a modal dialog blocks a window, the user may not be able to maximize or
+ minimize the blocked window— however, the actual behavior is unspecified
+ and platform-dependent. In any case, the user can't close the blocked window
+ interactively— but it can be closed programmatically by calling the
+ <code>setVisible(false)</code> or <code>dispose()</code> methods on the blocked
+ window.
+ </p>
+ <p>
+ <u>Blocked windows activations</u><br>
+ When the user selects a blocked window, it may be brought to the front, along
+ with the blocking modal dialog which would then become the active window—
+ however, the actual behavior is unspecified and platform-dependent.
+ </p>
+ <p>
+ <u>Hiding a modal dialog</u><br>
+ When the modal dialog that currently has focus is hidden, it is unspecified
+ and platform-dependent, which other window will become the active window.
+ Any of the following may become the active window:
+ <ol>
+ <li>The owner of the modal dialog - if the owner is unblocked.
+ </li><li>The <code>Window</code>, which was active before this modal dialog gained
+ 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.
+ </p>
+ <a name="Security"></a>
+ </p><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
+ 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>
+ </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:
+ </p><ul>
+ <li><code>isModalityTypeSupported(modalityType)</code><br>
+ Returns whether the specified modality type is supported on
+ the current platform.
+ If mode "M" is not supported and a dialog is set to M-modal,
+ it behaves as modeless.
+ </li>
+ <li><code>isModalExclusionTypeSupported(modalExclusionType)</code><br>
+ 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 cols="2" border="0">
+ <tbody><tr>
+ <td align="left" valign="center">
+ <ol>
+ <li>Frame "F" is shown<br>
+ <li>Document-modal dialog "D<sub>i</sub>" is shown<br>
+ <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br>
+ <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
+ <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — it's in the
+ same document<br>
+ </ol>
+ <br>
+ </td>
+ <td align="center" valign="center">
+ <img src="modal-example1.gif">
+ <br>
+ </td>
+ </tr>
+ <tr>
+ <td align="left" valign="center">
+ <ol>
+ <li>Frame "F" is shown<br>
+ <li>Document-modal dialog "D<sub>i</sub>" is shown<br>
+ <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br>
+ <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
+ <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> —
+ it's in the same document<br>
+ <li>D<sub>i</sub> is hidden<br>
+ <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br>
+ </ol>
+ <br>
+ </td>
+ <td align="center">
+ <img src="modal-example2.gif">
+ <br>
+ </td>
+ </tr>
+ <tr>
+ <td align="left" valign="center">
+ <ol>
+ <li>Frame "F" is shown<br>
+ <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br>
+ <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
+ <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br>
+ <li>Application-modal dialog "D<sub>iii</sub>" is shown<br>
+ <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> —
+ 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> — it's its owner<br>
+ <li>D<sub>iii</sub> remains unblocked — it blocks D<sub>ii</sub> and
+ D<sub>ii</sub> blocks D<sub>i</sub><br>
+ </ol>
+ <br>
+ </td>
+ <td align="center" valign="center">
+ <img src="modal-example3.gif">
+ <br>
+ </td>
+ </tr>
+ <tr>
+ <td align="left" valign="center">
+ <ol>
+ <li>Frame "F" is shown<br>
+ <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br>
+ <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
+ <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br>
+ <li>Application-modal dialog "D<sub>iii</sub>" is shown<br>
+ <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> — it's in the
+ same application<br>
+ <li>D<sub>i</sub> is shown<br>
+ <li>D<sub>iii</sub> becomes blocked by D<sub>i</sub> — D<sub>i</sub>
+ is not blocked<br>
+ <li>D<sub>i</sub> remains unblocked<br>
+ </ol>
+ <br>
+ </td>
+ <td align="center" valign="center">
+ <img src="modal-example4.gif">
+ <br>
+ </td>
+ </tr>
+ </tbody></table>
+
+</body></html>