Modality.html revision 0
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<!--
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk This code is free software; you can redistribute it and/or modify it
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk under the terms of the GNU General Public License version 2 only, as
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk published by the Free Software Foundation. Sun designates this
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk particular file as subject to the "Classpath" exception as provided
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk by Sun in the LICENSE file that accompanied this code.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk This code is distributed in the hope that it will be useful, but WITHOUT
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk version 2 for more details (a copy is included in the LICENSE file that
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk accompanied this code).
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk You should have received a copy of the GNU General Public License version
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk 2 along with this work; if not, write to the Free Software Foundation,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk CA 95054 USA or visit www.sun.com if you need additional information or
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk have any questions.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk-->
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<html>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<head>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <title>The AWT Modality</title>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk</head>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<body bgcolor="white">
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <h1 align="center">The AWT Modality</h1>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk This document, together with the API documentation for modality-related
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk classes (such as <code>java.awt.Dialog</code>), briefly describes the new
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk modality features and how to use them. It contains the following sections:
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><a href="#Definitions">Definitions</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li><a href="#ModalityTypes">Modality types</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><a href="#ShowHideBlocking">Show/hide blocking</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><a href="#ModalExclusion">Modal exclusion</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><a href="#Related">Related AWT features</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><a href="#Security">Security</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><a href="#PlatformSupport">Platform support</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><a href="#Compatibility">Compatibility</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><a href="#Examples">Examples</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <a name="Definitions"></a>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><h3>Definitions</h3>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Document</u> - a window without an owner that, together with
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk all its child hierarchy, may be operated on as a single self-contained
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk document.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Every window belongs to some document &#151; its root can be found as
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk the closest ancestor window without an owner.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <a name="ModalBlocked"></a>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Modal blocked window</u> - a window, that:
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li>doesn't receive any user input events
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li>doesn't receive input focus
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li>keeps its Z-order below the modal dialog that blocks it
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li></ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <blockquote>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <hr>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <b>Warning!</b> Some window managers allow users to change the window
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Z-order in an arbitrary way &#151; in that case the last requirement
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk may not be met.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <hr>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </blockquote>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Modal dialog</u> - a dialog that blocks some windows while it is
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk visible. The blocked windows are determined according to the dialog's
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk scope of blocking.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Modal excluded window</u> - a window that stays unblocked
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk while the modal dialog is visible. If a window is modal excluded
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk then all its owned windows and child components are also excluded.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Scope of blocking (SB)</u> - the set of windows (instances of
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <code>java.awt.Window</code> and all derived classes) that are blocked by
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk the modal dialog while it is visible.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <blockquote><hr>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <b>Note</b>: Everywhere in this document the notion of "window" is equal
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk to a top-level window in the Java programming language &#151; in other words
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk an instance of <code>java.awt.Window</code> or any descendant class.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <hr></blockquote>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <a name="ModalityTypes"></a>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><h3>Modality types</h3>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk There are four supported modality types :
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li>toolkit
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li>application
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li>document
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li>modeless
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li></ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk A dialog is, by default, modeless. A modal dialog is, by default,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk application-modal.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><ol>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><u>Modeless dialogs</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk A modeless dialog doesn't block any windows while visible.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li><u>Document-modal dialogs</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk A document-modal dialog blocks all windows from the same
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk document except those from its child hierarchy. The document root
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk is determined as the closest ancestor window without an
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk owner.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li><u>Application-modal dialogs</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk An application-modal dialog blocks all windows from the same
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk application except for those from its child hierarchy.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk If there are several applets launched in a browser, they can be
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk treated either as separate applications or a single application.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk This behavior is implementation-dependent.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li><u>Toolkit-modal dialogs</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk A toolkit-modal dialog blocks all windows that run in the same
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk toolkit except those from its child hierarchy. If there
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk are several applets launched all of them run with the same toolkit,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk so a toolkit-modal dialog shown from an applet may affect other
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk applets and all windows of the browser instance which embeds the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Java runtime environment for this toolkit.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk See the security section below.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li></ol>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Modality priority is arranged by the strength of blocking: modeless,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk document-modal, application-modal and toolkit-modal. This arrangement
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk is used when determining what dialog should remain unblocked if two
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk are visible and block each other. It naturally reflects the nesting
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk of a dialog's scope of blocking (SB): a modeless dialog has an empty SB,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk a document-modal dialog's SB is complete in some applications,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk and all the applications are run in one toolkit. </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Notes about owners:
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li>Creating a document-modal dialog without an owner:<br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Since <code>Dialog</code> is a class derived from
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <code>Window</code>, a <code>Dialog</code> instance automatically
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk becomes the root of the document if it has no owner. Thus, if
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk such a dialog is document-modal, its scope of blocking is empty
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk and it behaves the same way as a modeless dialog.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li>Creating an application-modal or toolkit-modal dialog with an
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk owner:<br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk The scope of blocking for an application- or toolkit-modal
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk dialog, as opposed to a document-modal dialog, doesn't depend on
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk its owner. Thus, in this case the only thing that the owner
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk affects is the Z-order: the dialog always stays on top of its owner.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li></ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <blockquote><hr>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <b>Implementation note</b>: Changing the modality type for a visible
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk dialog may have no effect until it is hidden and then shown again.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <hr></blockquote>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <a name="ShowHideBlocking"></a>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><h3>Show/hide blocking</h3>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Showing the window or modeless dialog: "F"</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk All the visible modal dialogs are looked through &#151; if F is from the SB
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk of one of them, it becomes blocked by it. If there are several such
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk dialogs, the first shown is used. If no such dialogs exist, F remains
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk unblocked.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Showing the modal dialog: "M"</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk When modal dialog M is shown, all the visible windows fall into one of
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk three distinct groups:
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li>Blockers of M (modal dialogs that block M and
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk either are in M's child hierarchy, or are not blocked by M, or have
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk a greater mode of modality, or block some other blocker of M)
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li>Blocked by M (windows from M's SB that are not blockers and are
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk not in child hierarchy of any blocker)
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li>All other windows (windows or modeless
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk dialogs outside M's SB and modal dialogs outside M's SB that do not
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk block M).
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </ul>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk After the modal dialog M is shown, it becomes blocked by the first shown
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk dialog from the first group (if there are any), all the windows from the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk second one become blocked by M, and all the windows from the third group
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk remain untouched.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>In typical cases</u>, when no child dialogs are shown before their owners,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk this rule can be simplified. (The following, simplified case, may
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk leave out some details).
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Showing the document-modal dialog: "M"</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk All the visible application- and toolkit-modal dialogs are looked
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk through &#151; if M is from the SB of one of them,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk it becomes blocked by it. If there are several such dialogs,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk the first shown is used. If no such dialogs exist, M remains unblocked.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Showing the application-modal dialog: "M"</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk All the visible toolkit-modal dialogs are looked through &#151;
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk if M is from the SB of one of them, it becomes blocked by it.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk If there are several such dialogs, the first shown is used.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk If no such dialogs exist, M remains unblocked.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <u>Showing the toolkit-modal dialog: "M"</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk M remains unblocked.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p><p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<!-- <center> -->
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </p>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <table border="1" cols="5" rows="5">
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <caption>The Standard Blocking Matrix</caption>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <tbody><tr align="center">
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">current/shown</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">frame &amp; modeless</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">document</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">application</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">toolkit</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </tr>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <tr align="center">
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">-</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">-</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">-</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">-</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">-</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </tr>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <tr align="center">
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">document</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <td align="center">blocked</td>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <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&#151; however, the actual behavior is unspecified
and platform-dependent. In any case, the user can't close the blocked window
interactively&#151; 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&#151;
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> &#151; 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> &#151; 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> &#151; 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> &#151;
it's in the same document<br>
<li>D<sub>i</sub> is hidden<br>
<li>F becomes blocked by D<sub>ii</sub> &#151; 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> &#151; 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> &#151;
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> &#151; it's its owner<br>
<li>D<sub>iii</sub> remains unblocked &#151; 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> &#151; 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> &#151; 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> &#151; 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>