|
1 <!-- |
|
2 Copyright (c) 2005, 2013, 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 </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 — 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 <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 <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 — 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> |
|
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 — 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 — |
|
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"> |
|
216 <caption>The Standard Blocking Matrix</caption> |
|
217 <tbody><tr align="center"> |
|
218 <td align="center">current/shown</td> |
|
219 <td align="center">frame & 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 </blockquote> |
|
297 |
|
298 <a name="Related"></a> |
|
299 <h3>Related AWT features</h3> |
|
300 |
|
301 <p> |
|
302 <u>Always-On-Top</u><br> |
|
303 When a modal dialog that is not always-on-top blocks an always-on-top window, |
|
304 their relative Z-order is unspecified and platform-dependent. |
|
305 </p> |
|
306 <p> |
|
307 <u>The <code>toFront()</code> and <code>toBack()</code> methods</u><br> |
|
308 A modal dialog should always be above all its blocked windows. Thus, if a blocked |
|
309 window is brought to the front, its blocking dialog, if any, is also brought to the |
|
310 front and remains above the blocked window. Likewise, if a modal dialog is sent to |
|
311 the back, all of its blocked windows are sent to the back to keep them below the |
|
312 blocking dialog. |
|
313 </p> |
|
314 <p> |
|
315 <u>Minimizing, maximizing and closing blocked windows</u><br> |
|
316 When a modal dialog blocks a window, the user may not be able to maximize or |
|
317 minimize the blocked window— however, the actual behavior is unspecified |
|
318 and platform-dependent. In any case, the user can't close the blocked window |
|
319 interactively— but it can be closed programmatically by calling the |
|
320 <code>setVisible(false)</code> or <code>dispose()</code> methods on the blocked |
|
321 window. |
|
322 </p> |
|
323 <p> |
|
324 <u>Blocked windows activations</u><br> |
|
325 When the user selects a blocked window, it may be brought to the front, along |
|
326 with the blocking modal dialog which would then become the active window— |
|
327 however, the actual behavior is unspecified and platform-dependent. |
|
328 </p> |
|
329 <p> |
|
330 <u>Hiding a modal dialog</u><br> |
|
331 When the modal dialog that currently has focus is hidden, it is unspecified |
|
332 and platform-dependent, which other window will become the active window. |
|
333 Any of the following may become the active window: |
|
334 <ol> |
|
335 <li>The owner of the modal dialog - if the owner is unblocked. |
|
336 </li><li>The <code>Window</code>, which was active before this modal dialog gained |
|
337 focus - if the owner of the modal dialog is absent or is blocked. |
|
338 </li></ol> |
|
339 If the modal dialog to be hidden does not have focus, the active window remains |
|
340 unchanged. |
|
341 |
|
342 <a name="Security"></a> |
|
343 <h3>Security</h3> |
|
344 |
|
345 <p> |
|
346 A special <code>AWTPermission</code>, <code>"toolkitModality"</code>, |
|
347 is required to show toolkit-modal |
|
348 dialogs. This would prevent, for example, blocking a browser or |
|
349 Java Web Start (JWS) by modal dialogs shown from applets. |
|
350 </p><p> |
|
351 The same permission is required to exclude a window from toolkit modality. |
|
352 This would prevent, for example, a dialog shown from an applet not to be |
|
353 blocked by a browser's or JWS's modal dialog. |
|
354 |
|
355 <a name="PlatformSupport"></a> |
|
356 </p><h3>Platform support</h3> |
|
357 |
|
358 <p> |
|
359 Two <code>java.awt.Toolkit</code> methods allow you to check whether |
|
360 the current platform supports specific modality features: |
|
361 </p><ul> |
|
362 <li><code>isModalityTypeSupported(modalityType)</code><br> |
|
363 Returns whether the specified modality type is supported on |
|
364 the current platform. |
|
365 If mode "M" is not supported and a dialog is set to M-modal, |
|
366 it behaves as modeless. |
|
367 </li> |
|
368 <li><code>isModalExclusionTypeSupported(modalExclusionType)</code><br> |
|
369 Returns whether the given modal exclusion type is supported on |
|
370 the current platform. If exclusion type "E" is not supported |
|
371 and a window is marked as E-excluded, this has no effect. |
|
372 </li></ul> |
|
373 |
|
374 <a name="Compatibility"></a> |
|
375 <h3>Compatibility</h3> |
|
376 |
|
377 <p> |
|
378 The default modality type is application-modal. It is used by the API |
|
379 calls: <code>Dialog.setModal(true)</code>, |
|
380 <code>Dialog(owner, true)</code>, etc. Prior to JDK 6 |
|
381 the default type was toolkit-modal, |
|
382 but the only distinction between application- and toolkit-modality is for |
|
383 applets and applications launched from Java Web Start. |
|
384 |
|
385 <a name="Examples"></a> |
|
386 </p><h3>Examples</h3> |
|
387 |
|
388 <table border="0"> |
|
389 <tbody><tr> |
|
390 <td align="left" > |
|
391 <ol> |
|
392 <li>Frame "F" is shown<br> |
|
393 <li>Document-modal dialog "D<sub>i</sub>" is shown<br> |
|
394 <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br> |
|
395 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br> |
|
396 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — it's in the |
|
397 same document<br> |
|
398 </ol> |
|
399 <br> |
|
400 </td> |
|
401 <td align="center"> |
|
402 <img src="modal-example1.gif"> |
|
403 <br> |
|
404 </td> |
|
405 </tr> |
|
406 <tr> |
|
407 <td align="left"> |
|
408 <ol> |
|
409 <li>Frame "F" is shown<br> |
|
410 <li>Document-modal dialog "D<sub>i</sub>" is shown<br> |
|
411 <li>F becomes blocked by D<sub>i</sub> — it's in the same document<br> |
|
412 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br> |
|
413 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — |
|
414 it's in the same document<br> |
|
415 <li>D<sub>i</sub> is hidden<br> |
|
416 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br> |
|
417 </ol> |
|
418 <br> |
|
419 </td> |
|
420 <td align="center"> |
|
421 <img src="modal-example2.gif"> |
|
422 <br> |
|
423 </td> |
|
424 </tr> |
|
425 <tr> |
|
426 <td align="left"> |
|
427 <ol> |
|
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> — |
|
434 it's in the same application<br> |
|
435 <li>D<sub>i</sub> is shown<br> |
|
436 <li>D<sub>i</sub> becomes blocked by D<sub>ii</sub> — it's its owner<br> |
|
437 <li>D<sub>iii</sub> remains unblocked — it blocks D<sub>ii</sub> and |
|
438 D<sub>ii</sub> blocks D<sub>i</sub><br> |
|
439 </ol> |
|
440 <br> |
|
441 </td> |
|
442 <td align="center"> |
|
443 <img src="modal-example3.gif"> |
|
444 <br> |
|
445 </td> |
|
446 </tr> |
|
447 <tr> |
|
448 <td align="left"> |
|
449 <ol> |
|
450 <li>Frame "F" is shown<br> |
|
451 <li>Toolkit-modal dialog "D<sub>i</sub>" is created, but not shown<br> |
|
452 <li>Document-modal dialog "D<sub>ii</sub>" is shown<br> |
|
453 <li>F becomes blocked by D<sub>ii</sub> — it's in the same document<br> |
|
454 <li>Application-modal dialog "D<sub>iii</sub>" is shown<br> |
|
455 <li>D<sub>ii</sub> becomes blocked by D<sub>iii</sub> — it's in the |
|
456 same application<br> |
|
457 <li>D<sub>i</sub> is shown<br> |
|
458 <li>D<sub>iii</sub> becomes blocked by D<sub>i</sub> — D<sub>i</sub> |
|
459 is not blocked<br> |
|
460 <li>D<sub>i</sub> remains unblocked<br> |
|
461 </ol> |
|
462 <br> |
|
463 </td> |
|
464 <td align="center"> |
|
465 <img src="modal-example4.gif"> |
|
466 <br> |
|
467 </td> |
|
468 </tr> |
|
469 </tbody></table> |
|
470 |
|
471 </body></html> |