*
     * @return whether this Window can be the focused Window
     * @see #isFocusableWindow
     * @see #setFocusableWindowState
     * @see #isShowing
     * @see Component#setFocusable
     * @since 1.4
     */
    public boolean getFocusableWindowState();

    /**
     * Sets whether this Window can become the focused Window if its nearest
     * owning Frame or Dialog is showing on the screen. If this Window's
     * focusable Window state is set to <code>true</code>, then
     * <code>isFocusableWindow</code> will return <code>true</code> if this
     * Window's nearest owning Frame or Dialog is showing on the screen. If
     * this Window's focusable Window state is set to <code>false</code>, then
     * <code>isFocusableWindow</code> will return <code>false</code>.
     *
     * @param focusableWindowState whether this Window can be the focused
     * Window
     * @see #isFocusableWindow
     * @see #getFocusableWindowState
     * @see #isShowing
     * @see Component#setFocusable
     * @since 1.4
     */
    public void setFocusableWindowState(boolean focusableWindowState);


Remove the following methods from javax.swing.JWindow:

    public final boolean isFocusableWindow();
    public final void setFocusableWindow(boolean focusableWindow);


Modifications to the AWT Focus Specification:

< To support palette windows and input methods, client code can prevent
< a Window from becoming the focused Window. By transitivity, this
< prevents the Window or any of its descendants from becoming the focus
< owner. Non-focusable Windows may still own Windows that are
< focusable. By default, all Windows are focusable. To make a Window
< non-focusable, use Window.setFocusableWindow(boolean).

To support palette windows and input methods, client code can prevent
a Window from becoming the focused Window. By transitivity, this
prevents the Window or any of its descendants from becoming the focus
owner. Non-focusable Windows may still own Windows that are
focusable. By default, every Window is focusable if its nearest owning
Frame or Dialog is showing on the screen. To make a Window
non-focusable, use Window.setFocusableWindowState(false).

< A Swing JWindow with a null owner must be a non-focusable Window. This
< restriction is necessary because Swing constructs all such JWindows so
< that they are owned by a private, hidden Frame. Because the new focus
< implementation requires that KeyEvents intended for a Window or its
< descendants be proxied through a child of the Window's owner, and
< because this proxy must be mapped on X11 in order to receive events, a
< JWindow with a null owner could never receive KeyEvents on X11
< anyways.

Because the new focus implementation requires that KeyEvents intended
for a Window or its descendants be proxied through a child of the
Window's owner, and because this proxy must be mapped on X11 in order
to receive events, a Window whose nearest owning Frame or Dialog is
not showing could never receive KeyEvents on X11. To support this
restriction, we have made a distinction between a Window's "window
focusability" and its "window focusability state". A Window's
focusability state is combined with the showing state of the Window's
nearest owning Frame or Dialog to determine the Window's focusability.
By default, all Windows have a focusability state of true. Setting a
Window's focusability state to false ensures that it will not become
the focused Window regardless of the showing state of its nearest
owning Frame or Dialog.

Swing allows applications to create JWindows with null owners. Swing
constructs all such JWindows so that they are owned by a private,
hidden Frame. Because the showing state of this Frame will always be
false, a JWindow constructed will a null owner can never be the
focused Window, even if it has a Window focusability state of true.


API reviewed and approved by:

Hania Gajewska


Implementation:
   - Engineer who made (or will make) the changes: David Mendenhall
   - Date at which changes will be complete: Immediately
   - Number of lines of new or modified code:
        + Java: TBD
        + Native: None.
   - Code reviewed (or will be reviewed) by: Hania Gajewska


Risk assessment:

Very low. Minor and self-contained changes in shared Java code
only. The methods which are being removed, or whose specifications
have been substantially altered, are new in Merlin. There is no
compatibility concern with the changes to those methods.


SQE (product testing) impact:

TBD


JCK (compatibility testing) impact:

TBD


Doc impact:

javadoc and Focus Specification changes only.


Localization impact:

None.


Internationalization impact:

None.


Security impact:

None.


Legal impact:

None.


For feature changes, Product Marketing approval:

N/A
Release: merlin

Problem: (BugID 4420896)
  Windows cannot be focusable when owning Frame or Dialog is not showing

The Focus Management Enhancements project for Merlin (RFE 4290675)
introduced an API that, for the first time, allowed focusable children
of a java.awt.Window (or javax.swing.JWindow) to receive KeyEvents
reliably. Previously, delivery of KeyEvents to such children was
problematic, if not impossible.

