/*
* Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
1. Useful API:
XWindowPeer.isModalBlocked()
Checks if this window is blocked by any modal dialog
For common component peers use getToplevelXWindow().isModalBlocked()
XWindowPeer.setModalBlocked(Dialog blocker, boolean blocked)
Implementation of WindoePeer.setModalBlocked() method
Marks this window blocked/unblocked and adds/removes it
from transient_for chain (see below)
Don't call this method directly, it should be used from shared
code only
XWindowPeer.addToTransientFors()
XWindowPeer.removeFromTransientFors()
See below
2. Filtering mouse events
Mouse events are filtered in the shared code. See
java.awt.ModalFilter class for details
3. Filtering key events
Key events are filtering by preventing the blocked windows
to get native focus. All the AWT windows use global active focus
input model (see ICCCM for details) and listens to WM_TAKE_FOCUS
protocol. If the window manager asks AWT to set focus on the
blocked window, in XDecoratedPeer.handleWmTakeFocus() method we
set the focus to the window's blocker.
4. Z-order
According to the Modality spec any modal dialog should be always on
top of its blocked windows. It is implemented with using
WM_TRANSIENT_FOR hint.
WM_TRANSIENT_FOR is used to mark one window to be a child of another
one, in particular for any kind of dialogs. When a modal dialog
is shown it temporary becomes a child of all its blocked windows
and thus remains on top of them.
WM_TRANSIENT_FOR value is a single window, so we can't directly make
a dialog be a child of several other windows. It is implemented
as a "transient_for chain": all the blocked windows are arranged
into a chain, each next window is transient for the prev.
The chain is stored in XWindowPeer's fields 'prevTransientFor' and
'nextTransientFor'. If window is not blocked both of these fields
are set to null.
However, the value of WM_TRANSIENT_FOR hint and prevTransientFor
may differ sometimes. This happens when two windows are in
different window states, usually NormalState and IconifiedState.
Some window managers don't allow a dialog to be visible is its
parent window is iconified. The situation is even worse: we
don't receive any notifications when the dialog is iconified
together with its parent frame.
Thus we need to track all the window's state changes. Also, for
any window state (NormalState, IconifiedState, WithdrawnState)
a distinct chain is tracked. Below is a brief example.
Let's consider two frames F1 and F2 and two modeless dialogs D1
(with F1 as a parent) and D2 (F2). Their Z-order is:
F1 - D1 - F2 - D2 (D1 is above F1, F2 is above D1, etc). Then
a modal dialog D3 is shown and all these four windows become
blocked by it. Transient_for chain is constructed in the
following way: F1 - D2 - F2 - D2 - D3. Respectively, F2
temporarily becomes a child of D1 (WM_TRANSIENT_FOR hint is
set to F2 with a value of D1), etc.
Then F1 is iconified (some window managers allow this action).
F1.nextTransientFor and D1.prevTransientFor aren't changed,
however the values of WM_TRANSIENT_FOR hint for them are
changed: hint value for F1 is set to None, and hint value for
D1 is set to None.
Let's iconify another window, F2. prev/nextTransientFor field
values aren't changed again, but WM_TRANSIENT_FOR hint is:
the value for D2 is D1, the value for F2 is F1 (both are
iconified).
When either F1 or F2 is restored, the value for its hint is
restored according to the value stored in prevTransientFor
and nextTransientFor fields.
Note that some window managers don't allow iconifying for
those windows that are children of some other toplevel. That
is any dialog can't be iconified and any blocked window
that is not the first in the transient_for chain too.
All the updates of the hint's value is performed in the
XWindowPeer.setToplevelTransientFor() method.
5. Multiscreen
All the problems with WM_TRANSIENT_FOR hint and different
window states can be applied to different X screens (if
/**代码未完, 请加载全部代码(NowJava.com).**/