This document outlines the API changes that have been done to AWT and Swing to accomodate the new focus model. For a general overview of the changes, you may want to first read this.
Modifications to existing classes:
New classes:
java.awt.AWTEvent:
/**
* Retargets an event to a new source. This method is typically used to
* retarget an event to a lightweight child Component of the original
* heavyweight source.
*
* This method is intended to be used only by event targeting subsystems,
* such as client-defined KeyboardFocusManagers. It is not for general
* client use.
*
* @param newSource the new Object to which the event should be dispatched
*/
public void setSource(Object newSource);
java.awt.Component:
/**
* Returns whether this Component can be focused.
*
* @return true if this Component is focusable;
* false otherwise.
* @see #setFocusable
* @since JDK1.1
* @deprecated As of 1.4, replaced by isFocusable
*/
public boolean isFocusTraversable();
/**
* Returns whether this Component can be focused.
*
* @return true if this Component is focusable;
* false otherwise.
* @see #setFocusable
* @since 1.4
*/
public boolean isFocusable();
/**
* Sets the focusable state of this Component to the specified value. This
* value overrides the Component's default focusability.
*
* @param focusable indicates whether this Component is focusable
* @see #isFocusable
* @since 1.4
* @beaninfo
* bound: true
*/
public void setFocusable(boolean focusable);
/**
* Sets the focus traversal keys for a given traversal operation for this
* Component.
*
* The default values for a Component's focus traversal keys are
* implementation-dependent. Sun recommends that all implementations for a
* particular native platform use the same default values. The
* recommendations for Windows and Unix are listed below. These
* recommendations are used in the Sun AWT implementations.
*
* <table border>
* <tr>
* <th>Identifier</th>
* <th>Meaning</th>
* <th>Default</th>
* </tr>
* <tr>
* <td>KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS</td>
* <td>Normal forward keyboard traversal</td>
* <td>TAB on KEY_PRESSED, CTRL-TAB on KEY_PRESSED</td>
* </tr>
* <tr>
* <td>KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS</td>
* <td>Normal reverse keyboard traversal</td>
* <td>SHIFT-TAB on KEY_PRESSED, CTRL-SHIFT-TAB on KEY_PRESSED</td>
* </tr>
* <tr>
* <td>KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS</td>
* <td>Go up one focus traversal cycle</td>
* <td>none</td>
* </tr>
* </table>
*
* To disable a traversal key, use an empty Set; Collections.EMPTY_SET is
* recommended.
*
* Using the AWTKeyStroke API, client code can specify on which of two
* specific KeyEvents, KEY_PRESSED or KEY_RELEASED, the focus traversal
* operation will occur. Regardless of which KeyEvent is specified,
* however, all KeyEvents related to the focus traversal key, including the
* associated KEY_TYPED event, will be consumed, and will not be dispatched
* to any Component. It is a runtime error to specify a KEY_TYPED event as
* mapping to a focus traversal operation, or to map the same event to
* multiple default focus traversal operations.
*
* If a value of null is specified for the Set, this Component inherits the
* Set from its parent. If all ancestors of this Component have null
* specified for the Set, then the current KeyboardFocusManager's default
* Set is used.
*
* @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
* @param keystrokes the Set of AWTKeyStroke for the specified operation
* @see #getFocusTraversalKeys
* @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
* @throws IllegalArgumentException if id is not one of
* KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or if keystrokes
* contains null, or if any Object in keystrokes is not an
* AWTKeyStroke, or if any keystroke represents a KEY_TYPED event,
* or if any keystroke already maps to another focus traversal
* operation for this Component
* @since 1.4
* @beaninfo
* bound: true
*/
public void setFocusTraversalKeys(int id, Set keystroke);
/**
* Returns the Set of focus traversal keys for a given traversal operation
* for this Component. (See
* setFocusTraversalKeys for a full description of each key.)
*
* If a Set of traversal keys has not been explicitly defined for this
* Component, then this Component's parent's Set is returned. If no Set
* has been explicitly defined for any of this Component's ancestors, then
* the current KeyboardFocusManager's default Set is returned.
*
* @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
* @return the Set of AWTKeyStrokes for the specified operation. The Set
* will be unmodifiable, and may be empty. null will never be
* returned.
* @see #setFocusTraversalKeys
* @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
* @throws IllegalArgumentException if id is not one of
* KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
* @since 1.4
*/
public Set getFocusTraversalKeys(int id);
/**
* Sets whether focus traversal keys are enabled for this Component.
* Components for which focus traversal keys are disabled receive key
* events for focus traversal keys. Components for which focus traversal
* keys are enabled do not see these events; instead, the events are
* automatically converted to traversal operations.
*
* @param focusTraversalKeysEnabled whether focus traversal keys are
* enabled for this Component
* @see #getFocusTraversalKeysEnabled
* @see #setFocusTraversalKeys
* @see #getFocusTraversalKeys
* @since 1.4
* @beaninfo
* bound: true
*/
public void setFocusTraversalKeysEnabled(boolean
focusTraversalKeysEnabled);
/**
* Returns whether focus traversal keys are enabled for this Component.
* Components for which focus traversal keys are disabled receive key
* events for focus traversal keys. Components for which focus traversal
* keys are enabled do not see these events; instead, the events are
* automatically converted to traversal operations.
*
* @return whether focus traversal keys are enabled for this Component
* @see #setFocusTraversalKeysEnabled
* @see #setFocusTraversalKeys
* @see #getFocusTraversalKeys
* @since 1.4
*/
public boolean getFocusTraversalKeysEnabled();
/**
* Requests that this Component get the input focus, and that this
* Component's top-level ancestor become the focused Window. This component
* must be displayable, visible, and focusable for the request to be
* granted. Every effort will be made to honor the request; however, in
* some cases it may be impossible to do so. Developers must never assume
* that this Component is the focus owner until this Component receives a
* FOCUS_GAINED event. If this request is denied because this Component's
* top-level Window cannot become the focused Window, the request will be
* remembered and will be granted when the Window is later focused by the
* user.
*
* This method cannot be used to set the focus owner to no Component at
* all. Use KeyboardFocusManager.clearGlobalFocusOwner()
* instead.
*
* Because the focus behavior of this method is platform-dependent,
* developers are strongly encouraged to use
* requestFocusInWindow when possible.
*
* @see #requestFocusInWindow
* @see java.awt.event.FocusEvent
* @see #addFocusListener
* @see #isFocusable
* @see #isDisplayable
* @see KeyboardFocusManager#clearGlobalFocusOwner
* @since JDK1.0
*/
public void requestFocus();
/**
* Requests that this Component get the input focus, and that this
* Component's top-level ancestor become the focused Window. This component
* must be displayable, visible, and focusable for the request to be
* granted. Every effort will be made to honor the request; however, in
* some cases it may be impossible to do so. Developers must never assume
* that this Component is the focus owner until this Component receives a
* FOCUS_GAINED event. If this request is denied because this Component's
* top-level Window cannot become the focused Window, the request will be
* remembered and will be granted when the Window is later focused by the
* user.
*
* This method returns a boolean value. If false is returned,
* the request is guaranteed to fail. If true is
* returned, the request will succeed unless it is vetoed, or an
* extraordinary event, such as disposal of the Component's peer, occurs
* before the request can be granted by the native windowing system. Again,
* while a return value of true indicates that the request is
* likely to succeed, developers must never assume that this Component is
* the focus owner until this Component receives a FOCUS_GAINED event.
*
* This method cannot be used to set the focus owner to no Component at
* all. Use KeyboardFocusManager.clearGlobalFocusOwner()
* instead.
*
* Because the focus behavior of this method is platform-dependent,
* developers are strongly encouraged to use
* requestFocusInWindow when possible.
*
* Every effort will be made to ensure that FocusEvents generated as a
* result of this request will have the specified temporary value. However,
* because specifying an arbitrary temporary state may not be implementable
* on all native windowing systems, correct behavior for this method can be
* guaranteed only for lightweight Components. This method is not intended
* for general use, but exists instead as a hook for lightweight Component
* libraries, such as Swing.
*
* @return false if the focus change request is guaranteed to
* fail; true if it is likely to succeed
* @see java.awt.event.FocusEvent
* @see #addFocusListener
* @see #isFocusable
* @see #isDisplayable
* @see KeyboardFocusManager#clearGlobalFocusOwner
* @since 1.4
*/
protected boolean requestFocus(boolean temporary);
/**
* Requests that this Component get the input focus, if this Component's
* top-level ancestor is already the focused Window. This component must be
* displayable, visible, and focusable for the request to be granted. Every
* effort will be made to honor the request; however, in some cases it may
* be impossible to do so. Developers must never assume that this Component
* is the focus owner until this Component receives a FOCUS_GAINED event.
*
* This method returns a boolean value. If false is returned,
* the request is guaranteed to fail. If true is
* returned, the request will succeed unless it is vetoed, or an
* extraordinary event, such as disposal of the Component's peer, occurs
* before the request can be granted by the native windowing system. Again,
* while a return value of true indicates that the request is
* likely to succeed, developers must never assume that this Component is
* the focus owner until this Component receives a FOCUS_GAINED event.
*
* This method cannot be used to set the focus owner to no Component at
* all. Use KeyboardFocusManager.clearGlobalFocusOwner()
* instead.
*
* The focus behavior of this method can be implemented uniformly across
* platforms, and thus developers are strongly encouraged to use this
* method over requestFocus when possible. Code which relies
* on requestFocus may exhibit different focus behavior on
* different platforms.
*
* @return false if the focus change request is guaranteed to
* fail; true if it is likely to succeed
* @see #requestFocus
* @see java.awt.event.FocusEvent
* @see #addFocusListener
* @see #isFocusable
* @see #isDisplayable
* @see KeyboardFocusManager#clearGlobalFocusOwner
* @since 1.4
*/
public boolean requestFocusInWindow();
/**
* Requests that this Component get the input focus, if this Component's
* top-level ancestor is already the focused Window. This component must be
* displayable, visible, and focusable for the request to be granted. Every
* effort will be made to honor the request; however, in some cases it may
* be impossible to do so. Developers must never assume that this Component
* is the focus owner until this Component receives a FOCUS_GAINED event.
*
* This method returns a boolean value. If false is returned,
* the request is guaranteed to fail. If true is
* returned, the request will succeed unless it is vetoed, or an
* extraordinary event, such as disposal of the Component's peer, occurs
* before the request can be granted by the native windowing system. Again,
* while a return value of true indicates that the request is
* likely to succeed, developers must never assume that this Component is
* the focus owner until this Component receives a FOCUS_GAINED event.
*
* This method cannot be used to set the focus owner to no Component at
* all. Use KeyboardFocusManager.clearGlobalFocusOwner()
* instead.
*
* The focus behavior of this method can be implemented uniformly across
* platforms, and thus developers are strongly encouraged to use this
* method over requestFocus when possible. Code which relies
* on requestFocus may exhibit different focus behavior on
* different platforms.
*
* Every effort will be made to ensure that FocusEvents generated as a
* result of this request will have the specified temporary value. However,
* because specifying an arbitrary temporary state may not be implementable
* on all native windowing systems, correct behavior for this method can be
* guaranteed only for lightweight Components. This method is not intended
* for general use, but exists instead as a hook for lightweight Component
* libraries, such as Swing.
*
* @return false if the focus change request is guaranteed to
* fail; true if it is likely to succeed
* @see #requestFocus
* @see java.awt.event.FocusEvent
* @see #addFocusListener
* @see #isFocusable
* @see #isDisplayable
* @see KeyboardFocusManager#clearGlobalFocusOwner
* @since 1.4
*/
protected boolean requestFocusInWindow(boolean temporary);
/**
* Transfers the focus to the next component, as though this Component were
* the focus owner.
* @see #requestFocus()
* @since JDK1.1
*/
public void transferFocus();
/**
* Transfers the focus to the previous component, as though this Component
* were the focus owner.
* @see #requestFocus()
* @since 1.4
*/
public void transferFocusBackward();
/**
* Transfers the focus up one focus traversal cycle. Typically, the focus
* owner is set to this Component's focus cycle root, and the current focus
* cycle root is set to the new focus owner's focus cycle root. If,
* however, this Component's focus cycle root is a Window, then the focus
* owner is set to the focus cycle root's default Component to focus, and
* the current focus cycle root is unchanged.
*
* @see #requestFocus()
* @see Container#isFocusCycleRoot()
* @see Container#setFocusCycleRoot()
* @since 1.4
*/
public void transferFocusUpCycle();
/**
* Returns the Container which is the focus cycle root of this Component's
* focus traversal cycle. Each focus traversal cycle has only a single
* focus cycle root and each Component which is not a Container belongs to
* only a single focus traversal cycle. Containers which are focus cycle
* roots belong to two cycles: one rooted at the Container itself, and one
* rooted at the Container's nearest focus-cycle-root ancestor. For such
* Containers, this method will return the Container's nearest focus-cycle-
* root ancestor.
*
* @return this Component's nearest focus-cycle-root ancestor
* @see Container#isFocusCycleRoot()
* @since 1.4
*/
public Container getFocusCycleRootAncestor();
/**
* Returns whether the specified Container is the focus cycle root of this
* Component's focus traversal cycle. Each focus traversal cycle has only
* a single focus cycle root and each Component which is not a Container
* belongs to only a single focus traversal cycle.
*
* @param container the Container to be tested
* @return true if the specified Container is a focus-cycle-
* root of this Component; false otherwise
* @see Container#isFocusCycleRoot()
* @since 1.4
*/
public boolean isFocusCycleRoot(Container container);
/**
* Returns true if this Component is the focus owner.
*
* @return true if this Component is the focus owner.
* @since 1.2
* @deprecated As of 1.4, replaced by isFocusOwner
*/
public boolean hasFocus();
/**
* Returns true if this Component is the focus owner.
*
* @return true if this Component is the focus owner.
* @since 1.4
*/
public boolean isFocusOwner();
/**
* Adds a PropertyChangeListener to the listener list. The listener is
* registered for all bound properties of this class, including the
* following:
* <ul>
* <li>this Component's font ("font")</li>
* <li>this Component's background color ("background")</li>
* <li>this Component's foreground color ("foreground")</li>
* <li>this Component's focusability ("focusable")</li>
* <li>this Component's focus traversal keys enabled state
* ("focusTraversalKeysEnabled")</li>
* <li>this Component's Set of FORWARD_TRAVERSAL_KEYS
* ("forwardFocusTraversalKeys")</li>
* <li>this Component's Set of BACKWARD_TRAVERSAL_KEYS
* ("backwardFocusTraversalKeys")</li>
* <li>this Component's Set of UP_CYCLE_TRAVERSAL_KEYS
* ("upCycleFocusTraversalKeys")</li>
* </ul>
* Note that if this Component is inheriting a bound property, then no
* event will be fired in response to a change in the inherited property.
*
* If listener is null, no exception is thrown and no action is performed.
*
* @param listener the PropertyChangeListener to be added
*
* @see #removePropertyChangeListener
* @see #addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
*/
public void addPropertyChangeListener(PropertyChangeListener listener);
/**
* Removes a PropertyChangeListener from the listener list. This method
* should be used to remove PropertyChangeListeners that were registered
* for all bound properties of this class.
*
* If listener is null, no exception is thrown and no action is performed.
*
* @param listener the PropertyChangeListener to be removed
*
* @see #addPropertyChangeListener
* @see #removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
*/
public void removePropertyChangeListener(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 Component's font ("font")</li>
* <li>this Component's background color ("background")</li>
* <li>this Component's foreground color ("foreground")</li>
* <li>this Component's focusability ("focusable")</li>
* <li>this Component's focus traversal keys enabled state
* ("focusTraversalKeysEnabled")</li>
* <li>this Component's Set of FORWARD_TRAVERSAL_KEYS
* ("forwardFocusTraversalKeys")</li>
* <li>this Component's Set of BACKWARD_TRAVERSAL_KEYS
* ("backwardFocusTraversalKeys")</li>
* <li>this Component's Set of UP_CYCLE_TRAVERSAL_KEYS
* ("upCycleFocusTraversalKeys")</li>
* </ul>
* Note that if this Component is inheriting a bound property, then no
* event will be fired in response to a change in the inherited property.
*
* 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 #removePropertyChangeListener
*/
public void addPropertyChangeListener(String propertyName,
PropertyChangeListener listener);
/**
* Removes a PropertyChangeListener from the listener list for a specific
* property. This method should be used to remove PropertyChangeListeners
* that were registered for a specific bound property.
*
* If listener is null, no exception is thrown and no action is performed.
*
* @param propertyName a valid property name
* @param listener the PropertyChangeListener to be removed
*
* @see #addPropertyChangeListener
* @see #removePropertyChangeListener(java.beans.PropertyChangeListener)
*/
public void removePropertyChangeListener(String propertyName,
PropertyChangeListener listener);
/**
* Support for reporting bound property changes for boolean properties.
* This method can be called when a bound property has changed and it will
* send the appropriate PropertyChangeEvent to any registered
* PropertyChangeListeners.
*
* @param propertyName the property whose value has changed
* @param oldValue the property's previous value
* @param newValue the property's new value
*/
public void firePropertyChange(String propertyName, boolean oldValue,
boolean newValue);
/**
* Support for reporting bound property changes for integer properties.
* This method can be called when a bound property has changed and it will
* send the appropriate PropertyChangeEvent to any registered
* PropertyChangeListeners.
*
* @param propertyName the property whose value has changed
* @param oldValue the property's previous value
* @param newValue the property's new value
*/
public void firePropertyChange(String propertyName, int oldValue,
int newValue);
/**
* Returns whether the font has been explicitly set for this Component. If
* this method returns false, this Component is inheriting its
* font from an ancestor.
*
* @return true if the font has been explicitly set for this
* Component; false otherwise.
* @since 1.4
*/
public boolean isFontSet();
/**
* Returns whether the background color has been explicitly set for this
* Component. If this method returns false, this Component is
* inheriting its background color from an ancestor.
*
* @return true if the background color has been explicitly
* set for this Component; false otherwise.
* @since 1.4
*/
public boolean isBackgroundSet();
/**
* Returns whether the foreground color has been explicitly set for this
* Component. If this method returns false, this Component is
* inheriting its foreground color from an ancestor.
*
* @return true if the foreground color has been explicitly
* set for this Component; false otherwise.
* @since 1.4
*/
public boolean isForegroundSet();
/**
* Returns whether the cursor has been explicitly set for this Component.
* If this method returns false, this Component is inheriting
* its cursor from an ancestor.
*
* @return true if the cursor has been explicitly set for this
* Component; false otherwise.
* @since 1.4
*/
public boolean isCursorSet();
/**
* Returns whether the Set of focus traversal keys for the given focus
* traversal operation has been explicitly defined for this Component. If
* this method returns false, this Component is inheriting the
* Set from an ancestor, or from the current KeyboardFocusManager.
*
* @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
* @return true if the the Set of focus traversal keys for the
* given focus traversal operation has been explicitly defined for
* this Component; false otherwise.
* @throws IllegalArgumentException if id is not one of
* KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
* @since 1.4
*/
public boolean areFocusTraversalKeysSet(int id);
java.awt.Container:
/**
* Sets the focus traversal keys for a given traversal operation for this
* Container.
*
* The default values for a Container's focus traversal keys are
* implementation-dependent. Sun recommends that all implementations for a
* particular native platform use the same default values. The
* recommendations for Windows and Unix are listed below. These
* recommendations are used in the Sun AWT implementations.
*
* <table border>
* <tr>
* <th>Identifier</th>
* <th>Meaning</th>
* <th>Default</th>
* </tr>
* <tr>
* <td>KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS</td>
* <td>Normal forward keyboard traversal</td>
* <td>TAB on KEY_PRESSED, CTRL-TAB on KEY_PRESSED</td>
* </tr>
* <tr>
* <td>KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS</td>
* <td>Normal reverse keyboard traversal</td>
* <td>SHIFT-TAB on KEY_PRESSED, CTRL-SHIFT-TAB on KEY_PRESSED</td>
* </tr>
* <tr>
* <td>KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS</td>
* <td>Go up one focus traversal cycle</td>
* <td>none</td>
* </tr>
* <tr>
* <td>KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS<td>
* <td>Go down one focus traversal cycle</td>
* <td>none</td>
* </tr>
* </table>
*
* To disable a traversal key, use an empty Set; Collections.EMPTY_SET is
* recommended.
*
* Using the AWTKeyStroke API, client code can specify on which of two
* specific KeyEvents, KEY_PRESSED or KEY_RELEASED, the focus traversal
* operation will occur. Regardless of which KeyEvent is specified,
* however, all KeyEvents related to the focus traversal key, including the
* associated KEY_TYPED event, will be consumed, and will not be dispatched
* to any Container. It is a runtime error to specify a KEY_TYPED event as
* mapping to a focus traversal operation, or to map the same event to
* multiple default focus traversal operations.
*
* If a value of null is specified for the Set, this Container inherits the
* Set from its parent. If all ancestors of this Container have null
* specified for the Set, then the current KeyboardFocusManager's default
* Set is used.
*
* @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
* KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
* @param keystrokes the Set of AWTKeyStroke for the specified operation
* @see #getFocusTraversalKeys
* @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
* @see KeyboardFocusManager#DOWN_CYCLE_TRAVERSAL_KEYS
* @throws IllegalArgumentException if id is not one of
* KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
* KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS, or if keystrokes
* contains null, or if any Object in keystrokes is not an
* AWTKeyStroke, or if any keystroke represents a KEY_TYPED event,
* or if any keystroke already maps to another focus traversal
* operation for this Container
* @since 1.4
* @beaninfo
* bound: true
*/
public void setFocusTraversalKeys(int id, Set keystroke);
/**
* Returns the Set of focus traversal keys for a given traversal operation
* for this Container. (See
* setFocusTraversalKeys for a full description of each key.)
*
* If a Set of traversal keys has not been explicitly defined for this
* Container, then this Container's parent's Set is returned. If no Set
* has been explicitly defined for any of this Container's ancestors, then
* the current KeyboardFocusManager's default Set is returned.
*
* @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
* KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
* @return the Set of AWTKeyStrokes for the specified operation. The Set
* will be unmodifiable, and may be empty. null will never be
* returned.
* @see #setFocusTraversalKeys
* @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
* @see KeyboardFocusManager#DOWN_CYCLE_TRAVERSAL_KEYS
* @throws IllegalArgumentException if id is not one of
* KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
* KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
* @since 1.4
*/
public Set getFocusTraversalKeys(int id);
/**
* Sets the focus traversal policy that will manage keyboard traversal of
* this Container's children, if this Container is a focus cycle root. If
* the argument is null, this Container inherits its policy from its focus-
* cycle-root ancestor. If all such ancestors of this Container have null
* policies, then the current KeyboardFocusManager's default policy is
* used. If the argument is non-null, this policy will be inherited by all
* focus-cycle-root children that have no keyboard-traversal policy of
* their own (as will, recursively, their focus-cycle-root children).
*
* If this Container is not a focus cycle root, the policy will be
* remembered, but will not be used or inherited by this or any other
* Containers until this Container is made a focus cycle root.
*
* @param policy the new focus traversal policy for this Container
* @see #getFocusTraversalPolicy
* @see #setFocusCycleRoot
* @see #isFocusCycleRoot
* @since 1.4
* @beaninfo
* bound: true
*/
public void setFocusTraversalPolicy(FocusTraversalPolicy policy);
/**
* Returns the focus traversal policy that will manage keyboard traversal
* of this Container's children, or null if this Container is not a focus
* cycle root. If no traversal policy has been explicitly set for this
* Container, then this Container's focus-cycle-root ancestor's policy is
* returned. If no traversal policy has been explicitly set for any focus-
* cycle-root ancestors of this Container, then the current
* KeyboardFocusManager's default policy is returned.
*
* @return this Container's focus traversal policy, or null if this
* Container is not a focus cycle root.
* @see #setFocusTraversalPolicy
* @see #setFocusCycleRoot
* @see #isFocusCycleRoot
* @since 1.4
*/
public FocusTraversalPolicy getFocusTraversalPolicy();
/**
* Sets whether this Container is the root of a focus traversal cycle. Once
* focus enters a traversal cycle, typically it cannot leave it via focus
* traversal unless one of the up- or down-cycle keys is pressed. Normal
* traversal is limited to this Container, and all of this Container's
* descendants that are not descendants of inferior focus cycle roots. Note
* that a FocusTraversalPolicy may bend these restrictions, however. For
* example, ContainerOrderFocusTraversalPolicy supports implicit down-cycle
* traversal.
*
* @param focusCycleRoot indicates whether this Container is the root of a
* focus traversal cycle
* @see #isFocusCycleRoot()
* @see #setFocusTraversalPolicy
* @see #getFocusTraversalPolicy
* @see ContainerOrderFocusTraversalPolicy
* @since 1.4
* @beaninfo
* bound: true
*/
public void setFocusCycleRoot(boolean focusCycleRoot);
/**
* Returns whether this Container is the root of a focus traversal cycle.
* Once focus enters a traversal cycle, typically it cannot leave it via
* focus traversal unless one of the up- or down-cycle keys is pressed.
* Normal traversal is limited to this Container, and all of this
* Container's descendants that are not descendants of inferior focus
* cycle roots. Note that a FocusTraversalPolicy may bend these
* restrictions, however. For example, ContainerOrderFocusTraversalPolicy
* supports implicit down-cycle traversal.
*
* @return whether this Container is the root of a focus traversal cycle
* @see #setFocusCycleRoot
* @see #setFocusTraversalPolicy
* @see #getFocusTraversalPolicy
* @see ContainerOrderFocusTraversalPolicy
* @since 1.4
*/
public boolean isFocusCycleRoot();
/**
* Returns whether the specified Container is the focus cycle root of this
* Container's focus traversal cycle. Each focus traversal cycle has only
* a single focus cycle root and each Container which is not a focus cycle
* root belongs to only a single focus traversal cycle. Containers which
* are focus cycle roots belong to two cycles: one rooted at the Container
* itself, and one rooted at the Container's nearest focus-cycle-root
* ancestor. This method will return true for both such
* Containers in this case.
*
* @param container the Container to be tested
* @return true if the specified Container is a focus-cycle-
* root of this Container; false otherwise
* @see #isFocusCycleRoot()
* @since 1.4
*/
public boolean isFocusCycleRoot(Container container);
/**
* Transfers the focus down one focus traversal cycle. If this Container is
* a focus cycle root, then the focus owner is set to this Container's
* default Component to focus, and the current focus cycle root is set to
* this Container. If this Container is not a focus cycle root, then no
* focus traversal operation occurs.
*
* @see Component#requestFocus()
* @see #isFocusCycleRoot
* @see #setFocusCycleRoot
* @since 1.4
*/
public void transferFocusDownCycle();
/**
* Adds a PropertyChangeListener to the listener list. The listener is
* registered for all bound properties of this class, including the
* following:
* <ul>
* <li>this Container's font ("font")</li>
* <li>this Container's background color ("background")</li>
* <li>this Container's foreground color ("foreground")</li>
* <li>this Container's focusability ("focusable")</li>
* <li>this Container's focus traversal keys enabled state
* ("focusTraversalKeysEnabled")</li>
* <li>this Container's Set of FORWARD_TRAVERSAL_KEYS
* ("forwardFocusTraversalKeys")</li>
* <li>this Container's Set of BACKWARD_TRAVERSAL_KEYS
* ("backwardFocusTraversalKeys")</li>
* <li>this Container's Set of UP_CYCLE_TRAVERSAL_KEYS
* ("upCycleFocusTraversalKeys")</li>
* <li>this Container's Set of DOWN_CYCLE_TRAVERSAL_KEYS
* ("downCycleFocusTraversalKeys")</li>
* <li>this Container's focus traversal policy ("focusTraversalPolicy")
* </li>
* <li>this Container's focus-cycle-root state ("focusCycleRoot")</li>
* </ul>
* Note that if this Container is inheriting a bound property, then no
* event will be fired in response to a change in the inherited property.
*
* 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 defaults:
* <ul>
* <li>this Container's font ("font")</li>
* <li>this Container's background color ("background")</li>
* <li>this Container's foreground color ("foreground")</li>
* <li>this Container's focusability ("focusable")</li>
* <li>this Container's focus traversal keys enabled state
* ("focusTraversalKeysEnabled")</li>
* <li>this Container's Set of FORWARD_TRAVERSAL_KEYS
* ("forwardFocusTraversalKeys")</li>
* <li>this Container's Set of BACKWARD_TRAVERSAL_KEYS
* ("backwardFocusTraversalKeys")</li>
* <li>this Container's Set of UP_CYCLE_TRAVERSAL_KEYS
* ("upCycleFocusTraversalKeys")</li>
* <li>this Container's Set of DOWN_CYCLE_TRAVERSAL_KEYS
* ("downCycleFocusTraversalKeys")</li>
* <li>this Container's focus traversal policy ("focusTraversalPolicy")
* </li>
* <li>this Container's focus-cycle-root state ("focusCycleRoot")</li>
* </ul>
* Note that if this Container is inheriting a bound property, then no
* event will be fired in response to a change in the inherited property.
*
* 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);
/**
* Returns whether the Set of focus traversal keys for the given focus
* traversal operation has been explicitly defined for this Container. If
* this method returns false, this Container is inheriting the
* Set from an ancestor, or from the current KeyboardFocusManager.
*
* @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
* KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
* @return true if the the Set of focus traversal keys for the
* given focus traversal operation has been explicitly defined for
* this Component; false otherwise.
* @throws IllegalArgumentException if id is not one of
* KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
* KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
* @since 1.4
*/
public boolean areFocusTraversalKeysSet(int id);
/**
* Returns whether the focus traversal policy has been explicitly set for
* this Container. If this method returns false, this
* Container will inherit its focus traversal policy from an ancestor, or
* from the current KeyboardFocusManager.
*
* @return true if the focus traversal policy has been
* explicitly set for this Container; false otherwise.
* @since 1.4
*/
public boolean isFocusTraversalPolicySet();
java.awt.Window:
/**
* If this Window is visible, brings this Window to the front and may make
* it the focused Window.
*
* Places this Window at the top of the stacking order and shows it in
* front of any other Windows in this VM. No action will take place is this
* Window is not visible. Some platforms do not allow Windows which own
* other Windows to appear on top of those owned Windows. Some platforms
* may not permit this VM to place its Windows above windows of native
* applications, or Windows of other VMs. This permission may depend on
* whether a Window in this VM is already focused. Every attempt will be
* made to move this Window as high as possible in the stacking order;
* however, developers should not assume that this method will move this
* Window above all other windows in every situation.
*
* Because of variations in native windowing systems, no guarantees about
* changes to the focused and active Windows can be made. Developers must
* never assume that this Window is the focused or active Window until this
* Window receives a WINDOW_GAINED_FOCUS or WINDOW_ACTIVATED event. On
* platforms where the top-most window is the focused window, this method
* will probably focus this Window, if it is not already focused. On
* platforms where the stacking order does not typically affect the focused
* window, this method will probably leave the focused and active
* Windows unchanged.
*
* If this method causes this Window to be focused, and this Window is a
* Frame or a Dialog, it will also become activated. If this Window is
* focused, but it is not a Frame or a Dialog, then the first Frame or
* Dialog that is an owner of this Window will be activated.
*
* @see #toBack
*/
public void toFront();
/**
* If this Window is visible, sends this Window to the back and may cause
* it to lose focus or activation if it is the focused or active Window.
*
* Places this Window at the bottom of the stacking order and shows it
* behind any other Windows in this VM. No action will take place is this
* Window is not visible. Some platforms do not allow Windows which are
* owned by other Windows to appear below their owners. Every attempt will
* be made to move this Window as low as possible in the stacking order;
* however, developers should not assume that this method will move this
* Window below all other windows in every situation.
*
* Because of variations in native windowing systems, no guarantees about
* changes to the focused and active Windows can be made. Developers must
* never assume that this Window is no longer the focused or active Window
* until this Window receives a WINDOW_LOST_FOCUS or WINDOW_DEACTIVATED
* event. On platforms where the top-most window is the focused window,
* this method will probably cause this Window to lose focus. In
* that case, the next highest, focusable Window in this VM will receive
* focus. On platforms where the stacking order does not typically affect
* the focused window, this method will probably leave the focused
* and active Windows unchanged.
*
* @see #toFront
*/
public void toBack();
/**
* Returns the child Component of this Window that has focus if this Window
* is focused; returns null otherwise.
*
* @return the child Component with focus, or null if this Window is not
* focused.
* @see #getMostRecentFocusOwner
* @see #isFocused
*/
public Component getFocusOwner();
/**
* Returns the child Component of this Window that will receive the focus
* when this Window is focused. If this Window is currently focused, this
* method returns the same Component as getFocusOwner(). If
* this Window is not focused, then the child Component that most recently
* requested focus will be returned. If no child Component has ever
* requested focus, and this is a focusable Window, then this Window's
* initial focusable Component is returned. If no child Component has ever
* requested focus, and this is a non-focusable Window, null is returned.
*
* @return the child Component that will receive focus when this Window is
* focused
* @see #getFocusOwner
* @see #isFocused
* @see #isFocusableWindow
* @since 1.4
*/
public Component getMostRecentFocusOwner();
/**
* Returns whether this Window is active. Only a Frame or a Dialog may be
* active. The native windowing system may denote the active Window or its
* children with special decorations, such as a highlighted title bar. The
* active Window is always either the focused Window, or the first Frame or
* Dialog that is an owner of the focused Window.
*
* @return whether this is the active Window.
* @see #isFocused
* @since 1.4
*/
public boolean isActive();
/**
* Returns whether this Window is focused. If there exists a focus owner,
* the focused Window is the Window that is, or contains, that focus owner.
* If there is no focus owner, then no Window is focused.
*
* If the focused Window is a Frame or a Dialog it is also the active
* Window. Otherwise, the active Window is the first Frame or Dialog that
* is an owner of the focused Window.
*
* @return whether this is the focused Window.
* @see #isActive
* @since 1.4
*/
public boolean isFocused();
/**
* Does nothing because Windows must always be roots of a focus traversal
* cycle. The passed-in value is ignored.
*
* @param focusCycleRoot this value is ignored
* @see #isFocusCycleRoot
* @see Container#setFocusTraversalPolicy
* @see Container#getFocusTraversalPolicy
* @since 1.4
*/
public final void setFocusCycleRoot(boolean focusCycleRoot);
/**
* Always returns true because all Windows must be roots of a
* focus traversal cycle.
*
* @return true
* @see #setFocusCycleRoot
* @see Container#setFocusTraversalPolicy
* @see Container#getFocusTraversalPolicy
* @since 1.4
*/
public final boolean isFocusCycleRoot();
/**
* Always returns null because Windows have no ancestors; they
* represent the top of the Component hierarchy.
*
* @return null
* @see Container#isFocusCycleRoot()
* @since 1.4
*/
public final Container getFocusCycleRootAncestor();
/**
* 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 false, neither this Window
* nor any of its subcomponents can become the focus owner. By default, all
* Windows are focusable.
*
* @return true if this Window can be the focused Window;
* false otherwise.
* @see #setFocusableWindow
* @see Component#isFocusable
* @since 1.4
*/
public boolean isFocusableWindow();
/**
* Sets 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 false, neither this Window nor any of
* its subcomponents can become the focus owner. By default, all Windows
* are focusable.
*
* @return true if this Window can be the focused Window;
* false otherwise.
* @see #isFocusableWindow
* @see Component#setFocusable
* @since 1.4
*/
public void setFocusableWindow(boolean focusableWindow);
/**
* 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.
*
* 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.
*
* 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);
java.awt.Frame:/** * Frames are capable of generating the following types of WindowEvents: * WindowOpened, WindowClosing, WindowClosed, WindowIconified, * WindowDeiconified, WindowActivated, WindowDeactivated, WindowGainedFocus, * WindowLostFocus. */
java.awt.Dialog:/** * Dialogs are capable of generating the following WindowEvents: * WindowOpened, WindowClosing, WindowClosed, WindowActivated, * WindowDeactivated, WindowGainedFocus, WindowLostFocus. */
java.awt.event.FocusEvent:
/**
* Constructs a FocusEvent object with the specified temporary state and
* opposite Component. The opposite Component is the other Component
* involved in this focus change. For a FOCUS_GAINED event, this is the
* Component that lost focus. For a FOCUS_LOST event, this is the Component
* that gained focus. If this focus change occurs with a native
* application, with a Java application in a different VM, or with no other
* Component, then the opposite Component is null.
*
* @param source the Component that originated the event
* @param id FOCUS_GAINED or FOCUS_LOST
* @param temporary true if the focus change is temporary;
* false otherwise
* @param opposite the other Component involved in the focus change,
* or null
*/
public FocusEvent(Component source, int id, boolean temporary,
Component opposite);
/**
* Returns the other Component involved in this focus change. For a
* FOCUS_GAINED event, this is the Component that lost focus. For a
* FOCUS_LOST event, this is the Component that gained focus. If this
* focus change occurs with a native application, with a Java application
* in a different VM or context, or with no other Component, then null is
* returned.
*
* @return the other Component involved in the focus change, or null
* @since 1.4
*/
public Component getOppositeComponent();
java.awt.event.WindowEvent:/** * A low-level event that indicates that a window has changed its status. This * low-level event is generated by a Window object when it is opened, closed, * activated, deactivated, iconified, or deiconified, or when focus is * transfered into or out of the Window. */
java.awt.event.WindowEvent:
/**
* The window-activated event type. This event is delivered when the Window
* becomes the active Window. Only a Frame or a Dialog can be the active
* Window. The native windowing system may denote the active Window or its
* children with special decorations, such as a highlighted title bar. The
* active Window is always either the focused Window, or the first Frame or
* Dialog that is an owner of the focused Window.
*/
public static final int WINDOW_ACTIVATED;
/**
* The window-deactivated event type. This event is delivered when the
* Window is no longer the active Window. Only a Frame or a Dialog can be
* the active Window. The native windowing system may denote the active
* Window or its children with special decorations, such as a highlighted
* title bar. The active Window is always either the focused Window, or the
* first Frame or Dialog that is an owner of the focused Window.
*/
public static final int WINDOW_DEACTIVATED;
/**
* The window-gained-focus event type. This event is delivered when the
* Window becomes the focused Window, which means that the Window, or one
* of its subcomponents, will receive keyboard events.
*/
public static final int WINDOW_GAINED_FOCUS;
/**
* The window-lost-focus event type. This event is delivered when a Window
* is no longer the focused Window, which means keyboard events will no
* longer be delivered to the Window or any of its subcomponents.
*/
public static final int WINDOW_LOST_FOCUS;
/**
* Constructs a WindowEvent object with the specified opposite Window. The
* opposite Window is the other Window involved in this focus or activation
* change. For a WINDOW_ACTIVATED or WINDOW_GAINED_FOCUS event, this is the
* Window that lost activation or focus. For a WINDOW_DEACTIVATED or
* WINDOW_LOST_FOCUS event, this is the Window that gained activation or
* focus. If this focus change occurs with a native application, with a
* Java application in a different VM, or with no other Window, then the
* opposite Window is null.
*
* @param source the Window object that originated the event
* @param id WINDOW_ACTIVATED, WINDOW_DEACTIVATED,
* WINDOW_GAINED_FOCUS, or WINDOW_LOST_FOCUS. It is
* expected that this constructor will not be used for
* other WindowEvent types because the opposite Window of
* such events will always be null.
* @param opposite the other Window involved in the focus or activation
* change, or null
*/
public WindowEvent(Window source, int id, Window opposite);
/**
* Returns the other Window involved in this focus or activation change.
* For a WINDOW_ACTIVATED or WINDOW_GAINED_FOCUS event, this is the Window
* that lost activation or focus. For a WINDOW_DEACTIVATED or
* WINDOW_LOST_FOCUS event, this is the Window that gained activation or
* focus. For any other type of WindowEvent, or if the focus or activation
* change occurs with a native application, with a Java application in a
* different VM or context, or with no other Window, null is returned.
*
* @return the other Window involved in the focus or activation change, or
* null
* @since 1.4
*/
public Window getOppositeWindow();
java.awt.event.WindowListener:
/**
* Invoked when the Window is set to be the active Window. Only a Frame or
* a Dialog can be the active Window. The native windowing system may
* denote the active Window or its children with special decorations, such
* as a highlighted title bar. The active Window is always either the
* focused Window, or the first Frame or Dialog that is an owner of the
* focused Window.
*/
public void windowActivated(WindowEvent e);
/**
* Invoked when a Window is no longer the active Window. Only a Frame or a
* Dialog can be the active Window. The native windowing system may denote
* the active Window or its children with special decorations, such as a
* highlighted title bar. The active Window is always either the focused
* Window, or the first Frame or Dialog that is an owner of the focused
* Window.
*/
public void windowDeactivated(WindowEvent e);
class
java.awt.event.WindowAdapter:
/**
* Invoked when the Window is set to be the focused Window, which means
* that the Window, or one of its subcomponents, will receive keyboard
* events.
*
* @since 1.4
*/
public void windowGainedFocus(WindowEvent e);
/**
* Invoked when the Window is no longer the focused Window, which means
* that keyboard events will no longer be delivered to the Window or any of
* its subcomponents.
*
* @since 1.4
*/
public void windowLostFocus(WindowEvent e);
class
java.awt.event.AWTEventMulticaster:
/**
* Handles the windowGainedFocus event by invoking the windowGainedFocus
* methods on listener-a and listener-b.
* @param e the window event
*/
public void windowGainedFocus(WindowEvent e);
/**
* Handles the windowLostFocus event by invoking the windowLostFocus
* methods on listener-a and listener-b.
* @param e the window event
*/
public void windowLostFocus(WindowEvent e);
class
java.awt.peer.ComponentPeer:
boolean isFocusTraversable();
void requestFocus();
java.awt.peer.ComponentPeer:
boolean isFocusable();
boolean requestFocus(boolean temporary,
boolean focusedWindowChangeAllowed);
java.awt.peer.WindowPeer:
int handleFocusTraversalEvent(KeyEvent e); /* REMOVED */
public final static int IGNORE_EVENT = 0; /* REMOVED */
public final static int CONSUME_EVENT = 1; /* REMOVED */
public final static int FOCUS_NEXT = 2; /* REMOVED */
public final static int FOCUS_PREVIOUS = 3; /* REMOVED */
javax.swing.FocusManager
This class has been obsoleted. New applications should use
java.awt.KeyboardFocusManager
exclusively. Nevertheless, we have preserved backward
compatibility for existing applications (but not applets) which
define their own FocusManager.
The Swing FocusManager has been changed to be a
subclass of the new, AWT
KeyboardFocusManager.
FocusManager.setCurrentManager(FocusManager)
and FocusManager.getCurrentManager() have been
changed to wrappers around
KeyboardFocusManager.setCurrentKeyboardFocusManager(KeyboardFocusManager) and
KeyboardFocusManager.getCurrentKeyboardFocusManager(), respectively.
There was much discussion over these changes because
KeyboardFocusManager.setCurrentKeyboardFocusManager(KeyboardFocusManager)
will throw a SecurityException if the calling
thread was not granted the
"replaceKeyboardFocusManager"
permission. Previously,
FocusManager.setCurrentManager(FocusManager) would
never throw a SecurityException. Although we were
able to design a convoluted class organization which avoided
this problem, we felt that the elegance and simplicity of the
proposed design outweighed the rather small backward
compatibility concern.
disableSwingFocusManager() and
isFocusManagerEnabled() have been
deprecated. Disabling the Swing FocusManager now has the
semantics of reverting the default
FocusTraversalPolicy from the Swing default of
javax.swing.LayoutFocusTraversalPolicy to the AWT
default of java.awt.DefaultFocusTraversalPolicy.
javax.swing.DefaultFocusManager
This class has been obsoleted. New applications should use
java.awt.KeyboardFocusManager
exclusively. Nevertheless, we have preserved backward
compatibility for existing applications (but not applets) which
define their own DefaultFocusManager.
If client code installs a legacy
DefaultFocusManager, we provide backward
compatibility by installing a non-public
LegacyGlueFocusTraversalPolicy which routes
FocusTraversalPolicy method invocations to the
corresponding methods on DefaultFocusManager.
javax.swing.JComponent
isManagingFocus: This method has been
deprecated. Its primary problem was that it tried to do too many
things and ended up doing none of them well. It changed a
JComponent's focus traversal keys from
TAB and SHIFT-TAB to CTRL-TAB and CTRL-SHIFT-TAB. It also marked
the JComponent in such a way that focus traversal
would not automatically enter the JComponent. This
was similar to, but different from, marking a
JComponent as a focus cycle root. Its functionality
is superseded by the FocusTraversalPolicy class,
per-Component focus traversal keys, and the ability
to disable a Component's focus traversal keys en
masse.
setNextFocusableComponent/getNextFocusableComponents:
These methods have been
deprecated. FocusTraversalPolicies are more
reliable because they allow an algorithmic expression of focus
traversal. These methods force applications to hard-code focus
traversal Component by Component.
setRequestFocusEnabled/isRequestFocusEnabled: These
methods have been deprecated. They are now equivalent to
setFocusable/isFocusable, which provide a tighter
specification of when a Component with this
property set to 'false' can become the focus owner.
requestDefaultFocus: This method has been
deprecated. Its functionality is superseded by
FocusTraversalPolicy.getDefaultComponent(Container).requestFocus().
javax.swing.JWindow
setFocusableWindow/isFocusableWindow: These methods
are declared final in JWindow to enforce the
restriction that all JWindows constructed with a
'null' owner must be non-focusable. This restriction is
necessary because Swing constructs such JWindows so
that they are owned by a private, hidden Frame, and
the new focus implementation requires that
KeyEvents intended for a Window or its
descendants be proxied through that Frame. Since
X11 requires a window to be mapped in order to be
focused, a JWindow with a 'null' owner could never
receive KeyEvents on X11.
javax.swing.JInternalFrame
getMostRecentFocusOwner: Like
java.awt.Window, JInternalFrame has a
getFocusOwner() method left over from before
centralization of focus management in
java.awt.KeyboardFocusManager. To round out the
API, and to remain consistent with Window,
getMostRecentFocusOwner() has been added to
JInternalFrame with the same specification as the
corresponding method on Window.
setFocusCycleRoot/isFocusCycleRoot: These methods
give JInternalFrames similar semantics to top-level
Windows in AWT. Since a JInternalFrame
must always be a focus cycle root, these methods are overridden and
declared final to enforce that restriction. However, unlike an AWT
Window, a JInternalFrame can have a
focus-cycle-root ancestor, such as a
JDesktopPane. Thus,
Component.getFocusCycleRootAncestor() is not
declared final in JInternalFrame as it is in
Window.
javax.swing.KeyStroke
Because the existing KeyStroke class was useful for
designing per-Component focus traversal key APIs,
this class was promoted with minor modifications to AWT as
java.awt.AWTKeyStroke. The Swing class is now a
subclass of the AWT class.
The one deprecated method in KeyStroke,
getKeyStroke(char, boolean), was not promoted to
AWT. Because of this, there is no simple way for this method to
participate in the standard AWTKeyStroke caching
scheme. The specification of this method has been changed to
note that implementations need not cache the instances returned
by this method.
javax.swing.SwingUtilities
findFocusOwner: This method has been
deprecated. Its functionality is superseded by
KeyboardFocusManager.getFocusOwner().