2362N/A Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A This code is free software; you can redistribute it and/or modify it 0N/A under the terms of the GNU General Public License version 2 only, as 2362N/A published by the Free Software Foundation. Oracle designates this 0N/A particular file as subject to the "Classpath" exception as provided 2362N/A by Oracle in the LICENSE file that accompanied this code. 0N/A This code is distributed in the hope that it will be useful, but WITHOUT 0N/A ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A version 2 for more details (a copy is included in the LICENSE file that 0N/A accompanied this code). 0N/A You should have received a copy of the GNU General Public License version 0N/A 2 along with this work; if not, write to the Free Software Foundation, 0N/A Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A <
title>The AWT Modality</
title>
0N/A<
body bgcolor="white">
0N/A <
h1 align="center">The AWT Modality</
h1>
0N/A This document, together with the API documentation for modality-related
0N/A modality features and how to use them. It contains the following sections:
0N/A <
li><
a href="#Definitions">Definitions</
a></
li>
0N/A </
li><
li><
a href="#ModalityTypes">Modality types</
a></
li>
0N/A <
li><
a href="#ShowHideBlocking">
Show/
hide blocking</
a></
li>
0N/A <
li><
a href="#ModalExclusion">Modal exclusion</
a></
li>
0N/A <
li><
a href="#Related">Related AWT features</
a></
li>
0N/A <
li><
a href="#Security">Security</
a></
li>
0N/A <
li><
a href="#PlatformSupport">Platform support</
a></
li>
0N/A <
li><
a href="#Compatibility">Compatibility</
a></
li>
0N/A <
li><
a href="#Examples">Examples</
a></
li>
0N/A <
a name="Definitions"></
a>
0N/A </
p><
h3>Definitions</
h3>
0N/A <
u>Document</
u> - a window without an owner that, together with
0N/A all its child hierarchy, may be operated on as a single self-contained
0N/A Every window belongs to some document — its root can be found as
0N/A the closest ancestor window without an owner.
0N/A <
a name="ModalBlocked"></
a>
0N/A <
u>Modal blocked window</
u> - a window, that:
0N/A <
li>doesn't receive any user input events
0N/A </
li><
li>doesn't receive input focus
0N/A </
li><
li>keeps its Z-order below the modal dialog that blocks it
0N/A <
b>Warning!</
b> Some window managers allow users to change the window
0N/A Z-order in an arbitrary way — in that case the last requirement
0N/A <
u>Modal dialog</
u> - a dialog that blocks some windows while it is
0N/A visible. The blocked windows are determined according to the dialog's
0N/A <
u>Modal excluded window</
u> - a window that stays unblocked
0N/A while the modal dialog is visible. If a window is modal excluded
0N/A then all its owned windows and child components are also excluded.
0N/A <
u>Scope of blocking (SB)</
u> - the set of windows (instances of
0N/A the modal dialog while it is visible.
0N/A <
b>Note</
b>: Everywhere in this document the notion of "window" is equal
0N/A to a top-level window in the Java programming language — in other words
0N/A <
a name="ModalityTypes"></
a>
0N/A </
p><
h3>Modality types</
h3>
0N/A There are four supported modality types :
0N/A </
li><
li>application
0N/A A dialog is, by default, modeless. A modal dialog is, by default,
0N/A <
li><
u>Modeless dialogs</
u><
br>
0N/A A modeless dialog doesn't block any windows while visible.
0N/A </
li><
li><
u>Document-modal dialogs</
u><
br>
0N/A A document-modal dialog blocks all windows from the same
0N/A document except those from its child hierarchy. The document root
0N/A is determined as the closest ancestor window without an
0N/A </
li><
li><
u>Application-modal dialogs</
u><
br>
0N/A An application-modal dialog blocks all windows from the same
0N/A application except for those from its child hierarchy.
0N/A If there are several applets launched in a browser, they can be
0N/A treated either as separate applications or a single application.
0N/A This behavior is implementation-dependent.
0N/A </
li><
li><
u>Toolkit-modal dialogs</
u><
br>
0N/A A toolkit-modal dialog blocks all windows that run in the same
0N/A toolkit except those from its child hierarchy. If there
0N/A are several applets launched all of them run with the same toolkit,
0N/A so a toolkit-modal dialog shown from an applet may affect other
0N/A applets and all windows of the browser instance which embeds the
0N/A Java runtime environment for this toolkit.
0N/A See the security section below.
0N/A Modality priority is arranged by the strength of blocking: modeless,
0N/A document-modal, application-modal and toolkit-modal. This arrangement
0N/A is used when determining what dialog should remain unblocked if two
0N/A are visible and block each other. It naturally reflects the nesting
0N/A of a dialog's scope of blocking (SB): a modeless dialog has an empty SB,
0N/A a document-modal dialog's SB is complete in some applications,
0N/A and all the applications are run in one toolkit. </
p><
p>
0N/A <
li>Creating a document-modal dialog without an owner:<
br>
0N/A Since <
code>Dialog</
code> is a class derived from
0N/A <
code>Window</
code>, a <
code>Dialog</
code> instance automatically
0N/A becomes the root of the document if it has no owner. Thus, if
0N/A such a dialog is document-modal, its scope of blocking is empty
0N/A and it behaves the same way as a modeless dialog.
0N/A </
li><
li>Creating an application-modal or toolkit-modal dialog with an
0N/A The scope of blocking for an application- or toolkit-modal
0N/A dialog, as opposed to a document-modal dialog, doesn't depend on
0N/A its owner. Thus, in this case the only thing that the owner
0N/A affects is the Z-order: the dialog always stays on top of its owner.
0N/A <
b>Implementation note</
b>: Changing the modality type for a visible
0N/A dialog may have no effect until it is hidden and then shown again.
0N/A <
a name="ShowHideBlocking"></
a>
0N/A <
u>Showing the window or modeless dialog: "F"</
u><
br>
0N/A All the visible modal dialogs are looked through — if F is from the SB
0N/A of one of them, it becomes blocked by it. If there are several such
0N/A dialogs, the first shown is used. If no such dialogs exist, F remains
0N/A <
u>Showing the modal dialog: "M"</
u><
br>
0N/A When modal dialog M is shown, all the visible windows fall into one of
0N/A three distinct groups:
0N/A <
li>Blockers of M (modal dialogs that block M and
0N/A either are in M's child hierarchy, or are not blocked by M, or have
0N/A a greater mode of modality, or block some other blocker of M)
0N/A <
li>Blocked by M (windows from M's SB that are not blockers and are
0N/A not in child hierarchy of any blocker)
0N/A <
li>All other windows (windows or modeless
0N/A dialogs outside M's SB and modal dialogs outside M's SB that do not
0N/A After the modal dialog M is shown, it becomes blocked by the first shown
0N/A dialog from the first group (if there are any), all the windows from the
0N/A second one become blocked by M, and all the windows from the third group
0N/A <
u>In typical cases</
u>, when no child dialogs are shown before their owners,
0N/A this rule can be simplified. (The following, simplified case, may
0N/A leave out some details).
0N/A <
u>Showing the document-modal dialog: "M"</
u><
br>
0N/A All the visible application- and toolkit-modal dialogs are looked
0N/A through — if M is from the SB of one of them,
0N/A it becomes blocked by it. If there are several such dialogs,
0N/A the first shown is used. If no such dialogs exist, M remains unblocked.
0N/A <
u>Showing the application-modal dialog: "M"</
u><
br>
0N/A All the visible toolkit-modal dialogs are looked through —
0N/A if M is from the SB of one of them, it becomes blocked by it.
0N/A If there are several such dialogs, the first shown is used.
0N/A If no such dialogs exist, M remains unblocked.
0N/A <
u>Showing the toolkit-modal dialog: "M"</
u><
br>
0N/A M remains unblocked.
0N/A <
table border="1" cols="5" rows="5">
0N/A <
caption>The Standard Blocking Matrix</
caption>
0N/A <
tbody><
tr align="center">
0N/A <
td align="center">frame & modeless</
td>
0N/A <
td align="center">document</
td>
0N/A <
td align="center">application</
td>
0N/A <
td align="center">toolkit</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">document</
td>
0N/A <
td align="center">blocked</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">application</
td>
0N/A <
td align="center">blocked</
td>
0N/A <
td align="center">blocked</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">-</
td>
0N/A <
td align="center">toolkit</
td>
0N/A <
td align="center">blocked</
td>
0N/A <
td align="center">blocked</
td>
0N/A <
td align="center">blocked</
td>
0N/A <
td align="center">-</
td>
0N/A After the modal dialog is shown, all the windows from its SB are blocked,
0N/A except those that block this modal dialog.
0N/A <
u>Hiding the window or modeless dialog: "F"</
u><
br>
0N/A If F was blocked by any modal dialog M, it becomes unblocked and is
0N/A removed from M's blocked windows list.
0N/A <
u>Hiding the modal dialog: "M"</
u><
br>
0N/A If M was blocked by any other modal dialog, for example, "N",
0N/A it becomes unblocked and
0N/A is removed from N's blocked windows list. Then, all the windows and dialogs
0N/A blocked by M become unblocked, and after that the same checks
0N/A (as in Showing the modal dialog: "M")
0N/A are performed for each of them in the order they were initially shown.
0N/A <
a name="ModalExclusion"></
a>
0N/A </
p><
h3>Modal exclusion</
h3>
0N/A There are two modal exclusion types introduced as of JDK 6
0N/A <
li>Exclusion from blocking of toolkit-modal dialogs
0N/A </
li><
li>Exclusion from blocking of application-modal dialogs
0N/A By default, a window's modal exclusion property is turned off.
0N/A <
li><
u>Application-modal exclusion</
u><
br>
0N/A If a window is application-modal excluded, it is not blocked by any
0N/A application-modal dialogs. Also, it is not blocked by document-modal
0N/A dialogs from outside of its child hierarchy.
0N/A </
li><
li><
u>Toolkit-modal exclusion</
u><
br>
0N/A If a window is toolkit-modal excluded, it is not blocked
0N/A by any application- or toolkit-modal dialogs. Also, it is not
0N/A blocked by document-modal dialogs from outside of their child hierarchy.
0N/A <
b>Implementation note</
b>: Changing the modal exclusion type for a visible window
0N/A may have no effect until it is hidden and then shown again.
0N/A <
a name="Related"</a>
0N/A </
p><
h3>Related AWT features</
h3>
0N/A <
u>Always-On-Top</
u><
br>
0N/A When a modal dialog that is not always-on-top blocks an always-on-top window,
0N/A their relative Z-order is unspecified and platform-dependent.
0N/A <
u>The <
code>toFront()</
code> and <
code>toBack()</
code> methods</
u><
br>
0N/A A modal dialog should always be above all its blocked windows. Thus, if a blocked
0N/A window is brought to the front, its blocking dialog, if any, is also brought to the
0N/A front and remains above the blocked window. Likewise, if a modal dialog is sent to
0N/A the back, all of its blocked windows are sent to the back to keep them below the
0N/A <
u>Minimizing, maximizing and closing blocked windows</
u><
br>
0N/A When a modal dialog blocks a window, the user may not be able to maximize or
0N/A minimize the blocked window— however, the actual behavior is unspecified
0N/A and platform-dependent. In any case, the user can't close the blocked window
0N/A interactively— but it can be closed programmatically by calling the
0N/A <
code>setVisible(false)</
code> or <
code>dispose()</
code> methods on the blocked
0N/A <
u>Blocked windows activations</
u><
br>
0N/A When the user selects a blocked window, it may be brought to the front, along
0N/A with the blocking modal dialog which would then become the active window—
0N/A however, the actual behavior is unspecified and platform-dependent.
0N/A <
u>Hiding a modal dialog</
u><
br>
0N/A When the modal dialog that currently has focus is hidden, it is unspecified
0N/A and platform-dependent, which other window will become the active window.
0N/A Any of the following may become the active window:
0N/A <
li>The owner of the modal dialog - if the owner is unblocked.
0N/A </
li><
li>The <
code>Window</
code>, which was active before this modal dialog gained
0N/A focus - if the owner of the modal dialog is absent or is blocked.
0N/A If the modal dialog to be hidden does not have focus, the active window remains
0N/A <
a name="Security"></
a>
0N/A </
p><
h3>Security</
h3>
0N/A A special <
code>AWTPermission</
code>, <
code>"toolkitModality"</
code>,
0N/A is required to show toolkit-modal
0N/A dialogs. This would prevent, for example, blocking a browser or
0N/A Java Web Start (JWS) by modal dialogs shown from applets.
0N/A The same permission is required to exclude a window from toolkit modality.
0N/A This would prevent, for example, a dialog shown from an applet not to be
0N/A blocked by a browser's or JWS's modal dialog.
0N/A <
a name="PlatformSupport"></
a>
0N/A </
p><
h3>Platform support</
h3>
0N/A the current platform supports specific modality features:
0N/A <
li><
code>isModalityTypeSupported(modalityType)</
code><
br>
0N/A Returns whether the specified modality type is supported on
0N/A the current platform.
0N/A If mode "M" is not supported and a dialog is set to M-modal,
0N/A it behaves as modeless.
0N/A <
li><
code>isModalExclusionTypeSupported(modalExclusionType)</
code><
br>
0N/A Returns whether the given modal exclusion type is supported on
0N/A the current platform. If exclusion type "E" is not supported
0N/A and a window is marked as E-excluded, this has no effect.
0N/A <
a name="Compatibility"></
a>
0N/A <
h3>Compatibility</
h3>
0N/A The default modality type is application-modal. It is used by the API
0N/A <
code>Dialog(owner, true)</
code>, etc. Prior to JDK 6
0N/A the default type was toolkit-modal,
0N/A but the only distinction between application- and toolkit-modality is for
0N/A applets and applications launched from Java Web Start.
0N/A <
a name="Examples"></
a>
0N/A </
p><
h3>Examples</
h3>
0N/A <
table cols="2" border="0">
0N/A <
td align="left" valign="center">
0N/A <
li>Frame "F" is shown<
br>
0N/A <
li>Document-modal dialog "D<
sub>i</
sub>" is shown<
br>
0N/A <
li>F becomes blocked by D<
sub>i</
sub> — it's in the same document<
br>
0N/A <
li>Document-modal dialog "D<
sub>ii</
sub>" is shown<
br>
0N/A <
li>D<
sub>i</
sub> becomes blocked by D<
sub>ii</
sub> — it's in the
0N/A <
td align="center" valign="center">
0N/A <
td align="left" valign="center">
0N/A <
li>Frame "F" is shown<
br>
0N/A <
li>Document-modal dialog "D<
sub>i</
sub>" is shown<
br>
0N/A <
li>F becomes blocked by D<
sub>i</
sub> — it's in the same document<
br>
0N/A <
li>Document-modal dialog "D<
sub>ii</
sub>" is shown<
br>
0N/A <
li>D<
sub>i</
sub> becomes blocked by D<
sub>ii</
sub> —
0N/A it's in the same document<
br>
0N/A <
li>D<
sub>i</
sub> is hidden<
br>
0N/A <
li>F becomes blocked by D<
sub>ii</
sub> — it's in the same document<
br>
0N/A <
td align="left" valign="center">
0N/A <
li>Frame "F" is shown<
br>
0N/A <
li>Toolkit-modal dialog "D<
sub>i</
sub>" is created, but not shown<
br>
0N/A <
li>Document-modal dialog "D<
sub>ii</
sub>" is shown<
br>
0N/A <
li>F becomes blocked by D<
sub>ii</
sub> — it's in the same document<
br>
0N/A <
li>Application-modal dialog "D<
sub>iii</
sub>" is shown<
br>
0N/A <
li>D<
sub>ii</
sub> becomes blocked by D<
sub>iii</
sub> —
0N/A it's in the same application<
br>
0N/A <
li>D<
sub>i</
sub> is shown<
br>
0N/A <
li>D<
sub>i</
sub> becomes blocked by D<
sub>ii</
sub> — it's its owner<
br>
0N/A <
li>D<
sub>iii</
sub> remains unblocked — it blocks D<
sub>ii</
sub> and
0N/A D<
sub>ii</
sub> blocks D<
sub>i</
sub><
br>
0N/A <
td align="center" valign="center">
0N/A <
td align="left" valign="center">
0N/A <
li>Frame "F" is shown<
br>
0N/A <
li>Toolkit-modal dialog "D<
sub>i</
sub>" is created, but not shown<
br>
0N/A <
li>Document-modal dialog "D<
sub>ii</
sub>" is shown<
br>
0N/A <
li>F becomes blocked by D<
sub>ii</
sub> — it's in the same document<
br>
0N/A <
li>Application-modal dialog "D<
sub>iii</
sub>" is shown<
br>
0N/A <
li>D<
sub>ii</
sub> becomes blocked by D<
sub>iii</
sub> — it's in the
0N/A same application<
br>
0N/A <
li>D<
sub>i</
sub> is shown<
br>
0N/A <
li>D<
sub>iii</
sub> becomes blocked by D<
sub>i</
sub> — D<
sub>i</
sub>
0N/A <
li>D<
sub>i</
sub> remains unblocked<
br>
0N/A <
td align="center" valign="center">
