| <!-- | |
| Copyright (c) 2005, 2013, 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 | |
| particular file as subject to the "Classpath" exception as provided | |
| by Oracle 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 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: | |
| </p><ul> | |
| <li><a href="#Definitions">Definitions</a></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> | |
| <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> | |
| <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> | |
| <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> | |
| 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"> | |
| <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. | |
| </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, | |
| 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. | |
| <a name="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 | |
| 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 border="0"> | |
| <tbody><tr> | |
| <td align="left" > | |
| <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"> | |
| <img src="modal-example1.gif"> | |
| <br> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left"> | |
| <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"> | |
| <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"> | |
| <img src="modal-example3.gif"> | |
| <br> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left"> | |
| <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"> | |
| <img src="modal-example4.gif"> | |
| <br> | |
| </td> | |
| </tr> | |
| </tbody></table> | |
| </body></html> |