Java tutorial
/* * Copyright (c) 1996, 2016, 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. */ package java.awt.event; import java.awt.Component; import java.io.ObjectStreamException; import sun.awt.AWTAccessor; import sun.awt.AppContext; import sun.awt.SunToolkit; /** * A low-level event which indicates that a Component has gained or lost the * input focus. This low-level event is generated by a Component (such as a * TextField). The event is passed to every {@code FocusListener} or * {@code FocusAdapter} object which registered to receive such events * using the Component's {@code addFocusListener} method. * ({@code FocusAdapter} objects implement the {@code FocusListener} * interface.) Each such listener object gets this {@code FocusEvent} when * the event occurs. * <p> * There are two levels of focus events: permanent and temporary. Permanent * focus change events occur when focus is directly moved from one Component to * another, such as through a call to requestFocus() or as the user uses the * TAB key to traverse Components. Temporary focus change events occur when * focus is temporarily lost for a Component as the indirect result of another * operation, such as Window deactivation or a Scrollbar drag. In this case, * the original focus state will automatically be restored once that operation * is finished, or, for the case of Window deactivation, when the Window is * reactivated. Both permanent and temporary focus events are delivered using * the FOCUS_GAINED and FOCUS_LOST event ids; the level may be distinguished in * the event using the isTemporary() method. * <p> * Every {@code FocusEvent} records its cause - the reason why this event was * generated. The cause is assigned during the focus event creation and may be * retrieved by calling {@link #getCause}. * <p> * An unspecified behavior will be caused if the {@code id} parameter * of any particular {@code FocusEvent} instance is not * in the range from {@code FOCUS_FIRST} to {@code FOCUS_LAST}. * * @see FocusAdapter * @see FocusListener * @see <a href="https://docs.oracle.com/javase/tutorial/uiswing/events/focuslistener.html">Tutorial: Writing a Focus Listener</a> * * @author Carl Quinn * @author Amy Fowler * @since 1.1 */ public class FocusEvent extends ComponentEvent { /** * This enum represents the cause of a {@code FocusEvent}- the reason why it * occurred. Possible reasons include mouse events, keyboard focus * traversal, window activation. * If no cause is provided then the reason is {@code UNKNOWN}. * * @since 9 */ public enum Cause { /** * The default value. */ UNKNOWN, /** * An activating mouse event. */ MOUSE_EVENT, /** * A focus traversal action with unspecified direction. */ TRAVERSAL, /** * An up-cycle focus traversal action. */ TRAVERSAL_UP, /** * A down-cycle focus traversal action. */ TRAVERSAL_DOWN, /** * A forward focus traversal action. */ TRAVERSAL_FORWARD, /** * A backward focus traversal action. */ TRAVERSAL_BACKWARD, /** * Restoring focus after a focus request has been rejected. */ ROLLBACK, /** * A system action causing an unexpected focus change. */ UNEXPECTED, /** * An activation of a toplevel window. */ ACTIVATION, /** * Clearing global focus owner. */ CLEAR_GLOBAL_FOCUS_OWNER } /** * The first number in the range of ids used for focus events. */ public static final int FOCUS_FIRST = 1004; /** * The last number in the range of ids used for focus events. */ public static final int FOCUS_LAST = 1005; /** * This event indicates that the Component is now the focus owner. */ public static final int FOCUS_GAINED = FOCUS_FIRST; //Event.GOT_FOCUS /** * This event indicates that the Component is no longer the focus owner. */ public static final int FOCUS_LOST = 1 + FOCUS_FIRST; //Event.LOST_FOCUS /** * A focus event has the reason why this event was generated. * The cause is set during the focus event creation. * * @serial * @see #getCause() * @since 9 */ private final Cause cause; /** * A focus event can have two different levels, permanent and temporary. * It will be set to true if some operation takes away the focus * temporarily and intends on getting it back once the event is completed. * Otherwise it will be set to false. * * @serial * @see #isTemporary */ boolean temporary; /** * 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, a Java application in a different VM, or with * no other Component, then the opposite Component is null. * * @see #getOppositeComponent * @since 1.4 */ transient Component opposite; /* * JDK 1.1 serialVersionUID */ private static final long serialVersionUID = 523753786457416396L; /** * Constructs a {@code FocusEvent} object with the * specified temporary state, opposite {@code Component} and the * {@code Cause.UNKNOWN} cause. * The opposite {@code Component} is the other * {@code Component} involved in this focus change. * For a {@code FOCUS_GAINED} event, this is the * {@code Component} that lost focus. For a * {@code FOCUS_LOST} event, this is the {@code 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 {@code Component}, then the opposite * {@code Component} is {@code null}. * <p> This method throws an * {@code IllegalArgumentException} if {@code source} * is {@code null}. * * @param source The {@code Component} that originated the event * @param id An integer indicating the type of event. * For information on allowable values, see * the class description for {@link FocusEvent} * @param temporary Equals {@code true} if the focus change is temporary; * {@code false} otherwise * @param opposite The other Component involved in the focus change, * or {@code null} * @throws IllegalArgumentException if {@code source} equals {@code null} * @see #getSource() * @see #getID() * @see #isTemporary() * @see #getOppositeComponent() * @see Cause#UNKNOWN * @since 1.4 */ public FocusEvent(Component source, int id, boolean temporary, Component opposite) { this(source, id, temporary, opposite, Cause.UNKNOWN); } /** * Constructs a {@code FocusEvent} object with the * specified temporary state, opposite {@code Component} and the cause. * The opposite {@code Component} is the other * {@code Component} involved in this focus change. * For a {@code FOCUS_GAINED} event, this is the * {@code Component} that lost focus. For a * {@code FOCUS_LOST} event, this is the {@code 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 {@code Component}, then the opposite * {@code Component} is {@code null}. * <p> This method throws an * {@code IllegalArgumentException} if {@code source} or {@code cause} * is {@code null}. * * @param source The {@code Component} that originated the event * @param id An integer indicating the type of event. * For information on allowable values, see * the class description for {@link FocusEvent} * @param temporary Equals {@code true} if the focus change is temporary; * {@code false} otherwise * @param opposite The other Component involved in the focus change, * or {@code null} * @param cause The focus event cause. * @throws IllegalArgumentException if {@code source} equals {@code null} * or if {@code cause} equals {@code null} * @see #getSource() * @see #getID() * @see #isTemporary() * @see #getOppositeComponent() * @see Cause * @since 9 */ public FocusEvent(Component source, int id, boolean temporary, Component opposite, Cause cause) { super(source, id); if (cause == null) { throw new IllegalArgumentException("null cause"); } this.temporary = temporary; this.opposite = opposite; this.cause = cause; } /** * Constructs a {@code FocusEvent} object and identifies * whether or not the change is temporary. * <p> This method throws an * {@code IllegalArgumentException} if {@code source} * is {@code null}. * * @param source The {@code Component} that originated the event * @param id An integer indicating the type of event. * For information on allowable values, see * the class description for {@link FocusEvent} * @param temporary Equals {@code true} if the focus change is temporary; * {@code false} otherwise * @throws IllegalArgumentException if {@code source} equals {@code null} * @see #getSource() * @see #getID() * @see #isTemporary() */ public FocusEvent(Component source, int id, boolean temporary) { this(source, id, temporary, null); } /** * Constructs a {@code FocusEvent} object and identifies it * as a permanent change in focus. * <p> This method throws an * {@code IllegalArgumentException} if {@code source} * is {@code null}. * * @param source The {@code Component} that originated the event * @param id An integer indicating the type of event. * For information on allowable values, see * the class description for {@link FocusEvent} * @throws IllegalArgumentException if {@code source} equals {@code null} * @see #getSource() * @see #getID() */ public FocusEvent(Component source, int id) { this(source, id, false); } /** * Identifies the focus change event as temporary or permanent. * * @return {@code true} if the focus change is temporary; * {@code false} otherwise */ public boolean isTemporary() { return temporary; } /** * 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() { if (opposite == null) { return null; } return (SunToolkit.targetToAppContext(opposite) == AppContext.getAppContext()) ? opposite : null; } /** * Returns a parameter string identifying this event. * This method is useful for event-logging and for debugging. * * @return a string identifying the event and its attributes */ public String paramString() { String typeStr; switch (id) { case FOCUS_GAINED: typeStr = "FOCUS_GAINED"; break; case FOCUS_LOST: typeStr = "FOCUS_LOST"; break; default: typeStr = "unknown type"; } return typeStr + (temporary ? ",temporary" : ",permanent") + ",opposite=" + getOppositeComponent() + ",cause=" + getCause(); } /** * Returns the event cause. * * @return one of {@link Cause} values * @since 9 */ public final Cause getCause() { return cause; } /** * Checks if this deserialized {@code FocusEvent} instance is compatible * with the current specification which implies that focus event has * non-null {@code cause} value. If the check fails a new {@code FocusEvent} * instance is returned which {@code cause} field equals to * {@link Cause#UNKNOWN} and its other fields have the same values as in * this {@code FocusEvent} instance. * * @serial * @see #cause * @since 9 */ @SuppressWarnings("serial") Object readResolve() throws ObjectStreamException { if (cause != null) { return this; } FocusEvent focusEvent = new FocusEvent(new Component() { }, getID(), isTemporary(), getOppositeComponent()); focusEvent.setSource(null); focusEvent.consumed = consumed; AWTAccessor.AWTEventAccessor accessor = AWTAccessor.getAWTEventAccessor(); accessor.setBData(focusEvent, accessor.getBData(this)); return focusEvent; } }