1 /* 2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.awt.event; 27 28 import java.awt.Component; 29 import sun.awt.AppContext; 30 import sun.awt.SunToolkit; 31 32 /** 33 * A low-level event which indicates that a Component has gained or lost the 34 * input focus. This low-level event is generated by a Component (such as a 35 * TextField). The event is passed to every <code>FocusListener</code> or 36 * <code>FocusAdapter</code> object which registered to receive such events 37 * using the Component's <code>addFocusListener</code> method. (<code> 38 * FocusAdapter</code> objects implement the <code>FocusListener</code> 39 * interface.) Each such listener object gets this <code>FocusEvent</code> when 40 * the event occurs. 41 * <p> 42 * There are two levels of focus events: permanent and temporary. Permanent 43 * focus change events occur when focus is directly moved from one Component to 44 * another, such as through a call to requestFocus() or as the user uses the 45 * TAB key to traverse Components. Temporary focus change events occur when 46 * focus is temporarily lost for a Component as the indirect result of another 47 * operation, such as Window deactivation or a Scrollbar drag. In this case, 48 * the original focus state will automatically be restored once that operation 49 * is finished, or, for the case of Window deactivation, when the Window is 50 * reactivated. Both permanent and temporary focus events are delivered using 51 * the FOCUS_GAINED and FOCUS_LOST event ids; the level may be distinguished in 52 * the event using the isTemporary() method. 53 * <p> 54 * An unspecified behavior will be caused if the {@code id} parameter 55 * of any particular {@code FocusEvent} instance is not 56 * in the range from {@code FOCUS_FIRST} to {@code FOCUS_LAST}. 57 * 58 * @see FocusAdapter 59 * @see FocusListener 60 * @see <a href="https://docs.oracle.com/javase/tutorial/uiswing/events/focuslistener.html">Tutorial: Writing a Focus Listener</a> 61 * 62 * @author Carl Quinn 63 * @author Amy Fowler 64 * @since 1.1 65 */ 66 public class FocusEvent extends ComponentEvent { 67 68 /** 69 * The first number in the range of ids used for focus events. 70 */ 71 public static final int FOCUS_FIRST = 1004; 72 73 /** 74 * The last number in the range of ids used for focus events. 75 */ 76 public static final int FOCUS_LAST = 1005; 77 78 /** 79 * This event indicates that the Component is now the focus owner. 80 */ 81 public static final int FOCUS_GAINED = FOCUS_FIRST; //Event.GOT_FOCUS 82 83 /** 84 * This event indicates that the Component is no longer the focus owner. 85 */ 86 public static final int FOCUS_LOST = 1 + FOCUS_FIRST; //Event.LOST_FOCUS 87 88 /** 89 * A focus event can have two different levels, permanent and temporary. 90 * It will be set to true if some operation takes away the focus 91 * temporarily and intends on getting it back once the event is completed. 92 * Otherwise it will be set to false. 93 * 94 * @serial 95 * @see #isTemporary 96 */ 97 boolean temporary; 98 99 /** 100 * The other Component involved in this focus change. For a FOCUS_GAINED 101 * event, this is the Component that lost focus. For a FOCUS_LOST event, 102 * this is the Component that gained focus. If this focus change occurs 103 * with a native application, a Java application in a different VM, or with 104 * no other Component, then the opposite Component is null. 105 * 106 * @see #getOppositeComponent 107 * @since 1.4 108 */ 109 transient Component opposite; 110 111 /* 112 * JDK 1.1 serialVersionUID 113 */ 114 private static final long serialVersionUID = 523753786457416396L; 115 116 /** 117 * Constructs a <code>FocusEvent</code> object with the 118 * specified temporary state and opposite <code>Component</code>. 119 * The opposite <code>Component</code> is the other 120 * <code>Component</code> involved in this focus change. 121 * For a <code>FOCUS_GAINED</code> event, this is the 122 * <code>Component</code> that lost focus. For a 123 * <code>FOCUS_LOST</code> event, this is the <code>Component</code> 124 * that gained focus. If this focus change occurs with a native 125 * application, with a Java application in a different VM, 126 * or with no other <code>Component</code>, then the opposite 127 * <code>Component</code> is <code>null</code>. 128 * <p> This method throws an 129 * <code>IllegalArgumentException</code> if <code>source</code> 130 * is <code>null</code>. 131 * 132 * @param source The <code>Component</code> that originated the event 133 * @param id An integer indicating the type of event. 134 * For information on allowable values, see 135 * the class description for {@link FocusEvent} 136 * @param temporary Equals <code>true</code> if the focus change is temporary; 137 * <code>false</code> otherwise 138 * @param opposite The other Component involved in the focus change, 139 * or <code>null</code> 140 * @throws IllegalArgumentException if <code>source</code> equals {@code null} 141 * @see #getSource() 142 * @see #getID() 143 * @see #isTemporary() 144 * @see #getOppositeComponent() 145 * @since 1.4 146 */ FocusEvent(Component source, int id, boolean temporary, Component opposite)147 public FocusEvent(Component source, int id, boolean temporary, 148 Component opposite) { 149 super(source, id); 150 this.temporary = temporary; 151 this.opposite = opposite; 152 } 153 154 /** 155 * Constructs a <code>FocusEvent</code> object and identifies 156 * whether or not the change is temporary. 157 * <p> This method throws an 158 * <code>IllegalArgumentException</code> if <code>source</code> 159 * is <code>null</code>. 160 * 161 * @param source The <code>Component</code> that originated the event 162 * @param id An integer indicating the type of event. 163 * For information on allowable values, see 164 * the class description for {@link FocusEvent} 165 * @param temporary Equals <code>true</code> if the focus change is temporary; 166 * <code>false</code> otherwise 167 * @throws IllegalArgumentException if <code>source</code> equals {@code null} 168 * @see #getSource() 169 * @see #getID() 170 * @see #isTemporary() 171 */ FocusEvent(Component source, int id, boolean temporary)172 public FocusEvent(Component source, int id, boolean temporary) { 173 this(source, id, temporary, null); 174 } 175 176 /** 177 * Constructs a <code>FocusEvent</code> object and identifies it 178 * as a permanent change in focus. 179 * <p> This method throws an 180 * <code>IllegalArgumentException</code> if <code>source</code> 181 * is <code>null</code>. 182 * 183 * @param source The <code>Component</code> that originated the event 184 * @param id An integer indicating the type of event. 185 * For information on allowable values, see 186 * the class description for {@link FocusEvent} 187 * @throws IllegalArgumentException if <code>source</code> equals {@code null} 188 * @see #getSource() 189 * @see #getID() 190 */ FocusEvent(Component source, int id)191 public FocusEvent(Component source, int id) { 192 this(source, id, false); 193 } 194 195 /** 196 * Identifies the focus change event as temporary or permanent. 197 * 198 * @return <code>true</code> if the focus change is temporary; 199 * <code>false</code> otherwise 200 */ isTemporary()201 public boolean isTemporary() { 202 return temporary; 203 } 204 205 /** 206 * Returns the other Component involved in this focus change. For a 207 * FOCUS_GAINED event, this is the Component that lost focus. For a 208 * FOCUS_LOST event, this is the Component that gained focus. If this 209 * focus change occurs with a native application, with a Java application 210 * in a different VM or context, or with no other Component, then null is 211 * returned. 212 * 213 * @return the other Component involved in the focus change, or null 214 * @since 1.4 215 */ getOppositeComponent()216 public Component getOppositeComponent() { 217 if (opposite == null) { 218 return null; 219 } 220 221 return (SunToolkit.targetToAppContext(opposite) == 222 AppContext.getAppContext()) 223 ? opposite 224 : null; 225 } 226 227 /** 228 * Returns a parameter string identifying this event. 229 * This method is useful for event-logging and for debugging. 230 * 231 * @return a string identifying the event and its attributes 232 */ paramString()233 public String paramString() { 234 String typeStr; 235 switch(id) { 236 case FOCUS_GAINED: 237 typeStr = "FOCUS_GAINED"; 238 break; 239 case FOCUS_LOST: 240 typeStr = "FOCUS_LOST"; 241 break; 242 default: 243 typeStr = "unknown type"; 244 } 245 return typeStr + (temporary ? ",temporary" : ",permanent") + 246 ",opposite=" + getOppositeComponent(); 247 } 248 249 } 250