3 <head> |
3 <head> |
4 <meta charset="utf-8"/> |
4 <meta charset="utf-8"/> |
5 <title>The AWT Modality</title> |
5 <title>The AWT Modality</title> |
6 </head> |
6 </head> |
7 <!-- |
7 <!-- |
8 Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. |
8 Copyright (c) 2005, 2018, Oracle and/or its affiliates. All rights reserved. |
9 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
9 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
10 |
10 |
11 This code is free software; you can redistribute it and/or modify it |
11 This code is free software; you can redistribute it and/or modify it |
12 under the terms of the GNU General Public License version 2 only, as |
12 under the terms of the GNU General Public License version 2 only, as |
13 published by the Free Software Foundation. Oracle designates this |
13 published by the Free Software Foundation. Oracle designates this |
28 or visit www.oracle.com if you need additional information or have any |
28 or visit www.oracle.com if you need additional information or have any |
29 questions. |
29 questions. |
30 --> |
30 --> |
31 |
31 |
32 <body> |
32 <body> |
33 |
33 <main role="main"> |
34 <h1>The AWT Modality</h1> |
34 <h1>The AWT Modality</h1> |
35 |
35 |
36 <p> |
36 <p> |
37 This document, together with the API documentation for modality-related |
37 This document, together with the API documentation for modality-related |
38 classes (such as <code>java.awt.Dialog</code>), briefly describes the new |
38 classes (such as <code>java.awt.Dialog</code>), briefly describes the new |
48 <li><a href="#Compatibility">Compatibility</a></li> |
48 <li><a href="#Compatibility">Compatibility</a></li> |
49 <li><a href="#Examples">Examples</a></li> |
49 <li><a href="#Examples">Examples</a></li> |
50 </ul> |
50 </ul> |
51 |
51 |
52 <a id="Definitions"></a> |
52 <a id="Definitions"></a> |
53 <h3>Definitions</h3> |
53 <h2>Definitions</h2> |
54 |
54 |
55 <p> |
55 <p> |
56 <u>Document</u> - a window without an owner that, together with |
56 <u>Document</u> - a window without an owner that, together with |
57 all its child hierarchy, may be operated on as a single self-contained |
57 all its child hierarchy, may be operated on as a single self-contained |
58 document. |
58 document. |
90 to a top-level window in the Java programming language — in other words |
90 to a top-level window in the Java programming language — in other words |
91 an instance of <code>java.awt.Window</code> or any descendant class. |
91 an instance of <code>java.awt.Window</code> or any descendant class. |
92 <hr></blockquote> |
92 <hr></blockquote> |
93 |
93 |
94 <a id="ModalityTypes"></a> |
94 <a id="ModalityTypes"></a> |
95 <h3>Modality types</h3> |
95 <h2>Modality types</h2> |
96 |
96 |
97 <p> |
97 <p> |
98 There are four supported modality types : |
98 There are four supported modality types : |
99 </p><ul> |
99 </p><ul> |
100 <li>toolkit |
100 <li>toolkit |
154 <b>Implementation note</b>: Changing the modality type for a visible |
154 <b>Implementation note</b>: Changing the modality type for a visible |
155 dialog may have no effect until it is hidden and then shown again. |
155 dialog may have no effect until it is hidden and then shown again. |
156 <hr></blockquote> |
156 <hr></blockquote> |
157 |
157 |
158 <a id="ShowHideBlocking"></a> |
158 <a id="ShowHideBlocking"></a> |
159 <h3>Show/hide blocking</h3> |
159 <h2>Show/hide blocking</h2> |
160 |
160 |
161 <p> |
161 <p> |
162 <u>Showing the window or modeless dialog: "F"</u><br> |
162 <u>Showing the window or modeless dialog: "F"</u><br> |
163 All the visible modal dialogs are looked through — if F is from the SB |
163 All the visible modal dialogs are looked through — if F is from the SB |
164 of one of them, it becomes blocked by it. If there are several such |
164 of one of them, it becomes blocked by it. If there are several such |
259 blocked by M become unblocked, and after that the same checks |
259 blocked by M become unblocked, and after that the same checks |
260 (as in Showing the modal dialog: "M") |
260 (as in Showing the modal dialog: "M") |
261 are performed for each of them in the order they were initially shown. |
261 are performed for each of them in the order they were initially shown. |
262 |
262 |
263 <a id="ModalExclusion"></a> |
263 <a id="ModalExclusion"></a> |
264 </p><h3>Modal exclusion</h3> |
264 </p><h2>Modal exclusion</h2> |
265 |
265 |
266 <p> |
266 <p> |
267 There are two modal exclusion types introduced as of JDK 6 |
267 There are two modal exclusion types introduced as of JDK 6 |
268 </p><ul> |
268 </p><ul> |
269 <li>Exclusion from blocking of toolkit-modal dialogs |
269 <li>Exclusion from blocking of toolkit-modal dialogs |
285 <b>Implementation note</b>: Changing the modal exclusion type for a visible window |
285 <b>Implementation note</b>: Changing the modal exclusion type for a visible window |
286 may have no effect until it is hidden and then shown again. |
286 may have no effect until it is hidden and then shown again. |
287 </blockquote> |
287 </blockquote> |
288 |
288 |
289 <a id="Related"></a> |
289 <a id="Related"></a> |
290 <h3>Related AWT features</h3> |
290 <h2>Related AWT features</h2> |
291 |
291 |
292 <p> |
292 <p> |
293 <u>Always-On-Top</u><br> |
293 <u>Always-On-Top</u><br> |
294 When a modal dialog that is not always-on-top blocks an always-on-top window, |
294 When a modal dialog that is not always-on-top blocks an always-on-top window, |
295 their relative Z-order is unspecified and platform-dependent. |
295 their relative Z-order is unspecified and platform-dependent. |
329 </li></ol> |
329 </li></ol> |
330 If the modal dialog to be hidden does not have focus, the active window remains |
330 If the modal dialog to be hidden does not have focus, the active window remains |
331 unchanged. |
331 unchanged. |
332 |
332 |
333 <a id="Security"></a> |
333 <a id="Security"></a> |
334 <h3>Security</h3> |
334 <h2>Security</h2> |
335 |
335 |
336 <p> |
336 <p> |
337 A special <code>AWTPermission</code>, <code>"toolkitModality"</code>, |
337 A special <code>AWTPermission</code>, <code>"toolkitModality"</code>, |
338 is required to show toolkit-modal |
338 is required to show toolkit-modal |
339 dialogs. This would prevent, for example, blocking a browser or |
339 dialogs. This would prevent, for example, blocking a browser or |
342 The same permission is required to exclude a window from toolkit modality. |
342 The same permission is required to exclude a window from toolkit modality. |
343 This would prevent, for example, a dialog shown from an applet not to be |
343 This would prevent, for example, a dialog shown from an applet not to be |
344 blocked by a browser's or JWS's modal dialog. |
344 blocked by a browser's or JWS's modal dialog. |
345 |
345 |
346 <a id="PlatformSupport"></a> |
346 <a id="PlatformSupport"></a> |
347 </p><h3>Platform support</h3> |
347 </p><h2>Platform support</h2> |
348 |
348 |
349 <p> |
349 <p> |
350 Two <code>java.awt.Toolkit</code> methods allow you to check whether |
350 Two <code>java.awt.Toolkit</code> methods allow you to check whether |
351 the current platform supports specific modality features: |
351 the current platform supports specific modality features: |
352 </p><ul> |
352 </p><ul> |
361 the current platform. If exclusion type "E" is not supported |
361 the current platform. If exclusion type "E" is not supported |
362 and a window is marked as E-excluded, this has no effect. |
362 and a window is marked as E-excluded, this has no effect. |
363 </li></ul> |
363 </li></ul> |
364 |
364 |
365 <a id="Compatibility"></a> |
365 <a id="Compatibility"></a> |
366 <h3>Compatibility</h3> |
366 <h2>Compatibility</h2> |
367 |
367 |
368 <p> |
368 <p> |
369 The default modality type is application-modal. It is used by the API |
369 The default modality type is application-modal. It is used by the API |
370 calls: <code>Dialog.setModal(true)</code>, |
370 calls: <code>Dialog.setModal(true)</code>, |
371 <code>Dialog(owner, true)</code>, etc. Prior to JDK 6 |
371 <code>Dialog(owner, true)</code>, etc. Prior to JDK 6 |
372 the default type was toolkit-modal, |
372 the default type was toolkit-modal, |
373 but the only distinction between application- and toolkit-modality is for |
373 but the only distinction between application- and toolkit-modality is for |
374 applets and applications launched from Java Web Start. |
374 applets and applications launched from Java Web Start. |
375 |
375 |
376 <a id="Examples"></a> |
376 <a id="Examples"></a> |
377 </p><h3>Examples</h3> |
377 </p><h2>Examples</h2> |
378 |
378 |
379 <table border="0"> |
379 <table border="0"> |
380 <tbody><tr> |
380 <tbody><tr> |
381 <td align="left" > |
381 <td align="left" > |
382 <ol> |
382 <ol> |