Modality.html revision 0
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 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 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 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 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<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
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 </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="#PlatformSupport">Platform support</a></li>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li><a href="#Compatibility">Compatibility</a></li>
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 Every window belongs to some document — its root can be found as
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk the closest ancestor window without an owner.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <li>doesn't receive any user input events
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </li><li>keeps its Z-order below the modal dialog that blocks it
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <blockquote>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <b>Warning!</b> Some window managers allow users to change the window
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Z-order in an arbitrary way — in that case the last requirement
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk may not be met.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk </blockquote>
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 <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 <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 <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 — in other words
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk an instance of <code>java.awt.Window</code> or any descendant class.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk There are four supported modality types :
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk A dialog is, by default, modeless. A modal dialog is, by default,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk application-modal.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk A modeless dialog doesn't block any windows while visible.
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 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 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 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 <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 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 <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 <u>Showing the window or modeless dialog: "F"</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk All the visible modal dialogs are looked through — 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 When modal dialog M is shown, all the visible windows fall into one of
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk three distinct groups:
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 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 <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 <u>Showing the document-modal dialog: "M"</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk All the visible application- and toolkit-modal dialogs are looked
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk through — 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 <u>Showing the application-modal dialog: "M"</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk All the visible toolkit-modal dialogs are looked through —
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 <u>Showing the toolkit-modal dialog: "M"</u><br>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk M remains unblocked.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<!-- <center> -->