Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / libcore / 319a3b994703aac84df7bcde272adfcb3cdbbbf0 / . / jdk / src / share / classes / java / awt / doc-files / Modality.html
blob: 5d9ee9f6ad92f324e3b42184866da233f4bb0fa9 [file] [log] [blame]
J. Duke319a3b92007-12-01 00:00:00 +0000[diff] [blame^]1<!--
2 Copyright 2005-2006 Sun Microsystems, Inc. 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. Sun designates this
8 particular file as subject to the "Classpath" exception as provided
9 by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 CA 95054 USA or visit www.sun.com if you need additional information or
23 have any 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><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 </p><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 &#151; 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 &#151; 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 </p><p>
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 &#151; in other words
96 an instance of <code>java.awt.Window</code> or any descendant class.
97 <hr></blockquote>
98
99 <a name="ModalityTypes"></a>
100 </p><h3>Modality types</h3>
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 <p>
113 </p><ol>
114 <li><u>Modeless dialogs</u><br>
115 A modeless dialog doesn't block any windows while visible.
116 </li><li><u>Document-modal dialogs</u><br>
117 A document-modal dialog blocks all windows from the same
118 document except those from its child hierarchy. The document root
119 is determined as the closest ancestor window without an
120 owner.
121 </li><li><u>Application-modal dialogs</u><br>
122 An application-modal dialog blocks all windows from the same
123 application except for those from its child hierarchy.
124 If there are several applets launched in a browser, they can be
125 treated either as separate applications or a single application.
126 This behavior is implementation-dependent.
127 </li><li><u>Toolkit-modal dialogs</u><br>
128 A toolkit-modal dialog blocks all windows that run in the same
129 toolkit except those from its child hierarchy. If there
130 are several applets launched all of them run with the same toolkit,
131 so a toolkit-modal dialog shown from an applet may affect other
132 applets and all windows of the browser instance which embeds the
133 Java runtime environment for this toolkit.
134 See the security section below.
135 </li></ol>
136 <p>
137 Modality priority is arranged by the strength of blocking: modeless,
138 document-modal, application-modal and toolkit-modal. This arrangement
139 is used when determining what dialog should remain unblocked if two
140 are visible and block each other. It naturally reflects the nesting
141 of a dialog's scope of blocking (SB): a modeless dialog has an empty SB,
142 a document-modal dialog's SB is complete in some applications,
143 and all the applications are run in one toolkit. </p><p>
144 Notes about owners:
145 </p><ul>
146 <li>Creating a document-modal dialog without an owner:<br>
147 Since <code>Dialog</code> is a class derived from
148 <code>Window</code>, a <code>Dialog</code> instance automatically
149 becomes the root of the document if it has no owner. Thus, if
150 such a dialog is document-modal, its scope of blocking is empty
151 and it behaves the same way as a modeless dialog.
152 </li><li>Creating an application-modal or toolkit-modal dialog with an
153 owner:<br>
154 The scope of blocking for an application- or toolkit-modal
155 dialog, as opposed to a document-modal dialog, doesn't depend on
156 its owner. Thus, in this case the only thing that the owner
157 affects is the Z-order: the dialog always stays on top of its owner.
158 </li></ul>
159 <p>
160 <blockquote><hr>
161 <b>Implementation note</b>: Changing the modality type for a visible
162 dialog may have no effect until it is hidden and then shown again.
163 <hr></blockquote>
164
165 <a name="ShowHideBlocking"></a>
166 </p><h3>Show/hide blocking</h3>
167
168 <p>
169 <u>Showing the window or modeless dialog: "F"</u><br>
170 All the visible modal dialogs are looked through &#151; if F is from the SB
171 of one of them, it becomes blocked by it. If there are several such
172 dialogs, the first shown is used. If no such dialogs exist, F remains
173 unblocked.
174 </p><p>
175 <u>Showing the modal dialog: "M"</u><br>
176 When modal dialog M is shown, all the visible windows fall into one of
177 three distinct groups:
178 <ul>
179 <li>Blockers of M (modal dialogs that block M and
180 either are in M's child hierarchy, or are not blocked by M, or have
181 a greater mode of modality, or block some other blocker of M)
182 <li>Blocked by M (windows from M's SB that are not blockers and are
183 not in child hierarchy of any blocker)
184 <li>All other windows (windows or modeless
185 dialogs outside M's SB and modal dialogs outside M's SB that do not
186 block M).
187 </ul>
188 </p><p>
189 After the modal dialog M is shown, it becomes blocked by the first shown
190 dialog from the first group (if there are any), all the windows from the
191 second one become blocked by M, and all the windows from the third group
192 remain untouched.
193 </p><p>
194 <u>In typical cases</u>, when no child dialogs are shown before their owners,
195 this rule can be simplified. (The following, simplified case, may
196 leave out some details).
197 </p><p>
198 <u>Showing the document-modal dialog: "M"</u><br>
199 All the visible application- and toolkit-modal dialogs are looked
200 through &#151; if M is from the SB of one of them,
201 it becomes blocked by it. If there are several such dialogs,
202 the first shown is used. If no such dialogs exist, M remains unblocked.
203 </p><p>
204 <u>Showing the application-modal dialog: "M"</u><br>
205 All the visible toolkit-modal dialogs are looked through &#151;
206 if M is from the SB of one of them, it becomes blocked by it.
207 If there are several such dialogs, the first shown is used.
208 If no such dialogs exist, M remains unblocked.
209 </p><p>
210 <u>Showing the toolkit-modal dialog: "M"</u><br>
211 M remains unblocked.
212 </p><p>
213<!-- <center> -->
214 </p>
215 <table border="1" cols="5" rows="5">
216 <caption>The Standard Blocking Matrix</caption>
217 <tbody><tr align="center">
218 <td align="center">current/shown</td>
219 <td align="center">frame &amp; modeless</td>
220 <td align="center">document</td>
221 <td align="center">application</td>
222 <td align="center">toolkit</td>
223 </tr>
224 <tr align="center">
225 <td align="center">-</td>
226 <td align="center">-</td>
227 <td align="center">-</td>
228 <td align="center">-</td>
229 <td align="center">-</td>
230 </tr>
231 <tr align="center">
232 <td align="center">document</td>
233 <td align="center">blocked</td>
234 <td align="center">-</td>
235 <td align="center">-</td>
236 <td align="center">-</td>
237 </tr>
238 <tr align="center">
239 <td align="center">application</td>
240 <td align="center">blocked</td>
241 <td align="center">blocked</td>
242 <td align="center">-</td>
243 <td align="center">-</td>
244 </tr>
245 <tr align="center">
246 <td align="center">toolkit</td>
247 <td align="center">blocked</td>
248 <td align="center">blocked</td>
249 <td align="center">blocked</td>
250 <td align="center">-</td>
251 </tr>
252 </tbody></table>
253<!-- </center> -->
254 <p>
255 After the modal dialog is shown, all the windows from its SB are blocked,
256 except those that block this modal dialog.
257 </p><p>
258 <u>Hiding the window or modeless dialog: "F"</u><br>
259 If F was blocked by any modal dialog M, it becomes unblocked and is
260 removed from M's blocked windows list.
261 </p><p>
262 <u>Hiding the modal dialog: "M"</u><br>
263 If M was blocked by any other modal dialog, for example, "N",
264 it becomes unblocked and
265 is removed from N's blocked windows list. Then, all the windows and dialogs
266 blocked by M become unblocked, and after that the same checks
267 (as in Showing the modal dialog: "M")
268 are performed for each of them in the order they were initially shown.
269
270 <a name="ModalExclusion"></a>
271 </p><h3>Modal exclusion</h3>
272
273 <p>
274 There are two modal exclusion types introduced as of JDK 6
275 </p><ul>
276 <li>Exclusion from blocking of toolkit-modal dialogs
277 </li><li>Exclusion from blocking of application-modal dialogs
278 </li></ul>
279 By default, a window's modal exclusion property is turned off.
280 <p>
281 </p><ol>
282 <li><u>Application-modal exclusion</u><br>
283 If a window is application-modal excluded, it is not blocked by any
284 application-modal dialogs. Also, it is not blocked by document-modal
285 dialogs from outside of its child hierarchy.
286 </li><li><u>Toolkit-modal exclusion</u><br>
287 If a window is toolkit-modal excluded, it is not blocked
288 by any application- or toolkit-modal dialogs. Also, it is not
289 blocked by document-modal dialogs from outside of their child hierarchy.
290 </li></ol>
291 <p>
292 <blockquote>
293 <hr>
294 <b>Implementation note</b>: Changing the modal exclusion type for a visible window
295 may have no effect until it is hidden and then shown again.
296 </hr>
297 </blockquote>
298
299 <a name="Related"</a>
300 </p><h3>Related AWT features</h3>
301
302 <p>
303 <u>Always-On-Top</u><br>
304 When a modal dialog that is not always-on-top blocks an always-on-top window,
305 their relative Z-order is unspecified and platform-dependent.
306 </p>
307 <p>
308 <u>The <code>toFront()</code> and <code>toBack()</code> methods</u><br>
309 A modal dialog should always be above all its blocked windows. Thus, if a blocked
310 window is brought to the front, its blocking dialog, if any, is also brought to the
311 front and remains above the blocked window. Likewise, if a modal dialog is sent to
312 the back, all of its blocked windows are sent to the back to keep them below the
313 blocking dialog.
314 </p>
315 <p>
316 <u>Minimizing, maximizing and closing blocked windows</u><br>
317 When a modal dialog blocks a window, the user may not be able to maximize or
318 minimize the blocked window&#151; however, the actual behavior is unspecified
319 and platform-dependent. In any case, the user can't close the blocked window
320 interactively&#151; but it can be closed programmatically by calling the
321 <code>setVisible(false)</code> or <code>dispose()</code> methods on the blocked
322 window.
323 </p>
324 <p>
325 <u>Blocked windows activations</u><br>
326 When the user selects a blocked window, it may be brought to the front, along
327 with the blocking modal dialog which would then become the active window&#151;
328 however, the actual behavior is unspecified and platform-dependent.
329 </p>
330 <p>
331 <u>Hiding a modal dialog</u><br>
332 When the modal dialog that currently has focus is hidden, it is unspecified
333 and platform-dependent, which other window will become the active window.
334 Any of the following may become the active window:
335 <ol>
336 <li>The owner of the modal dialog - if the owner is unblocked.
337 </li><li>The <code>Window</code>, which was active before this modal dialog gained
338 focus - if the owner of the modal dialog is absent or is blocked.
339 </li></ol>
340 If the modal dialog to be hidden does not have focus, the active window remains
341 unchanged.
342 </p>
343 <a name="Security"></a>
344 </p><h3>Security</h3>
345
346 <p>
347 A special <code>AWTPermission</code>, <code>"toolkitModality"</code>,
348 is required to show toolkit-modal
349 dialogs. This would prevent, for example, blocking a browser or
350 Java Web Start (JWS) by modal dialogs shown from applets.
351 </p><p>
352 The same permission is required to exclude a window from toolkit modality.
353 This would prevent, for example, a dialog shown from an applet not to be
354 blocked by a browser's or JWS's modal dialog.
355
356 <a name="PlatformSupport"></a>
357 </p><h3>Platform support</h3>
358
359 <p>
360 Two <code>java.awt.Toolkit</code> methods allow you to check whether
361 the current platform supports specific modality features:
362 </p><ul>
363 <li><code>isModalityTypeSupported(modalityType)</code><br>
364 Returns whether the specified modality type is supported on
365 the current platform.
366 If mode "M" is not supported and a dialog is set to M-modal,
367 it behaves as modeless.
368 </li>
369 <li><code>isModalExclusionTypeSupported(modalExclusionType)</code><br>
370 Returns whether the given modal exclusion type is supported on
371 the current platform. If exclusion type "E" is not supported
372 and a window is marked as E-excluded, this has no effect.
373 </li></ul>
374
375 <a name="Compatibility"></a>
376 <h3>Compatibility</h3>
377
378 <p>
379 The default modality type is application-modal. It is used by the API
380 calls: <code>Dialog.setModal(true)</code>,
381 <code>Dialog(owner, true)</code>, etc. Prior to JDK 6
382 the default type was toolkit-modal,
383 but the only distinction between application- and toolkit-modality is for
384 applets and applications launched from Java Web Start.
385
386 <a name="Examples"></a>
387 </p><h3>Examples</h3>
388
389 <table cols="2" border="0">
390 <tbody><tr>
391 <td align="left" valign="center">
392 <ol>
393 <li>Frame "F" is shown<br>
394 <li>Document-modal dialog "D<sub>i</sub>" is shown<br>
395 <li>F becomes blocked by D<sub>i</sub> &#151; it's in the same document<br>
396 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
397 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> &#151; it's in the
398 same document<br>
399 </ol>
400 <br>
401 </td>
402 <td align="center" valign="center">
403 <img src="modal-example1.gif">
404 <br>
405 </td>
406 </tr>
407 <tr>
408 <td align="left" valign="center">
409 <ol>
410 <li>Frame "F" is shown<br>
411 <li>Document-modal dialog "D<sub>i</sub>" is shown<br>
412 <li>F becomes blocked by D<sub>i</sub> &#151; it's in the same document<br>
413 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
414 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> &#151;
415 it's in the same document<br>
416 <li>D<sub>i</sub> is hidden<br>
417 <li>F becomes blocked by D<sub>ii</sub> &#151; it's in the same document<br>
418 </ol>
419 <br>
420 </td>
421 <td align="center">
422 <img src="modal-example2.gif">
423 <br>
424 </td>
425 </tr>
426 <tr>
427 <td align="left" valign="center">
428 <ol>
429 <li>Frame "F" is shown<br>
430 <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br>
431 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
432 <li>F becomes blocked by D<sub>ii</sub> &#151; it's in the same document<br>
433 <li>Application-modal dialog "D<sub>iii</sub>" is shown<br>
434 <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> &#151;
435 it's in the same application<br>
436 <li>D<sub>i</sub> is shown<br>
437 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> &#151; it's its owner<br>
438 <li>D<sub>iii</sub> remains unblocked &#151; it blocks D<sub>ii</sub> and
439 D<sub>ii</sub> blocks D<sub>i</sub><br>
440 </ol>
441 <br>
442 </td>
443 <td align="center" valign="center">
444 <img src="modal-example3.gif">
445 <br>
446 </td>
447 </tr>
448 <tr>
449 <td align="left" valign="center">
450 <ol>
451 <li>Frame "F" is shown<br>
452 <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br>
453 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br>
454 <li>F becomes blocked by D<sub>ii</sub> &#151; it's in the same document<br>
455 <li>Application-modal dialog "D<sub>iii</sub>" is shown<br>
456 <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> &#151; it's in the
457 same application<br>
458 <li>D<sub>i</sub> is shown<br>
459 <li>D<sub>iii</sub> becomes blocked by D<sub>i</sub> &#151; D<sub>i</sub>
460 is not blocked<br>
461 <li>D<sub>i</sub> remains unblocked<br>
462 </ol>
463 <br>
464 </td>
465 <td align="center" valign="center">
466 <img src="modal-example4.gif">
467 <br>
468 </td>
469 </tr>
470 </tbody></table>
471
472</body></html>