1 <!doctype html>
   2 <html lang="en">
   3 <head>
   4   <meta charset="utf-8"/>
   5   <title>The AWT Modality</title>
   6   <style>
   7     td {text-align: center;}
   8     tr {text-align: center;}
   9   </style>
  10 </head>
  11 <!--
  12  Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
  13  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  14 
  15  This code is free software; you can redistribute it and/or modify it
  16  under the terms of the GNU General Public License version 2 only, as
  17  published by the Free Software Foundation.  Oracle designates this
  18  particular file as subject to the "Classpath" exception as provided
  19  by Oracle in the LICENSE file that accompanied this code.
  20 
  21  This code is distributed in the hope that it will be useful, but WITHOUT
  22  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  23  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  24  version 2 for more details (a copy is included in the LICENSE file that
  25  accompanied this code).
  26 
  27  You should have received a copy of the GNU General Public License version
  28  2 along with this work; if not, write to the Free Software Foundation,
  29  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  30 
  31  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  32  or visit www.oracle.com if you need additional information or have any
  33  questions.
  34 -->
  35 
  36 <body>
  37 <main role="main">
  38     <h1>The AWT Modality</h1>
  39 
  40     <p>
  41       This document, together with the API documentation for modality-related
  42       classes (such as <code>java.awt.Dialog</code>), briefly describes the new
  43       modality features and how to use them. It contains the following sections:
  44     </p><ul>
  45       <li><a href="#Definitions">Definitions</a></li>
  46       <li><a href="#ModalityTypes">Modality types</a></li>
  47       <li><a href="#ShowHideBlocking">Show/hide blocking</a></li>
  48       <li><a href="#ModalExclusion">Modal exclusion</a></li>
  49       <li><a href="#Related">Related AWT features</a></li>
  50       <li><a href="#Security">Security</a></li>
  51       <li><a href="#PlatformSupport">Platform support</a></li>
  52       <li><a href="#Compatibility">Compatibility</a></li>
  53       <li><a href="#Examples">Examples</a></li>
  54     </ul>
  55 
  56     <a id="Definitions"></a>
  57     <h2>Definitions</h2>
  58 
  59     <p>
  60       Document - a window without an owner that, together with
  61       all its child hierarchy, may be operated on as a single self-contained
  62       document.
  63       Every window belongs to some document &mdash; its root can be found as
  64       the closest ancestor window without an owner.
  65     </p><p>
  66       <a id="ModalBlocked"></a>
  67       Modal blocked window - a window, that:
  68       </p><ul>
  69         <li>doesn't receive any user input events
  70         </li><li>doesn't receive input focus
  71         </li><li>keeps its Z-order below the modal dialog that blocks it
  72       </li></ul>
  73       <blockquote>
  74         <hr>
  75           <b>Warning!</b> Some window managers allow users to change the window
  76           Z-order in an arbitrary way &mdash; in that case the last requirement
  77           may not be met.
  78         <hr>
  79       </blockquote>
  80     <p>
  81       Modal dialog - a dialog that blocks some windows while it is
  82       visible. The blocked windows are determined according to the dialog's
  83       scope of blocking.
  84     </p><p>
  85       Modal excluded window - a window that stays unblocked
  86       while the modal dialog is visible. If a window is modal excluded
  87       then all its owned windows and child components are also excluded.
  88     </p><p>
  89       Scope of blocking (SB) - the set of windows (instances of
  90       <code>java.awt.Window</code> and all derived classes) that are blocked by
  91       the modal dialog while it is visible.
  92      <blockquote><hr>
  93       <b>Note</b>: Everywhere in this document the notion of "window" is equal
  94       to a top-level window in the Java programming language &mdash; in other words
  95       an instance of <code>java.awt.Window</code> or any descendant class.
  96       <hr></blockquote>
  97 
  98     <a id="ModalityTypes"></a>
  99     <h2>Modality types</h2>
 100 
 101     <p>
 102       There are four supported modality types :
 103       </p><ul>
 104         <li>toolkit
 105         </li><li>application
 106         </li><li>document
 107         </li><li>modeless
 108       </li></ul>
 109       A dialog is, by default, modeless.  A modal dialog is, by default,
 110       application-modal.
 111     <ol>
 112       <li>Modeless dialogs<br>
 113         A modeless dialog doesn't block any windows while visible.
 114       </li><li>Document-modal dialogs<br>
 115         A document-modal dialog blocks all windows from the same
 116         document except those from its child hierarchy. The document root
 117         is determined as the closest ancestor window without an
 118         owner.
 119       </li><li>Application-modal dialogs<br>
 120         An application-modal dialog blocks all windows from the same
 121         application except for those from its child hierarchy.
 122         If there are several applets launched in a browser, they can be
 123         treated either as separate applications or a single application.
 124         This behavior is implementation-dependent.
 125       </li><li>Toolkit-modal dialogs<br>
 126         A toolkit-modal dialog blocks all windows that run in the same
 127         toolkit except those from its child hierarchy. If there
 128         are several applets launched all of them run with the same toolkit,
 129         so a toolkit-modal dialog shown from an applet may affect other
 130         applets and all windows of the browser instance which embeds the
 131         Java runtime environment for this toolkit.
 132         See the security section below.
 133     </li></ol>
 134     <p>
 135       Modality priority is arranged by the strength of blocking: modeless,
 136       document-modal, application-modal and toolkit-modal. This arrangement
 137       is used when determining what dialog should remain unblocked if two
 138       are visible and block each other. It naturally reflects the nesting
 139       of a dialog's scope of blocking (SB): a modeless dialog has an empty SB,
 140       a document-modal dialog's SB is complete in some applications,
 141       and all the applications are run in one toolkit.  </p><p>
 142       Notes about owners:
 143       </p><ul>
 144         <li>Creating a document-modal dialog without an owner:<br>
 145           Since <code>Dialog</code> is a class derived from
 146           <code>Window</code>, a <code>Dialog</code> instance automatically
 147           becomes the root of the document if it has no owner. Thus, if
 148           such a dialog is document-modal, its scope of blocking is empty
 149           and it behaves the same way as a modeless dialog.
 150         </li><li>Creating an application-modal or toolkit-modal dialog with an
 151           owner:<br>
 152           The scope of blocking for an application- or toolkit-modal
 153           dialog, as opposed to a document-modal dialog, doesn't depend on
 154           its owner. Thus, in this case the only thing that the owner
 155           affects is the Z-order: the dialog always stays on top of its owner.
 156       </li></ul>
 157     <blockquote><hr>
 158       <b>Implementation note</b>: Changing the modality type for a visible
 159       dialog may have no effect until it is hidden and then shown again.
 160       <hr></blockquote>
 161 
 162     <a id="ShowHideBlocking"></a>
 163     <h2>Show/hide blocking</h2>
 164 
 165     <p>
 166       Showing the window or modeless dialog: "F"<br>
 167       All the visible modal dialogs are looked through &mdash; if F is from the SB
 168       of one of them, it becomes blocked by it. If there are several such
 169       dialogs, the first shown is used. If no such dialogs exist, F remains
 170       unblocked.
 171     </p><p>
 172       Showing the modal dialog: "M"<br>
 173       When modal dialog M is shown, all the visible windows fall into one of
 174       three distinct groups:
 175       <ul>
 176       <li>Blockers of M (modal dialogs that block M and
 177       either are in M's child hierarchy, or are not blocked by M, or have
 178       a greater mode of modality, or block some other blocker of M)
 179       <li>Blocked by M (windows from M's SB that are not blockers and are
 180       not in child hierarchy of any blocker)
 181       <li>All other windows (windows or modeless
 182       dialogs outside M's SB and modal dialogs outside M's SB that do not
 183       block M).
 184       </ul>
 185       <p>
 186       After the modal dialog M is shown, it becomes blocked by the first shown
 187       dialog from the first group (if there are any), all the windows from the
 188       second one become blocked by M, and all the windows from the third group
 189       remain untouched.
 190     </p><p>
 191       In typical cases, when no child dialogs are shown before their owners,
 192       this rule can be simplified. (The following, simplified case, may
 193       leave out some details).
 194       </p><p>
 195       Showing the document-modal dialog: "M"<br>
 196       All the visible application- and toolkit-modal dialogs are looked
 197       through &mdash; if M is from the SB of one of them,
 198       it becomes blocked by it. If there are several such dialogs,
 199       the first shown is used. If no such dialogs exist, M remains unblocked.
 200       </p><p>
 201       Showing the application-modal dialog: "M"<br>
 202       All the visible toolkit-modal dialogs are looked through &mdash;
 203       if M is from the SB of one of them, it becomes blocked by it.
 204       If there are several such dialogs, the first shown is used.
 205       If no such dialogs exist, M remains unblocked.
 206       </p><p>
 207       Showing the toolkit-modal dialog: "M"<br>
 208       M remains unblocked.
 209 
 210           <table border="1">
 211                 <caption>The Standard Blocking Matrix</caption>
 212             <tbody><tr>
 213               <th scope="col">current/shown</th>
 214               <th scope="col">frame &amp; modeless</th>
 215               <th scope="col">document</th>
 216               <th scope="col">application</th>
 217               <th scope="col">toolkit</th>
 218             </tr>
 219             <tr>
 220               <th scope="row">-</th>
 221               <td>-</td>
 222               <td>-</td>
 223               <td>-</td>
 224               <td>-</td>
 225             </tr>
 226             <tr>
 227               <th scope="row">document</th>
 228               <td>blocked</td>
 229               <td>-</td>
 230               <td>-</td>
 231               <td>-</td>
 232             </tr>
 233             <tr>
 234               <th scope="row">application</th>
 235               <td>blocked</td>
 236               <td>blocked</td>
 237               <td>-</td>
 238               <td>-</td>
 239             </tr>
 240             <tr>
 241               <th scope="row">toolkit</th>
 242               <td>blocked</td>
 243               <td>blocked</td>
 244               <td>blocked</td>
 245               <td>-</td>
 246             </tr>
 247           </tbody>
 248         </table>
 249       <p>
 250       After the modal dialog is shown, all the windows from its SB are blocked,
 251       except those that block this modal dialog.
 252     </p><p>
 253       Hiding the window or modeless dialog: "F"<br>
 254       If F was blocked by any modal dialog M, it becomes unblocked and is
 255       removed from M's blocked windows list.
 256     </p><p>
 257       Hiding the modal dialog: "M"<br>
 258       If M was blocked by any other modal dialog, for example, "N",
 259       it becomes unblocked and
 260       is removed from N's blocked windows list. Then, all the windows and dialogs
 261       blocked by M become unblocked, and after that the same checks
 262       (as in Showing the modal dialog: "M")
 263       are performed for each of them in the order they were initially shown.
 264 
 265     <a id="ModalExclusion"></a>
 266     </p><h2>Modal exclusion</h2>
 267 
 268     <p>
 269       There are two modal exclusion types introduced as of JDK 6
 270       </p><ul>
 271         <li>Exclusion from blocking of toolkit-modal dialogs
 272         </li><li>Exclusion from blocking of application-modal dialogs
 273       </li></ul>
 274       By default, a window's modal exclusion property is turned off.
 275       <ol>
 276         <li>Application-modal exclusion<br>
 277           If a window is application-modal excluded, it is not blocked by any
 278           application-modal dialogs. Also, it is not blocked by document-modal
 279           dialogs from outside of its child hierarchy.
 280         </li><li>Toolkit-modal exclusion<br>
 281           If a window is toolkit-modal excluded, it is not blocked
 282           by any application- or toolkit-modal dialogs. Also, it is not
 283           blocked by document-modal dialogs from outside of their child hierarchy.
 284       </li></ol>
 285     <blockquote>
 286       <hr>
 287         <b>Implementation note</b>: Changing the modal exclusion type for a visible window
 288         may have no effect until it is hidden and then shown again.<hr>
 289     </blockquote>
 290 
 291     <a id="Related"></a>
 292     <h2>Related AWT features</h2>
 293 
 294     <p>
 295       Always-On-Top<br>
 296       When a modal dialog that is not always-on-top blocks an always-on-top window,
 297       their relative Z-order is unspecified and platform-dependent.
 298     </p>
 299     <p>
 300       The <code>toFront()</code> and <code>toBack()</code> methods<br>
 301       A modal dialog should always be above all its blocked windows. Thus, if a blocked
 302       window is brought to the front, its blocking dialog, if any, is also brought to the
 303       front and remains above the blocked window. Likewise, if a modal dialog is sent to
 304       the back, all of its blocked windows are sent to the back to keep them below the
 305       blocking dialog.
 306     </p>
 307     <p>
 308       Minimizing, maximizing and closing blocked windows<br>
 309       When a modal dialog blocks a window, the user may not be able to maximize or
 310       minimize the blocked window&mdash; however, the actual behavior is unspecified
 311       and platform-dependent. In any case, the user can't close the blocked window
 312       interactively&mdash; but it can be closed programmatically by calling the
 313       <code>setVisible(false)</code> or <code>dispose()</code> methods on the blocked
 314       window.
 315     </p>
 316     <p>
 317       Blocked windows activations<br>
 318       When the user selects a blocked window, it may be brought to the front, along
 319       with the blocking modal dialog which would then become the active window&mdash;
 320       however, the actual behavior is unspecified and platform-dependent.
 321     </p>
 322     <p>
 323       Hiding a modal dialog<br>
 324       When the modal dialog that currently has focus is hidden, it is unspecified
 325       and platform-dependent, which other window will become the active window.
 326       Any of the following may become the active window:
 327       <ol>
 328         <li>The owner of the modal dialog - if the owner is unblocked.
 329         </li><li>The <code>Window</code>, which was active before this modal dialog gained
 330         focus - if the owner of the modal dialog is absent or is blocked.
 331       </li></ol>
 332       If the modal dialog to be hidden does not have focus, the active window remains
 333       unchanged.
 334 
 335     <a id="Security"></a>
 336     <h2>Security</h2>
 337 
 338     <p>
 339       A special <code>AWTPermission</code>, <code>"toolkitModality"</code>,
 340       is required to show toolkit-modal
 341       dialogs. This would prevent, for example, blocking a browser or
 342       Java Web Start (JWS) by modal dialogs shown from applets.
 343     </p><p>
 344       The same permission is required to exclude a window from toolkit modality.
 345       This would prevent, for example, a dialog shown from an applet not to be
 346       blocked by a browser's or JWS's modal dialog.
 347 
 348     <a id="PlatformSupport"></a>
 349     </p><h2>Platform support</h2>
 350 
 351     <p>
 352       Two <code>java.awt.Toolkit</code> methods allow you to check whether
 353       the current platform supports specific modality features:
 354       </p><ul>
 355         <li><code>isModalityTypeSupported(modalityType)</code><br>
 356           Returns whether the specified modality type is supported on
 357           the current platform.
 358           If mode "M" is not supported and a dialog is set to M-modal,
 359           it behaves as modeless.
 360         </li>
 361         <li><code>isModalExclusionTypeSupported(modalExclusionType)</code><br>
 362           Returns whether the given modal exclusion type is supported on
 363           the current platform. If exclusion type "E" is not supported
 364           and a window is marked as E-excluded, this has no effect.
 365       </li></ul>
 366 
 367     <a id="Compatibility"></a>
 368     <h2>Compatibility</h2>
 369 
 370     <p>
 371       The default modality type is application-modal. It is used by the API
 372       calls: <code>Dialog.setModal(true)</code>,
 373       <code>Dialog(owner, true)</code>, etc. Prior to JDK 6
 374       the default type was toolkit-modal,
 375       but the only distinction between application- and toolkit-modality is for
 376       applets and applications launched from Java Web Start.
 377 
 378     <a id="Examples"></a>
 379     </p><h2>Examples</h2>
 380 
 381     <h3>Example 1</h3>
 382     <ol style="float: left">
 383         <li>Frame F is shown<br>
 384         <li>Document-modal dialog D<sub>i</sub> is shown<br>
 385         <li>F becomes blocked by D<sub>i</sub> &mdash; it's in the same document<br>
 386         <li>Document-modal dialog D<sub>ii</sub> is shown<br>
 387         <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> &mdash; it's in the
 388             same document<br>
 389     </ol>
 390     <p style="float: left; margin-left: 1em">
 391         <img src="modal-example1.gif" alt="Example 1">
 392     </p>
 393 
 394     <h3 style="clear: left">Example 2</h3>
 395     <ol style="float: left">
 396         <li>Frame F is shown<br>
 397         <li>Document-modal dialog D<sub>i</sub> is shown<br>
 398         <li>F becomes blocked by D<sub>i</sub> &mdash; it's in the same document<br>
 399         <li>Document-modal dialog D<sub>ii</sub> is shown<br>
 400         <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> &mdash; it's in the
 401             same document<br>
 402     </ol>
 403     <p style="float: left; margin-left: 1em">
 404         <img src="modal-example2.gif" alt="Example 2">
 405     </p>
 406 
 407     <h3 style="clear: left">Example 3</h3>
 408     <ol style="float: left">
 409         <li>Frame F is shown<br>
 410         <li>Toolkit-modal dialog D<sub>i</sub> is created, but not shown<br>
 411         <li>Document-modal dialog D<sub>ii</sub> is shown<br>
 412         <li>F becomes blocked by D<sub>ii</sub> &mdash; it's in the same document<br>
 413         <li>Application-modal dialog D<sub>iii</sub> is shown<br>
 414         <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> &mdash;
 415             it's in the same application<br>
 416         <li>D<sub>i</sub> is shown<br>
 417         <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> &mdash; it's its owner<br>
 418         <li>D<sub>iii</sub> remains unblocked &mdash; it blocks D<sub>ii</sub> and
 419             D<sub>ii</sub> blocks D<sub>i</sub><br>
 420     </ol>
 421     <p style="float: left; margin-left: 1em">
 422         <img src="modal-example3.gif" alt="Example 3">
 423     </p>
 424 
 425     <h3 style="clear: left">Example 4</h3>
 426     <ol style="float: left">
 427         <li>Frame F is shown<br>
 428         <li>Toolkit-modal dialog D<sub>i</sub> is created, but not shown<br>
 429         <li>Document-modal dialog D<sub>ii</sub> is shown<br>
 430         <li>F becomes blocked by D<sub>ii</sub> &mdash; it's in the same document<br>
 431         <li>Application-modal dialog D<sub>iii</sub> is shown<br>
 432         <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> &mdash; it's in the
 433             same application<br>
 434         <li>D<sub>i</sub> is shown<br>
 435         <li>D<sub>iii</sub> becomes blocked by D<sub>i</sub> &mdash; D<sub>i</sub>
 436             is not blocked<br>
 437         <li>D<sub>i</sub> remains unblocked<br>
 438     </ol>
 439     <p style="float: left; margin-left: 1em">
 440         <img src="modal-example4.gif" alt="Example 4">
 441     </p>
 442     <br style="clear:both;">
 443 </main>
 444 </body></html>