FocusEvent


1   /*
2    * @(#)FocusEvent.java  1.30 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt.event;
9   
10  import java.awt.Component  ;
11  import java.awt.Event  ;
12  
13  import sun.awt.AppContext;
14  import sun.awt.SunToolkit;
15  
16  /**
17   * A low-level event which indicates that a Component has gained or lost the
18   * input focus. This low-level event is generated by a Component (such as a
19   * TextField). The event is passed to every <code>FocusListener</code> or
20   * <code>FocusAdapter</code> object which registered to receive such events
21   * using the Component's <code>addFocusListener</code> method. (<code>
22   * FocusAdapter</code> objects implement the <code>FocusListener</code>
23   * interface.) Each such listener object gets this <code>FocusEvent</code> when
24   * the event occurs.
25   * <p>
26   * There are two levels of focus events: permanent and temporary. Permanent
27   * focus change events occur when focus is directly moved from one Component to
28   * another, such as through a call to requestFocus() or as the user uses the
29   * TAB key to traverse Components. Temporary focus change events occur when
30   * focus is temporarily lost for a Component as the indirect result of another
31   * operation, such as Window deactivation or a Scrollbar drag. In this case,
32   * the original focus state will automatically be restored once that operation
33   * is finished, or, for the case of Window deactivation, when the Window is
34   * reactivated. Both permanent and temporary focus events are delivered using
35   * the FOCUS_GAINED and FOCUS_LOST event ids; the level may be distinguished in
36   * the event using the isTemporary() method.
37   *  
38   * @see FocusAdapter
39   * @see FocusListener
40   * @see <a HREF="http://java.sun.com/docs/books/tutorial/post1.0/ui/focuslistener.html">Tutorial: Writing a Focus Listener</a>
41   * @see <a HREF="http://www.awl.com/cp/javaseries/jcl1_2.html">Reference: The Java Class Libraries (update file)</a>
42   *
43   * @author Carl Quinn
44   * @author Amy Fowler
45   * @version 1.30 12/19/03
46   * @since 1.1
47   */
48  public class FocusEvent extends ComponentEvent   {
49  
50      /**
51       * The first number in the range of ids used for focus events.
52       */    
53      public static final int FOCUS_FIRST     = 1004;
54  
55      /**
56       * The last number in the range of ids used for focus events.
57       */
58      public static final int FOCUS_LAST      = 1005;
59  
60      /**
61       * This event indicates that the Component is now the focus owner.
62       */
63      public static final int FOCUS_GAINED = FOCUS_FIRST; //Event.GOT_FOCUS
64  
65      /**
66       * This event indicates that the Component is no longer the focus owner.
67       */
68      public static final int FOCUS_LOST = 1 + FOCUS_FIRST; //Event.LOST_FOCUS
69  
70      /**
71       * A focus event can have two different levels, permanent and temporary.
72       * It will be set to true if some operation takes away the focus
73       * temporarily and intends on getting it back once the event is completed.
74       * Otherwise it will be set to false.
75       *
76       * @serial
77       * @see #isTemporary
78       */
79      boolean temporary;
80  
81      /**
82       * The other Component involved in this focus change. For a FOCUS_GAINED
83       * event, this is the Component that lost focus. For a FOCUS_LOST event,
84       * this is the Component that gained focus. If this focus change occurs
85       * with a native application, a Java application in a different VM, or with
86       * no other Component, then the opposite Component is null.
87       *
88       * @see #getOppositeComponent
89       * @since 1.4
90       */
91      transient Component   opposite;
92    
93      /*
94       * JDK 1.1 serialVersionUID 
95       */
96      private static final long serialVersionUID = 523753786457416396L;
97  
98      /**
99       * Constructs a <code>FocusEvent</code> object with the
100      * specified temporary state and opposite <code>Component</code>.
101      * The opposite <code>Component</code> is the other
102      * <code>Component</code> involved in this focus change.
103      * For a <code>FOCUS_GAINED</code> event, this is the
104      * <code>Component</code> that lost focus. For a
105      * <code>FOCUS_LOST</code> event, this is the <code>Component</code>
106      * that gained focus. If this focus change occurs with a native
107      * application, with a Java application in a different VM,
108      * or with no other <code>Component</code>, then the opposite
109      * <code>Component</code> is <code>null</code>.
110      * <p>Note that passing in an invalid <code>id</code> results in
111      * unspecified behavior. This method throws an
112      * <code>IllegalArgumentException</code> if <code>source</code>
113      * is <code>null</code>.
114      * 
115      * @param source     the <code>Component</code> that originated the event
116      * @param id         <code>FOCUS_GAINED</code> or <code>FOCUS_LOST</code>
117      * @param temporary  <code>true</code> if the focus change is temporary;
118      *                   <code>false</code> otherwise
119      * @param opposite   the other Component involved in the focus change,
120      *                   or <code>null</code>
121      * @throws IllegalArgumentException if <code>source</code> is null
122      */
123     public FocusEvent(Component   source, int id, boolean temporary,
124                       Component   opposite) {
125         super(source, id);
126     this.temporary = temporary;
127     this.opposite = opposite;
128     }
129 
130     /**
131      * Constructs a <code>FocusEvent</code> object and identifies
132      * whether or not the change is temporary.
133      * <p>Note that passing in an invalid <code>id</code> results in
134      * unspecified behavior. This method throws an
135      * <code>IllegalArgumentException</code> if <code>source</code>
136      * is <code>null</code>.
137      *
138      * @param source    the <code>Component</code> that originated the event
139      * @param id        an integer indicating the type of event
140      * @param temporary <code>true</code> if the focus change is temporary;
141      *                  <code>false</code> otherwise
142      * @throws IllegalArgumentException if <code>source</code> is null
143      */
144     public FocusEvent(Component   source, int id, boolean temporary) {
145         this(source, id, temporary, null);
146     }
147 
148     /**
149      * Constructs a <code>FocusEvent</code> object and identifies it
150      * as a permanent change in focus.
151      * <p>Note that passing in an invalid <code>id</code> results in
152      * unspecified behavior. This method throws an
153      * <code>IllegalArgumentException</code> if <code>source</code>
154      * is <code>null</code>.
155      *
156      * @param source    the <code>Component</code> that originated the event
157      * @param id        an integer indicating the type of event
158      * @throws IllegalArgumentException if <code>source</code> is null
159      */
160     public FocusEvent(Component   source, int id) {
161         this(source, id, false);
162     }
163 
164     /**
165      * Identifies the focus change event as temporary or permanent.
166      *
167      * @return <code>true</code> if the focus change is temporary;
168      *         <code>false</code> otherwise
169      */
170     public boolean isTemporary() {
171         return temporary;
172     }
173 
174     /**
175      * Returns the other Component involved in this focus change. For a
176      * FOCUS_GAINED event, this is the Component that lost focus. For a
177      * FOCUS_LOST event, this is the Component that gained focus. If this
178      * focus change occurs with a native application, with a Java application
179      * in a different VM or context, or with no other Component, then null is
180      * returned.
181      *
182      * @return the other Component involved in the focus change, or null
183      * @since 1.4
184      */
185     public Component   getOppositeComponent() {
186         if (opposite == null) {
187         return null;
188     }
189 
190         return (SunToolkit.targetToAppContext(opposite) ==
191         AppContext.getAppContext())
192         ? opposite
193         : null;
194     }
195 
196     /**
197      * Returns a parameter string identifying this event.
198      * This method is useful for event-logging and for debugging.
199      *
200      * @return a string identifying the event and its attributes
201      */
202     public String   paramString() {
203         String   typeStr;
204         switch(id) {
205           case FOCUS_GAINED:
206               typeStr = "FOCUS_GAINED";
207               break;
208           case FOCUS_LOST:
209               typeStr = "FOCUS_LOST";
210               break;
211           default:
212               typeStr = "unknown type";
213         }
214     return typeStr + (temporary ? ",temporary" : ",permanent") +
215         ",opposite=" + getOppositeComponent();
216     }
217 
218 }
219
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags