1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
/* * @(#)FocusEvent.java 1.33 06/04/18 * * Copyright 2006 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package java.awt.event; import java.awt.Component; import java.awt.Event; 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</code> or * <code>FocusAdapter</code> object which registered to receive such events * using the Component's <code>addFocusListener</code> method. (<code> * FocusAdapter</code> objects implement the <code>FocusListener</code> * interface.) Each such listener object gets this <code>FocusEvent</code> 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. * * @see FocusAdapter * @see FocusListener * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/focuslistener.html">Tutorial: Writing a Focus Listener</a> * * @author Carl Quinn * @author Amy Fowler * @version 1.33 04/18/06 * @since 1.1 */ public class FocusEvent extends ComponentEvent { /** * 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 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</code> object with the * specified temporary state and opposite <code>Component</code>. * The opposite <code>Component</code> is the other * <code>Component</code> involved in this focus change. * For a <code>FOCUS_GAINED</code> event, this is the * <code>Component</code> that lost focus. For a * <code>FOCUS_LOST</code> event, this is the <code>Component</code> * 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</code>, then the opposite * <code>Component</code> is <code>null</code>. * <p>Note that passing in an invalid <code>id</code> results in * unspecified behavior. This method throws an * <code>IllegalArgumentException</code> if <code>source</code> * is <code>null</code>. * * @param source the <code>Component</code> that originated the event * @param id <code>FOCUS_GAINED</code> or <code>FOCUS_LOST</code> * @param temporary <code>true</code> if the focus change is temporary; * <code>false</code> otherwise * @param opposite the other Component involved in the focus change, * or <code>null</code> * @throws IllegalArgumentException if <code>source</code> is null * @since 1.4 */ public FocusEvent(Component source, int id, boolean temporary, Component opposite) { super(source, id); this.temporary = temporary; this.opposite = opposite; } /** * Constructs a <code>FocusEvent</code> object and identifies * whether or not the change is temporary. * <p>Note that passing in an invalid <code>id</code> results in * unspecified behavior. This method throws an * <code>IllegalArgumentException</code> if <code>source</code> * is <code>null</code>. * * @param source the <code>Component</code> that originated the event * @param id an integer indicating the type of event * @param temporary <code>true</code> if the focus change is temporary; * <code>false</code> otherwise * @throws IllegalArgumentException if <code>source</code> is null */ public FocusEvent(Component source, int id, boolean temporary) { this(source, id, temporary, null); } /** * Constructs a <code>FocusEvent</code> object and identifies it * as a permanent change in focus. * <p>Note that passing in an invalid <code>id</code> results in * unspecified behavior. This method throws an * <code>IllegalArgumentException</code> if <code>source</code> * is <code>null</code>. * * @param source the <code>Component</code> that originated the event * @param id an integer indicating the type of event * @throws IllegalArgumentException if <code>source</code> is null */ public FocusEvent(Component source, int id) { this(source, id, false); } /** * Identifies the focus change event as temporary or permanent. * * @return <code>true</code> if the focus change is temporary; * <code>false</code> 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(); } }