The implementation underlying this new API creates a focus proxy on
the Window's nearest owning Frame or Dialog. While the Java
application, and indeed even the peer architecture, believe that the
Java focus owner directly receives all KeyEvents from the native
windowing system, in fact, these KeyEvents are first sent to the focus
proxy and later retargeted to the true focus owner. This allows the AWT
to dispatch KeyEvents to focusable children of a Window without making
that Window active from a native perspective. This was necessary to
remain fully backward-compatible with the Ladybird, Kestrel, and
earlier implementations.

Unfortunately, X11 requires that the focus proxy be "mapped" in order
to receive KeyEvents. This roughly means that the proxy must be
visible on the screen. (It could, in fact, have a position off the
screen so that even though it is visible, the user cannot see it
because it is clipped by the edge of the display.) This restriction
was not encompassed into the API when it was first designed. The API
needs to be updated to reflect that a Window might not be focusable
unless its nearest owning Frame or Dialog (which contains the focus
proxy) is showing on the screen. While we could note that this
behavior is platform-dependent and remove the restriction on Win32
and potentially other platforms, we would prefer to remain consistent
across platforms in this case. In particular, introducing platform-
specific behavior into Swing's JWindow class seems to violate the
bedrock principle of Swing: create a cross-platform toolkit that does
not suffer from the platform inconsistencies of the AWT peer
architecture.


Requesters:

AWT Core (David Mendenhall)


Proposed API change:

Add the '>>' noted clauses to the specifications of the following existing
constructors of java.awt.Window:
    /**
     * Constructs a new invisible window with the specified
>> * Frame as its owner. The Window will not be focusable unless its owner
>> * is showing on the screen.
     * <p>
     * If there is a security manager, this method first calls
     * the security manager's <code>checkTopLevelWindow</code>
     * method with <code>this</code>
     * as its argument to determine whether or not the window
     * must be displayed with a warning banner.
     *
     * @param owner the <code>Frame</code> to act as owner
     * @exception IllegalArgumentException if <code>gc</code>
     * is not from a screen device.
     * @exception java.lang.IllegalArgumentException if
     * <code>owner</code> is <code>null</code>. This exception
     * is always thrown when GraphicsEnvironment.isHeadless()
     * returns true.
     * @see java.awt.GraphicsEnvironment#isHeadless
     * @see java.lang.SecurityManager#checkTopLevelWindow
>> * @see #isShowing
     */
    public Window(Frame owner);

    /**
     * Constructs a new invisible window with the specified
>> * Window as its owner. The Window will not be focusable unless its nearest
>> * owning Frame or Dialog is showing on the screen.
     * <p>
     * If there is a security manager, this method first calls
     * the security manager's <code>checkTopLevelWindow</code>
     * method with <code>this</code>
     * as its argument to determine whether or not the window
     * must be displayed with a warning banner.
     *
     * @param owner the Window to act as owner
     * @exception java.lang.IllegalArgumentException if <code>owner</code>
     * is <code>null</code>. This exception is always thrown
     * when GraphicsEnvironment.isHeadless() returns true.
     * @see java.awt.GraphicsEnvironment#isHeadless
     * @see java.lang.SecurityManager#checkTopLevelWindow
>> * @see #isShowing
     * @since 1.2
     */
    public Window(Window owner);

    /**
     * Constructs a new invisible window with the specified
     * window as its owner and a
>> * <code>GraphicsConfiguration</code> of a screen device. The Window will
>> * not be focusable unless its nearest owning Frame or Dialog is showing on
>> * the screen.
     * <p>
     * If there is a security manager, this method first calls
     * the security manager's <code>checkTopLevelWindow</code>
     * method with <code>this</code>
     * as its argument to determine whether or not the window
     * must be displayed with a warning banner.
     * @param owner the window to act as owner
     * @param gc the <code>GraphicsConfiguration</code>
     * of the target screen device. If <code>gc</code> is
     * <code>null</code>, the system default
     * <code>GraphicsConfiguration</code> is assumed.
     * @throws IllegalArgumentException if
     * <code>owner</code> is <code>null</code>.
     * @throws IllegalArgumentException if <code>gc</code> is not from
     * a screen device. This exception is always thrown when
     * GraphicsEnvironment.isHeadless() returns true.
     * @see java.awt.GraphicsEnvironment#isHeadless
     * @see java.lang.SecurityManager#checkTopLevelWindow
     * @see GraphicsConfiguration#getBounds
>> * @see #isShowing
     * @since 1.3
     */
    public Window(Window owner, GraphicsConfiguration gc);


