001 /*
002 * Copyright 1996-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.event;
027
028 import java.awt.Component;
029 import sun.awt.AppContext;
030 import sun.awt.SunToolkit;
031
032 /**
033 * A low-level event which indicates that a Component has gained or lost the
034 * input focus. This low-level event is generated by a Component (such as a
035 * TextField). The event is passed to every <code>FocusListener</code> or
036 * <code>FocusAdapter</code> object which registered to receive such events
037 * using the Component's <code>addFocusListener</code> method. (<code>
038 * FocusAdapter</code> objects implement the <code>FocusListener</code>
039 * interface.) Each such listener object gets this <code>FocusEvent</code> when
040 * the event occurs.
041 * <p>
042 * There are two levels of focus events: permanent and temporary. Permanent
043 * focus change events occur when focus is directly moved from one Component to
044 * another, such as through a call to requestFocus() or as the user uses the
045 * TAB key to traverse Components. Temporary focus change events occur when
046 * focus is temporarily lost for a Component as the indirect result of another
047 * operation, such as Window deactivation or a Scrollbar drag. In this case,
048 * the original focus state will automatically be restored once that operation
049 * is finished, or, for the case of Window deactivation, when the Window is
050 * reactivated. Both permanent and temporary focus events are delivered using
051 * the FOCUS_GAINED and FOCUS_LOST event ids; the level may be distinguished in
052 * the event using the isTemporary() method.
053 *
054 * @see FocusAdapter
055 * @see FocusListener
056 * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/focuslistener.html">Tutorial: Writing a Focus Listener</a>
057 *
058 * @author Carl Quinn
059 * @author Amy Fowler
060 * @version 1.41 06/05/07
061 * @since 1.1
062 */
063 public class FocusEvent extends ComponentEvent {
064
065 /**
066 * The first number in the range of ids used for focus events.
067 */
068 public static final int FOCUS_FIRST = 1004;
069
070 /**
071 * The last number in the range of ids used for focus events.
072 */
073 public static final int FOCUS_LAST = 1005;
074
075 /**
076 * This event indicates that the Component is now the focus owner.
077 */
078 public static final int FOCUS_GAINED = FOCUS_FIRST; //Event.GOT_FOCUS
079
080 /**
081 * This event indicates that the Component is no longer the focus owner.
082 */
083 public static final int FOCUS_LOST = 1 + FOCUS_FIRST; //Event.LOST_FOCUS
084
085 /**
086 * A focus event can have two different levels, permanent and temporary.
087 * It will be set to true if some operation takes away the focus
088 * temporarily and intends on getting it back once the event is completed.
089 * Otherwise it will be set to false.
090 *
091 * @serial
092 * @see #isTemporary
093 */
094 boolean temporary;
095
096 /**
097 * The other Component involved in this focus change. For a FOCUS_GAINED
098 * event, this is the Component that lost focus. For a FOCUS_LOST event,
099 * this is the Component that gained focus. If this focus change occurs
100 * with a native application, a Java application in a different VM, or with
101 * no other Component, then the opposite Component is null.
102 *
103 * @see #getOppositeComponent
104 * @since 1.4
105 */
106 transient Component opposite;
107
108 /*
109 * JDK 1.1 serialVersionUID
110 */
111 private static final long serialVersionUID = 523753786457416396L;
112
113 /**
114 * Constructs a <code>FocusEvent</code> object with the
115 * specified temporary state and opposite <code>Component</code>.
116 * The opposite <code>Component</code> is the other
117 * <code>Component</code> involved in this focus change.
118 * For a <code>FOCUS_GAINED</code> event, this is the
119 * <code>Component</code> that lost focus. For a
120 * <code>FOCUS_LOST</code> event, this is the <code>Component</code>
121 * that gained focus. If this focus change occurs with a native
122 * application, with a Java application in a different VM,
123 * or with no other <code>Component</code>, then the opposite
124 * <code>Component</code> is <code>null</code>.
125 * <p>Note that passing in an invalid <code>id</code> results in
126 * unspecified behavior. This method throws an
127 * <code>IllegalArgumentException</code> if <code>source</code>
128 * is <code>null</code>.
129 *
130 * @param source the <code>Component</code> that originated the event
131 * @param id <code>FOCUS_GAINED</code> or <code>FOCUS_LOST</code>
132 * @param temporary <code>true</code> if the focus change is temporary;
133 * <code>false</code> otherwise
134 * @param opposite the other Component involved in the focus change,
135 * or <code>null</code>
136 * @throws IllegalArgumentException if <code>source</code> is null
137 * @since 1.4
138 */
139 public FocusEvent(Component source, int id, boolean temporary,
140 Component opposite) {
141 super (source, id);
142 this .temporary = temporary;
143 this .opposite = opposite;
144 }
145
146 /**
147 * Constructs a <code>FocusEvent</code> object and identifies
148 * whether or not the change is temporary.
149 * <p>Note that passing in an invalid <code>id</code> results in
150 * unspecified behavior. This method throws an
151 * <code>IllegalArgumentException</code> if <code>source</code>
152 * is <code>null</code>.
153 *
154 * @param source the <code>Component</code> that originated the event
155 * @param id an integer indicating the type of event
156 * @param temporary <code>true</code> if the focus change is temporary;
157 * <code>false</code> otherwise
158 * @throws IllegalArgumentException if <code>source</code> is null
159 */
160 public FocusEvent(Component source, int id, boolean temporary) {
161 this (source, id, temporary, null);
162 }
163
164 /**
165 * Constructs a <code>FocusEvent</code> object and identifies it
166 * as a permanent change in focus.
167 * <p>Note that passing in an invalid <code>id</code> results in
168 * unspecified behavior. This method throws an
169 * <code>IllegalArgumentException</code> if <code>source</code>
170 * is <code>null</code>.
171 *
172 * @param source the <code>Component</code> that originated the event
173 * @param id an integer indicating the type of event
174 * @throws IllegalArgumentException if <code>source</code> is null
175 */
176 public FocusEvent(Component source, int id) {
177 this (source, id, false);
178 }
179
180 /**
181 * Identifies the focus change event as temporary or permanent.
182 *
183 * @return <code>true</code> if the focus change is temporary;
184 * <code>false</code> otherwise
185 */
186 public boolean isTemporary() {
187 return temporary;
188 }
189
190 /**
191 * Returns the other Component involved in this focus change. For a
192 * FOCUS_GAINED event, this is the Component that lost focus. For a
193 * FOCUS_LOST event, this is the Component that gained focus. If this
194 * focus change occurs with a native application, with a Java application
195 * in a different VM or context, or with no other Component, then null is
196 * returned.
197 *
198 * @return the other Component involved in the focus change, or null
199 * @since 1.4
200 */
201 public Component getOppositeComponent() {
202 if (opposite == null) {
203 return null;
204 }
205
206 return (SunToolkit.targetToAppContext(opposite) == AppContext
207 .getAppContext()) ? opposite : null;
208 }
209
210 /**
211 * Returns a parameter string identifying this event.
212 * This method is useful for event-logging and for debugging.
213 *
214 * @return a string identifying the event and its attributes
215 */
216 public String paramString() {
217 String typeStr;
218 switch (id) {
219 case FOCUS_GAINED:
220 typeStr = "FOCUS_GAINED";
221 break;
222 case FOCUS_LOST:
223 typeStr = "FOCUS_LOST";
224 break;
225 default:
226 typeStr = "unknown type";
227 }
228 return typeStr + (temporary ? ",temporary" : ",permanent")
229 + ",opposite=" + getOppositeComponent();
230 }
231
232 }
|