/* 

 * Copyright 2006 Sun Microsystems, Inc.  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.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.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

    Xinerama is off). For example, some window managers ignore

    the hint if window and transient_for window are on different

    screens.

  That leads to us to track a separate transient_for chain for

    every screen in the system, as well as for every window

    state. See XWindowPeer.updateTransientFor() for details.

6. See also

  Some examples how transient_for chain is constructed and

    destructed can be found in JavaDoc comments for the

    following methods: XWindowPeer.addToTransientFors(),

    XWindowPeer.removeFromTransientFors(),

    XWindowPeer.setToplevelTransientFor(),

    XWindowPeer.stateChanged().