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, 2018, 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
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
210 <table border="1">
211 <caption>The Standard Blocking Matrix</caption>
212 <tbody><tr>
213 <td>current/shown</td>
214 <td>frame & modeless</td>
215 <td>document</td>
216 <td>application</td>
217 <td>toolkit</td>
218 </tr>
219 <tr>
220 <td>-</td>
221 <td>-</td>
222 <td>-</td>
223 <td>-</td>
224 <td>-</td>
225 </tr>
226 <tr>
227 <td>document</td>
228 <td>blocked</td>
229 <td>-</td>
230 <td>-</td>
231 <td>-</td>
232 </tr>
233 <tr>
234 <td>application</td>
235 <td>blocked</td>
236 <td>blocked</td>
237 <td>-</td>
238 <td>-</td>
239 </tr>
240 <tr>
241 <td>toolkit</td>
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 <u>Hiding the window or modeless dialog: "F"</u><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 <u>Hiding the modal dialog: "M"</u><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
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 <table border="0">
382 <tbody><tr>
383 <td style="text-align:left" >
384 <ol>
385 <li>Frame "F" is shown<br>
386 <li>Document-modal dialog "D<sub>i</sub>" is shown<br>
387 <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br>
388 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
389 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — it's in the
390 same document<br>
391 </ol>
392 <br>
393 </td>
394 <td>
395 <img src="modal-example1.gif" alt="Example 1">
396 <br>
397 </td>
398 </tr>
399 <tr>
400 <td style="text-align:left">
401 <ol>
402 <li>Frame "F" is shown<br>
403 <li>Document-modal dialog "D<sub>i</sub>" is shown<br>
404 <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br>
405 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
406 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> —
407 it's in the same document<br>
408 <li>D<sub>i</sub> is hidden<br>
409 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br>
410 </ol>
411 <br>
412 </td>
413 <td>
414 <img src="modal-example2.gif" alt="Example 2">
415 <br>
416 </td>
417 </tr>
418 <tr>
419 <td style="text-align:left">
420 <ol>
421 <li>Frame "F" is shown<br>
422 <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br>
423 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
424 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br>
425 <li>Application-modal dialog "D<sub>iii</sub>" is shown<br>
426 <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> —
427 it's in the same application<br>
428 <li>D<sub>i</sub> is shown<br>
429 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — it's its owner<br>
430 <li>D<sub>iii</sub> remains unblocked — it blocks D<sub>ii</sub> and
431 D<sub>ii</sub> blocks D<sub>i</sub><br>
432 </ol>
433 <br>
434 </td>
435 <td>
436 <img src="modal-example3.gif" alt="Example 3">
437 <br>
438 </td>
439 </tr>
440 <tr>
441 <td style="text-align:left">
442 <ol>
443 <li>Frame "F" is shown<br>
444 <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br>
445 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
446 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br>
447 <li>Application-modal dialog "D<sub>iii</sub>" is shown<br>
448 <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> — it's in the
449 same application<br>
450 <li>D<sub>i</sub> is shown<br>
451 <li>D<sub>iii</sub> becomes blocked by D<sub>i</sub> — D<sub>i</sub>
452 is not blocked<br>
453 <li>D<sub>i</sub> remains unblocked<br>
454 </ol>
455 <br>
456 </td>
457 <td>
458 <img src="modal-example4.gif" alt="Example 4">
459 <br>
460 </td>
461 </tr>
462 </tbody></table>
463 </main>
464 </body></html>
|
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
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
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 & 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 <u>Hiding the window or modeless dialog: "F"</u><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 <u>Hiding the modal dialog: "M"</u><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
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 <table border="0" role="presentation">
382 <tbody><tr>
383 <td>
384 <img src="modal-example1.gif" alt="Example 1">
385 </td>
386 <td style="text-align:left" >
387 <ol>
388 <li>Frame "F" is shown<br>
389 <li>Document-modal dialog "D<sub>i</sub>" is shown<br>
390 <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br>
391 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
392 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — it's in the
393 same document<br>
394 </ol>
395 </td>
396 </tr>
397 <tr>
398 <td>
399 <img src="modal-example2.gif" alt="Example 2">
400 </td>
401 <td style="text-align:left">
402 <ol>
403 <li>Frame "F" is shown<br>
404 <li>Document-modal dialog "D<sub>i</sub>" is shown<br>
405 <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br>
406 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
407 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> —
408 it's in the same document<br>
409 <li>D<sub>i</sub> is hidden<br>
410 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br>
411 </ol>
412 </td>
413 </tr>
414 <tr>
415 <td>
416 <img src="modal-example3.gif" alt="Example 3">
417 </td>
418 <td style="text-align:left">
419 <ol>
420 <li>Frame "F" is shown<br>
421 <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br>
422 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
423 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br>
424 <li>Application-modal dialog "D<sub>iii</sub>" is shown<br>
425 <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> —
426 it's in the same application<br>
427 <li>D<sub>i</sub> is shown<br>
428 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — it's its owner<br>
429 <li>D<sub>iii</sub> remains unblocked — it blocks D<sub>ii</sub> and
430 D<sub>ii</sub> blocks D<sub>i</sub><br>
431 </ol>
432 </td>
433 </tr>
434 <tr>
435 <td>
436 <img src="modal-example4.gif" alt="Example 4">
437 </td>
438 <td style="text-align:left">
439 <ol>
440 <li>Frame "F" is shown<br>
441 <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br>
442 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
443 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br>
444 <li>Application-modal dialog "D<sub>iii</sub>" is shown<br>
445 <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> — it's in the
446 same application<br>
447 <li>D<sub>i</sub> is shown<br>
448 <li>D<sub>iii</sub> becomes blocked by D<sub>i</sub> — D<sub>i</sub>
449 is not blocked<br>
450 <li>D<sub>i</sub> remains unblocked<br>
451 </ol>
452 </td>
453 </tr>
454 </tbody></table>
455 </main>
456 </body></html>
|