1 /*
2 * Copyright (c) 1997, 2007, 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.AWTEvent;
29 import java.awt.Component;
30 import java.awt.EventQueue;
31 import java.awt.font.TextHitInfo;
32 import java.io.IOException;
33 import java.io.ObjectInputStream;
34 import java.text.AttributedCharacterIterator;
35 import java.text.CharacterIterator;
36 import javax.tools.annotation.GenerateNativeHeader;
37
38 /**
39 * Input method events contain information about text that is being
40 * composed using an input method. Whenever the text changes, the
41 * input method sends an event. If the text component that's currently
42 * using the input method is an active client, the event is dispatched
43 * to that component. Otherwise, it is dispatched to a separate
44 * composition window.
45 *
46 * <p>
47 * The text included with the input method event consists of two parts:
48 * committed text and composed text. Either part may be empty. The two
49 * parts together replace any uncommitted composed text sent in previous events,
50 * or the currently selected committed text.
51 * Committed text should be integrated into the text component's persistent
52 * data, it will not be sent again. Composed text may be sent repeatedly,
53 * with changes to reflect the user's editing operations. Committed text
54 * always precedes composed text.
55 *
56 * @author JavaSoft Asia/Pacific
57 * @since 1.2
58 */
59 /* No native methods here, but the constants are needed in the supporting JNI code */
60 @GenerateNativeHeader
61 public class InputMethodEvent extends AWTEvent {
62
63 /**
64 * Serial Version ID.
65 */
66 private static final long serialVersionUID = 4727190874778922661L;
67
68 /**
69 * Marks the first integer id for the range of input method event ids.
70 */
71 public static final int INPUT_METHOD_FIRST = 1100;
72
73 /**
74 * The event type indicating changed input method text. This event is
75 * generated by input methods while processing input.
76 */
77 public static final int INPUT_METHOD_TEXT_CHANGED = INPUT_METHOD_FIRST;
78
79 /**
80 * The event type indicating a changed insertion point in input method text.
81 * This event is
82 * generated by input methods while processing input if only the caret changed.
83 */
84 public static final int CARET_POSITION_CHANGED = INPUT_METHOD_FIRST + 1;
85
86 /**
87 * Marks the last integer id for the range of input method event ids.
88 */
89 public static final int INPUT_METHOD_LAST = INPUT_METHOD_FIRST + 1;
90
91 /**
92 * The time stamp that indicates when the event was created.
93 *
94 * @serial
95 * @see #getWhen
96 * @since 1.4
97 */
98 long when;
99
100 // Text object
101 private transient AttributedCharacterIterator text;
102 private transient int committedCharacterCount;
103 private transient TextHitInfo caret;
104 private transient TextHitInfo visiblePosition;
105
106 /**
107 * Constructs an <code>InputMethodEvent</code> with the specified
108 * source component, type, time, text, caret, and visiblePosition.
109 * <p>
110 * The offsets of caret and visiblePosition are relative to the current
111 * composed text; that is, the composed text within <code>text</code>
112 * if this is an <code>INPUT_METHOD_TEXT_CHANGED</code> event,
113 * the composed text within the <code>text</code> of the
114 * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event otherwise.
115 * <p>Note that passing in an invalid <code>id</code> results in
116 * unspecified behavior. This method throws an
117 * <code>IllegalArgumentException</code> if <code>source</code>
118 * is <code>null</code>.
119 *
120 * @param source the object where the event originated
121 * @param id the event type
122 * @param when a long integer that specifies the time the event occurred
123 * @param text the combined committed and composed text,
124 * committed text first; must be <code>null</code>
125 * when the event type is <code>CARET_POSITION_CHANGED</code>;
126 * may be <code>null</code> for
127 * <code>INPUT_METHOD_TEXT_CHANGED</code> if there's no
128 * committed or composed text
129 * @param committedCharacterCount the number of committed
130 * characters in the text
131 * @param caret the caret (a.k.a. insertion point);
132 * <code>null</code> if there's no caret within current
133 * composed text
134 * @param visiblePosition the position that's most important
135 * to be visible; <code>null</code> if there's no
136 * recommendation for a visible position within current
137 * composed text
138 * @throws IllegalArgumentException if <code>id</code> is not
139 * in the range
140 * <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>;
141 * or if id is <code>CARET_POSITION_CHANGED</code> and
142 * <code>text</code> is not <code>null</code>;
143 * or if <code>committedCharacterCount</code> is not in the range
144 * <code>0</code>..<code>(text.getEndIndex() - text.getBeginIndex())</code>
145 * @throws IllegalArgumentException if <code>source</code> is null
146 *
147 * @since 1.4
148 */
149 public InputMethodEvent(Component source, int id, long when,
150 AttributedCharacterIterator text, int committedCharacterCount,
151 TextHitInfo caret, TextHitInfo visiblePosition) {
152 super(source, id);
153 if (id < INPUT_METHOD_FIRST || id > INPUT_METHOD_LAST) {
154 throw new IllegalArgumentException("id outside of valid range");
155 }
156
157 if (id == CARET_POSITION_CHANGED && text != null) {
158 throw new IllegalArgumentException("text must be null for CARET_POSITION_CHANGED");
159 }
160
161 this.when = when;
162 this.text = text;
163 int textLength = 0;
164 if (text != null) {
165 textLength = text.getEndIndex() - text.getBeginIndex();
166 }
167
168 if (committedCharacterCount < 0 || committedCharacterCount > textLength) {
169 throw new IllegalArgumentException("committedCharacterCount outside of valid range");
170 }
171 this.committedCharacterCount = committedCharacterCount;
172
173 this.caret = caret;
174 this.visiblePosition = visiblePosition;
175 }
176
177 /**
178 * Constructs an <code>InputMethodEvent</code> with the specified
179 * source component, type, text, caret, and visiblePosition.
180 * <p>
181 * The offsets of caret and visiblePosition are relative to the current
182 * composed text; that is, the composed text within <code>text</code>
183 * if this is an <code>INPUT_METHOD_TEXT_CHANGED</code> event,
184 * the composed text within the <code>text</code> of the
185 * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event otherwise.
186 * The time stamp for this event is initialized by invoking
187 * {@link java.awt.EventQueue#getMostRecentEventTime()}.
188 * <p>Note that passing in an invalid <code>id</code> results in
189 * unspecified behavior. This method throws an
190 * <code>IllegalArgumentException</code> if <code>source</code>
191 * is <code>null</code>.
192 *
193 * @param source the object where the event originated
194 * @param id the event type
195 * @param text the combined committed and composed text,
196 * committed text first; must be <code>null</code>
197 * when the event type is <code>CARET_POSITION_CHANGED</code>;
198 * may be <code>null</code> for
199 * <code>INPUT_METHOD_TEXT_CHANGED</code> if there's no
200 * committed or composed text
201 * @param committedCharacterCount the number of committed
202 * characters in the text
203 * @param caret the caret (a.k.a. insertion point);
204 * <code>null</code> if there's no caret within current
205 * composed text
206 * @param visiblePosition the position that's most important
207 * to be visible; <code>null</code> if there's no
208 * recommendation for a visible position within current
209 * composed text
210 * @throws IllegalArgumentException if <code>id</code> is not
211 * in the range
212 * <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>;
213 * or if id is <code>CARET_POSITION_CHANGED</code> and
214 * <code>text</code> is not <code>null</code>;
215 * or if <code>committedCharacterCount</code> is not in the range
216 * <code>0</code>..<code>(text.getEndIndex() - text.getBeginIndex())</code>
217 * @throws IllegalArgumentException if <code>source</code> is null
218 */
219 public InputMethodEvent(Component source, int id,
220 AttributedCharacterIterator text, int committedCharacterCount,
221 TextHitInfo caret, TextHitInfo visiblePosition) {
222 this(source, id, EventQueue.getMostRecentEventTime(), text,
223 committedCharacterCount, caret, visiblePosition);
224 }
225
226 /**
227 * Constructs an <code>InputMethodEvent</code> with the
228 * specified source component, type, caret, and visiblePosition.
229 * The text is set to <code>null</code>,
230 * <code>committedCharacterCount</code> to 0.
231 * <p>
232 * The offsets of <code>caret</code> and <code>visiblePosition</code>
233 * are relative to the current composed text; that is,
234 * the composed text within the <code>text</code> of the
235 * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event if the
236 * event being constructed as a <code>CARET_POSITION_CHANGED</code> event.
237 * For an <code>INPUT_METHOD_TEXT_CHANGED</code> event without text,
238 * <code>caret</code> and <code>visiblePosition</code> must be
239 * <code>null</code>.
240 * The time stamp for this event is initialized by invoking
241 * {@link java.awt.EventQueue#getMostRecentEventTime()}.
242 * <p>Note that passing in an invalid <code>id</code> results in
243 * unspecified behavior. This method throws an
244 * <code>IllegalArgumentException</code> if <code>source</code>
245 * is <code>null</code>.
246 *
247 * @param source the object where the event originated
248 * @param id the event type
249 * @param caret the caret (a.k.a. insertion point);
250 * <code>null</code> if there's no caret within current
251 * composed text
252 * @param visiblePosition the position that's most important
253 * to be visible; <code>null</code> if there's no
254 * recommendation for a visible position within current
255 * composed text
256 * @throws IllegalArgumentException if <code>id</code> is not
257 * in the range
258 * <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>
259 * @throws IllegalArgumentException if <code>source</code> is null
260 */
261 public InputMethodEvent(Component source, int id, TextHitInfo caret,
262 TextHitInfo visiblePosition) {
263 this(source, id, EventQueue.getMostRecentEventTime(), null,
264 0, caret, visiblePosition);
265 }
266
267 /**
268 * Gets the combined committed and composed text.
269 * Characters from index 0 to index <code>getCommittedCharacterCount() - 1</code> are committed
270 * text, the remaining characters are composed text.
271 *
272 * @return the text.
273 * Always null for CARET_POSITION_CHANGED;
274 * may be null for INPUT_METHOD_TEXT_CHANGED if there's no composed or committed text.
275 */
276 public AttributedCharacterIterator getText() {
277 return text;
278 }
279
280 /**
281 * Gets the number of committed characters in the text.
282 */
283 public int getCommittedCharacterCount() {
284 return committedCharacterCount;
285 }
286
287 /**
288 * Gets the caret.
289 * <p>
290 * The offset of the caret is relative to the current
291 * composed text; that is, the composed text within getText()
292 * if this is an <code>INPUT_METHOD_TEXT_CHANGED</code> event,
293 * the composed text within getText() of the
294 * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event otherwise.
295 *
296 * @return the caret (a.k.a. insertion point).
297 * Null if there's no caret within current composed text.
298 */
299 public TextHitInfo getCaret() {
300 return caret;
301 }
302
303 /**
304 * Gets the position that's most important to be visible.
305 * <p>
306 * The offset of the visible position is relative to the current
307 * composed text; that is, the composed text within getText()
308 * if this is an <code>INPUT_METHOD_TEXT_CHANGED</code> event,
309 * the composed text within getText() of the
310 * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event otherwise.
311 *
312 * @return the position that's most important to be visible.
313 * Null if there's no recommendation for a visible position within current composed text.
314 */
315 public TextHitInfo getVisiblePosition() {
316 return visiblePosition;
317 }
318
319 /**
320 * Consumes this event so that it will not be processed
321 * in the default manner by the source which originated it.
322 */
323 public void consume() {
324 consumed = true;
325 }
326
327 /**
328 * Returns whether or not this event has been consumed.
329 * @see #consume
330 */
331 public boolean isConsumed() {
332 return consumed;
333 }
334
335 /**
336 * Returns the time stamp of when this event occurred.
337 *
338 * @return this event's timestamp
339 * @since 1.4
340 */
341 public long getWhen() {
342 return when;
343 }
344
345 /**
346 * Returns a parameter string identifying this event.
347 * This method is useful for event-logging and for debugging.
348 * It contains the event ID in text form, the characters of the
349 * committed and composed text
350 * separated by "+", the number of committed characters,
351 * the caret, and the visible position.
352 *
353 * @return a string identifying the event and its attributes
354 */
355 public String paramString() {
356 String typeStr;
357 switch(id) {
358 case INPUT_METHOD_TEXT_CHANGED:
359 typeStr = "INPUT_METHOD_TEXT_CHANGED";
360 break;
361 case CARET_POSITION_CHANGED:
362 typeStr = "CARET_POSITION_CHANGED";
363 break;
364 default:
365 typeStr = "unknown type";
366 }
367
368 String textString;
369 if (text == null) {
370 textString = "no text";
371 } else {
372 StringBuilder textBuffer = new StringBuilder("\"");
373 int committedCharacterCount = this.committedCharacterCount;
374 char c = text.first();
375 while (committedCharacterCount-- > 0) {
376 textBuffer.append(c);
377 c = text.next();
378 }
379 textBuffer.append("\" + \"");
380 while (c != CharacterIterator.DONE) {
381 textBuffer.append(c);
382 c = text.next();
383 }
384 textBuffer.append("\"");
385 textString = textBuffer.toString();
386 }
387
388 String countString = committedCharacterCount + " characters committed";
389
390 String caretString;
391 if (caret == null) {
392 caretString = "no caret";
393 } else {
394 caretString = "caret: " + caret.toString();
395 }
396
397 String visiblePositionString;
398 if (visiblePosition == null) {
399 visiblePositionString = "no visible position";
400 } else {
401 visiblePositionString = "visible position: " + visiblePosition.toString();
402 }
403
404 return typeStr + ", " + textString + ", " + countString + ", " + caretString + ", " + visiblePositionString;
405 }
406
407 /**
408 * Initializes the <code>when</code> field if it is not present in the
409 * object input stream. In that case, the field will be initialized by
410 * invoking {@link java.awt.EventQueue#getMostRecentEventTime()}.
411 */
412 private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException {
413 s.defaultReadObject();
414 if (when == 0) {
415 when = EventQueue.getMostRecentEventTime();
416 }
417 }
418 }