Change the '<<' noted clauses as follows:

    /**
     * Adds a PropertyChangeListener to the listener list. The listener is
     * registered for all bound properties of this class, including the
     * following:
     * <ul>
     * <li>this Window's font ("font")</li>
     * <li>this Window's background color ("background")</li>
     * <li>this Window's foreground color ("foreground")</li>
     * <li>this Window's focusability ("focusable")</li>
     * <li>this Window's focus traversal keys enabled state
     * ("focusTraversalKeysEnabled")</li>
     * <li>this Window's Set of FORWARD_TRAVERSAL_KEYS
     * ("forwardFocusTraversalKeys")</li>
     * <li>this Window's Set of BACKWARD_TRAVERSAL_KEYS
     * ("backwardFocusTraversalKeys")</li>
     * <li>this Window's Set of UP_CYCLE_TRAVERSAL_KEYS
     * ("upCycleFocusTraversalKeys")</li>
     * <li>this Window's Set of DOWN_CYCLE_TRAVERSAL_KEYS
     * ("downCycleFocusTraversalKeys")</li>
     * <li>this Window's focus traversal policy ("focusTraversalPolicy")
     * </li>
<< * <li>this Window's focusable Window state ("focusableWindow")</li>
     * </ul>
     * Note that if this Window is inheriting a bound property, then no
     * event will be fired in response to a change in the inherited property.
     * <p>
     * If listener is null, no exception is thrown and no action is performed.
     *
     * @param listener the PropertyChangeListener to be added
     *
     * @see Component#removePropertyChangeListener
     * @see #addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
     */
    public void addPropertyChangeListener(PropertyChangeListener listener);

    /**
     * Adds a PropertyChangeListener to the listener list. The listener is
     * registered for all bound properties of this class, including the
     * following:
     * <ul>
     * <li>this Window's font ("font")</li>
     * <li>this Window's background color ("background")</li>
     * <li>this Window's foreground color ("foreground")</li>
     * <li>this Window's focusability ("focusable")</li>
     * <li>this Window's focus traversal keys enabled state
     * ("focusTraversalKeysEnabled")</li>
     * <li>this Window's Set of FORWARD_TRAVERSAL_KEYS
     * ("forwardFocusTraversalKeys")</li>
     * <li>this Window's Set of BACKWARD_TRAVERSAL_KEYS
     * ("backwardFocusTraversalKeys")</li>
     * <li>this Window's Set of UP_CYCLE_TRAVERSAL_KEYS
     * ("upCycleFocusTraversalKeys")</li>
     * <li>this Window's Set of DOWN_CYCLE_TRAVERSAL_KEYS
     * ("downCycleFocusTraversalKeys")</li>
     * <li>this Window's focus traversal policy ("focusTraversalPolicy")
     * </li>
>> * <li>this Window's focusable Window state ("focusableWindowState")
>> * </li>
     * </ul>
     * Note that if this Window is inheriting a bound property, then no
     * event will be fired in response to a change in the inherited property.
     * <p>
     * If listener is null, no exception is thrown and no action is performed.
     *
     * @param listener the PropertyChangeListener to be added
     *
     * @see Component#removePropertyChangeListener
     * @see #addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
     */

    public void addPropertyChangeListener(PropertyChangeListener listener);

    /**
     * Adds a PropertyChangeListener to the listener list for a specific
     * property. The specified property may be user-defined, or one of the
     * following:
     * <ul>
     * <li>this Window's font ("font")</li>
     * <li>this Window's background color ("background")</li>
     * <li>this Window's foreground color ("foreground")</li>
     * <li>this Window's focusability ("focusable")</li>
     * <li>this Window's focus traversal keys enabled state
     * ("focusTraversalKeysEnabled")</li>
     * <li>this Window's Set of FORWARD_TRAVERSAL_KEYS
     * ("forwardFocusTraversalKeys")</li>
     * <li>this Window's Set of BACKWARD_TRAVERSAL_KEYS
     * ("backwardFocusTraversalKeys")</li>
     * <li>this Window's Set of UP_CYCLE_TRAVERSAL_KEYS
     * ("upCycleFocusTraversalKeys")</li>
     * <li>this Window's Set of DOWN_CYCLE_TRAVERSAL_KEYS
     * ("downCycleFocusTraversalKeys")</li>
     * <li>this Window's focus traversal policy ("focusTraversalPolicy")
     * </li>
<< * <li>this Window's focusable Window state ("focusableWindow")</li>
     * </ul>
     * Note that if this Window is inheriting a bound property, then no
     * event will be fired in response to a change in the inherited property.
     * <p>
     * If listener is null, no exception is thrown and no action is performed.
     *
     * @param propertyName one of the property names listed above
     * @param listener the PropertyChangeListener to be added
     *
     * @see #addPropertyChangeListener(java.beans.PropertyChangeListener)
     * @see Component#removePropertyChangeListener
     */
    public void addPropertyChangeListener(String propertyName,
                                          PropertyChangeListener listener);

    /**
     * Adds a PropertyChangeListener to the listener list for a specific
     * property. The specified property may be user-defined, or one of the
     * following:
     * <ul>
     * <li>this Window's font ("font")</li>
     * <li>this Window's background color ("background")</li>
     * <li>this Window's foreground color ("foreground")</li>
     * <li>this Window's focusability ("focusable")</li>
     * <li>this Window's focus traversal keys enabled state
     * ("focusTraversalKeysEnabled")</li>
     * <li>this Window's Set of FORWARD_TRAVERSAL_KEYS
     * ("forwardFocusTraversalKeys")</li>
     * <li>this Window's Set of BACKWARD_TRAVERSAL_KEYS
     * ("backwardFocusTraversalKeys")</li>
     * <li>this Window's Set of UP_CYCLE_TRAVERSAL_KEYS
     * ("upCycleFocusTraversalKeys")</li>
     * <li>this Window's Set of DOWN_CYCLE_TRAVERSAL_KEYS
     * ("downCycleFocusTraversalKeys")</li>
     * <li>this Window's focus traversal policy ("focusTraversalPolicy")
     * </li>
>> * <li>this Window's focusable Window state ("focusableWindowState")
>> * </li>
     * </ul>
     * Note that if this Window is inheriting a bound property, then no
     * event will be fired in response to a change in the inherited property.
     * <p>
     * If listener is null, no exception is thrown and no action is performed.
     *
     * @param propertyName one of the property names listed above
     * @param listener the PropertyChangeListener to be added
     *
     * @see #addPropertyChangeListener(java.beans.PropertyChangeListener)
     * @see Component#removePropertyChangeListener
     */
    public void addPropertyChangeListener(String propertyName,
                                          PropertyChangeListener listener);


