1 <!-- 2 Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved. 3 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 5 This code is free software; you can redistribute it and/or modify it 6 under the terms of the GNU General Public License version 2 only, as 7 published by the Free Software Foundation. Oracle designates this 8 particular file as subject to the "Classpath" exception as provided 9 by Oracle in the LICENSE file that accompanied this code. 10 11 This code is distributed in the hope that it will be useful, but WITHOUT 12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 version 2 for more details (a copy is included in the LICENSE file that 15 accompanied this code). 16 17 You should have received a copy of the GNU General Public License version 18 2 along with this work; if not, write to the Free Software Foundation, 19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 or visit www.oracle.com if you need additional information or have any 23 questions. 24 --> 25 26 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 27 28 <html> 29 30 <head> 31 32 <title>The AWT Modality</title> 33 34 </head> 35 36 <body bgcolor="white"> 37 38 <h1 align="center">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 name="Definitions"></a> 57 <h3>Definitions</h3> 58 59 <p> 60 <u>Document</u> - 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 — its root can be found as 64 the closest ancestor window without an owner. 65 </p><p> 66 <a name="ModalBlocked"></a> 67 <u>Modal blocked window</u> - 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 — in that case the last requirement 77 may not be met. 78 <hr> 79 </blockquote> 80 <p> 81 <u>Modal dialog</u> - 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 <u>Modal excluded window</u> - 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 <u>Scope of blocking (SB)</u> - 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 — in other words 95 an instance of <code>java.awt.Window</code> or any descendant class. 96 <hr></blockquote> 97 98 <a name="ModalityTypes"></a> 99 <h3>Modality types</h3> 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><u>Modeless dialogs</u><br> 113 A modeless dialog doesn't block any windows while visible. 114 </li><li><u>Document-modal dialogs</u><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><u>Application-modal dialogs</u><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><u>Toolkit-modal dialogs</u><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 name="ShowHideBlocking"></a> 163 <h3>Show/hide blocking</h3> 164 165 <p> 166 <u>Showing the window or modeless dialog: "F"</u><br> 167 All the visible modal dialogs are looked through — 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 <u>Showing the modal dialog: "M"</u><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 <u>In typical cases</u>, 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 <u>Showing the document-modal dialog: "M"</u><br> 196 All the visible application- and toolkit-modal dialogs are looked 197 through — 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 <u>Showing the application-modal dialog: "M"</u><br> 202 All the visible toolkit-modal dialogs are looked through — 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 <u>Showing the toolkit-modal dialog: "M"</u><br> 208 M remains unblocked. 209 </p><p> 210 <!-- <center> --> 211 </p> 212 <table border="1"> 213 <caption>The Standard Blocking Matrix</caption> 214 <tbody><tr align="center"> 215 <td align="center">current/shown</td> 216 <td align="center">frame & modeless</td> 217 <td align="center">document</td> 218 <td align="center">application</td> 219 <td align="center">toolkit</td> 220 </tr> 221 <tr align="center"> 222 <td align="center">-</td> 223 <td align="center">-</td> 224 <td align="center">-</td> 225 <td align="center">-</td> 226 <td align="center">-</td> 227 </tr> 228 <tr align="center"> 229 <td align="center">document</td> 230 <td align="center">blocked</td> 231 <td align="center">-</td> 232 <td align="center">-</td> 233 <td align="center">-</td> 234 </tr> 235 <tr align="center"> 236 <td align="center">application</td> 237 <td align="center">blocked</td> 238 <td align="center">blocked</td> 239 <td align="center">-</td> 240 <td align="center">-</td> 241 </tr> 242 <tr align="center"> 243 <td align="center">toolkit</td> 244 <td align="center">blocked</td> 245 <td align="center">blocked</td> 246 <td align="center">blocked</td> 247 <td align="center">-</td> 248 </tr> 249 </tbody></table> 250 <!-- </center> --> 251 <p> 252 After the modal dialog is shown, all the windows from its SB are blocked, 253 except those that block this modal dialog. 254 </p><p> 255 <u>Hiding the window or modeless dialog: "F"</u><br> 256 If F was blocked by any modal dialog M, it becomes unblocked and is 257 removed from M's blocked windows list. 258 </p><p> 259 <u>Hiding the modal dialog: "M"</u><br> 260 If M was blocked by any other modal dialog, for example, "N", 261 it becomes unblocked and 262 is removed from N's blocked windows list. Then, all the windows and dialogs 263 blocked by M become unblocked, and after that the same checks 264 (as in Showing the modal dialog: "M") 265 are performed for each of them in the order they were initially shown. 266 267 <a name="ModalExclusion"></a> 268 </p><h3>Modal exclusion</h3> 269 270 <p> 271 There are two modal exclusion types introduced as of JDK 6 272 </p><ul> 273 <li>Exclusion from blocking of toolkit-modal dialogs 274 </li><li>Exclusion from blocking of application-modal dialogs 275 </li></ul> 276 By default, a window's modal exclusion property is turned off. 277 <ol> 278 <li><u>Application-modal exclusion</u><br> 279 If a window is application-modal excluded, it is not blocked by any 280 application-modal dialogs. Also, it is not blocked by document-modal 281 dialogs from outside of its child hierarchy. 282 </li><li><u>Toolkit-modal exclusion</u><br> 283 If a window is toolkit-modal excluded, it is not blocked 284 by any application- or toolkit-modal dialogs. Also, it is not 285 blocked by document-modal dialogs from outside of their child hierarchy. 286 </li></ol> 287 <blockquote> 288 <hr> 289 <b>Implementation note</b>: Changing the modal exclusion type for a visible window 290 may have no effect until it is hidden and then shown again. 291 </blockquote> 292 293 <a name="Related"></a> 294 <h3>Related AWT features</h3> 295 296 <p> 297 <u>Always-On-Top</u><br> 298 When a modal dialog that is not always-on-top blocks an always-on-top window, 299 their relative Z-order is unspecified and platform-dependent. 300 </p> 301 <p> 302 <u>The <code>toFront()</code> and <code>toBack()</code> methods</u><br> 303 A modal dialog should always be above all its blocked windows. Thus, if a blocked 304 window is brought to the front, its blocking dialog, if any, is also brought to the 305 front and remains above the blocked window. Likewise, if a modal dialog is sent to 306 the back, all of its blocked windows are sent to the back to keep them below the 307 blocking dialog. 308 </p> 309 <p> 310 <u>Minimizing, maximizing and closing blocked windows</u><br> 311 When a modal dialog blocks a window, the user may not be able to maximize or 312 minimize the blocked window— however, the actual behavior is unspecified 313 and platform-dependent. In any case, the user can't close the blocked window 314 interactively— but it can be closed programmatically by calling the 315 <code>setVisible(false)</code> or <code>dispose()</code> methods on the blocked 316 window. 317 </p> 318 <p> 319 <u>Blocked windows activations</u><br> 320 When the user selects a blocked window, it may be brought to the front, along 321 with the blocking modal dialog which would then become the active window— 322 however, the actual behavior is unspecified and platform-dependent. 323 </p> 324 <p> 325 <u>Hiding a modal dialog</u><br> 326 When the modal dialog that currently has focus is hidden, it is unspecified 327 and platform-dependent, which other window will become the active window. 328 Any of the following may become the active window: 329 <ol> 330 <li>The owner of the modal dialog - if the owner is unblocked. 331 </li><li>The <code>Window</code>, which was active before this modal dialog gained 332 focus - if the owner of the modal dialog is absent or is blocked. 333 </li></ol> 334 If the modal dialog to be hidden does not have focus, the active window remains 335 unchanged. 336 337 <a name="Security"></a> 338 <h3>Security</h3> 339 340 <p> 341 A special <code>AWTPermission</code>, <code>"toolkitModality"</code>, 342 is required to show toolkit-modal 343 dialogs. This would prevent, for example, blocking a browser or 344 Java Web Start (JWS) by modal dialogs shown from applets. 345 </p><p> 346 The same permission is required to exclude a window from toolkit modality. 347 This would prevent, for example, a dialog shown from an applet not to be 348 blocked by a browser's or JWS's modal dialog. 349 350 <a name="PlatformSupport"></a> 351 </p><h3>Platform support</h3> 352 353 <p> 354 Two <code>java.awt.Toolkit</code> methods allow you to check whether 355 the current platform supports specific modality features: 356 </p><ul> 357 <li><code>isModalityTypeSupported(modalityType)</code><br> 358 Returns whether the specified modality type is supported on 359 the current platform. 360 If mode "M" is not supported and a dialog is set to M-modal, 361 it behaves as modeless. 362 </li> 363 <li><code>isModalExclusionTypeSupported(modalExclusionType)</code><br> 364 Returns whether the given modal exclusion type is supported on 365 the current platform. If exclusion type "E" is not supported 366 and a window is marked as E-excluded, this has no effect. 367 </li></ul> 368 369 <a name="Compatibility"></a> 370 <h3>Compatibility</h3> 371 372 <p> 373 The default modality type is application-modal. It is used by the API 374 calls: <code>Dialog.setModal(true)</code>, 375 <code>Dialog(owner, true)</code>, etc. Prior to JDK 6 376 the default type was toolkit-modal, 377 but the only distinction between application- and toolkit-modality is for 378 applets and applications launched from Java Web Start. 379 380 <a name="Examples"></a> 381 </p><h3>Examples</h3> 382 383 <table border="0"> 384 <tbody><tr> 385 <td align="left" > 386 <ol> 387 <li>Frame "F" is shown<br> 388 <li>Document-modal dialog "D<sub>i</sub>" is shown<br> 389 <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br> 390 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br> 391 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — it's in the 392 same document<br> 393 </ol> 394 <br> 395 </td> 396 <td align="center"> 397 <img src="modal-example1.gif" alt="Example 1"> 398 <br> 399 </td> 400 </tr> 401 <tr> 402 <td align="left"> 403 <ol> 404 <li>Frame "F" is shown<br> 405 <li>Document-modal dialog "D<sub>i</sub>" is shown<br> 406 <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br> 407 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br> 408 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — 409 it's in the same document<br> 410 <li>D<sub>i</sub> is hidden<br> 411 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br> 412 </ol> 413 <br> 414 </td> 415 <td align="center"> 416 <img src="modal-example2.gif" alt="Example 2"> 417 <br> 418 </td> 419 </tr> 420 <tr> 421 <td align="left"> 422 <ol> 423 <li>Frame "F" is shown<br> 424 <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br> 425 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br> 426 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br> 427 <li>Application-modal dialog "D<sub>iii</sub>" is shown<br> 428 <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> — 429 it's in the same application<br> 430 <li>D<sub>i</sub> is shown<br> 431 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — it's its owner<br> 432 <li>D<sub>iii</sub> remains unblocked — it blocks D<sub>ii</sub> and 433 D<sub>ii</sub> blocks D<sub>i</sub><br> 434 </ol> 435 <br> 436 </td> 437 <td align="center"> 438 <img src="modal-example3.gif" alt="Example 3"> 439 <br> 440 </td> 441 </tr> 442 <tr> 443 <td align="left"> 444 <ol> 445 <li>Frame "F" is shown<br> 446 <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br> 447 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br> 448 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br> 449 <li>Application-modal dialog "D<sub>iii</sub>" is shown<br> 450 <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> — it's in the 451 same application<br> 452 <li>D<sub>i</sub> is shown<br> 453 <li>D<sub>iii</sub> becomes blocked by D<sub>i</sub> — D<sub>i</sub> 454 is not blocked<br> 455 <li>D<sub>i</sub> remains unblocked<br> 456 </ol> 457 <br> 458 </td> 459 <td align="center"> 460 <img src="modal-example4.gif" alt="Example 4"> 461 <br> 462 </td> 463 </tr> 464 </tbody></table> 465 466 </body></html> --- EOF ---