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