Replace the specification of Window.isFocusableWindow as follows:

<< /**
<< * Returns whether this Window can become the focused Window, that is,
<< * whether this Window or any of its subcomponents can become the focus
<< * owner. If this method returns <code>false</code>, neither this Window
<< * nor any of its subcomponents can become the focus owner. By default, all
<< * Windows are focusable.
<< *
<< * @return <code>true</code> if this Window can be the focused Window;
<< * <code>false</code> otherwise.
<< * @see #setFocusableWindow
<< * @see Component#isFocusable
<< * @since 1.4
<< */
<< public boolean isFocusableWindow();

>> /**
>> * Returns whether this Window can become the focused Window, that is,
>> * whether this Window or any of its subcomponents can become the focus
>> * owner. For a Window to be focusable, its focusable Window state must be
>> * set to <code>true</code> and its nearest owning Frame or Dialog must be
>> * showing on the screen. If either of these conditions is not met, then
>> * neither this Window nor any of its subcomponents can become the focus
>> * owner.
>> *
>> * @return <code>true</code> if this Window can be the focused Window;
>> * <code>false</code> otherwise
>> * @see #getFocusableWindowState
>> * @see #setFocusableWindowState
>> * @see #isShowing
>> * @see Component#isFocusable
>> * @since 1.4
>> */
>> public final boolean isFocusableWindow(); /* changed from non-final */


Remove the following method from java.awt.Window:

    public void setFocusableWindow(boolean);


Add the following methods to java.awt.Window:

    /**
     * Returns whether this Window can become the focused Window if its nearest
     * owning Frame or Dialog is showing on the screen. If this method returns
     * <code>true</code>, then <code>isFocusableWindow</code> will return
     * <code>true</code> if this Window's nearest owning Frame or Dialog is
     * showing on the screen. If this method returns <code>false</code>, then
     * <code>isFocusableWindow</code> will return <code>false</code> as well.
     * By default, all Windows have a focusable Window state of
     * <code>true</code>.