src/share/classes/java/awt/event/InputMethodEvent.java

Print this page




   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 java.lang.annotation.Native;
  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:


 200      *      characters in the text
 201      * @param caret the caret (a.k.a. insertion point);
 202      *      <code>null</code> if there's no caret within current
 203      *      composed text
 204      * @param visiblePosition the position that's most important
 205      *      to be visible; <code>null</code> if there's no
 206      *      recommendation for a visible position within current
 207      *      composed text
 208      * @throws IllegalArgumentException if <code>id</code> is not
 209      *      in the range
 210      *      <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>;
 211      *      or if id is <code>CARET_POSITION_CHANGED</code> and
 212      *      <code>text</code> is not <code>null</code>;
 213      *      or if <code>committedCharacterCount</code> is not in the range
 214      *      <code>0</code>..<code>(text.getEndIndex() - text.getBeginIndex())</code>
 215      * @throws IllegalArgumentException if <code>source</code> is null
 216      */
 217     public InputMethodEvent(Component source, int id,
 218             AttributedCharacterIterator text, int committedCharacterCount,
 219             TextHitInfo caret, TextHitInfo visiblePosition) {
 220         this(source, id, EventQueue.getMostRecentEventTime(), text,
 221              committedCharacterCount, caret, visiblePosition);


 222     }
 223 
 224     /**
 225      * Constructs an <code>InputMethodEvent</code> with the
 226      * specified source component, type, caret, and visiblePosition.
 227      * The text is set to <code>null</code>,
 228      * <code>committedCharacterCount</code> to 0.
 229      * <p>
 230      * The offsets of <code>caret</code> and <code>visiblePosition</code>
 231      * are relative to the current composed text; that is,
 232      * the composed text within the <code>text</code> of the
 233      * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event if the
 234      * event being constructed as a <code>CARET_POSITION_CHANGED</code> event.
 235      * For an <code>INPUT_METHOD_TEXT_CHANGED</code> event without text,
 236      * <code>caret</code> and <code>visiblePosition</code> must be
 237      * <code>null</code>.
 238      * The time stamp for this event is initialized by invoking
 239      * {@link java.awt.EventQueue#getMostRecentEventTime()}.
 240      * <p>Note that passing in an invalid <code>id</code> results in
 241      * unspecified behavior. This method throws an
 242      * <code>IllegalArgumentException</code> if <code>source</code>
 243      * is <code>null</code>.
 244      *
 245      * @param source the object where the event originated
 246      * @param id the event type
 247      * @param caret the caret (a.k.a. insertion point);
 248      *      <code>null</code> if there's no caret within current
 249      *      composed text
 250      * @param visiblePosition the position that's most important
 251      *      to be visible; <code>null</code> if there's no
 252      *      recommendation for a visible position within current
 253      *      composed text
 254      * @throws IllegalArgumentException if <code>id</code> is not
 255      *      in the range
 256      *      <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>
 257      * @throws IllegalArgumentException if <code>source</code> is null
 258      */
 259     public InputMethodEvent(Component source, int id, TextHitInfo caret,
 260             TextHitInfo visiblePosition) {
 261         this(source, id, EventQueue.getMostRecentEventTime(), null,
 262              0, caret, visiblePosition);

 263     }
 264 
 265     /**
 266      * Gets the combined committed and composed text.
 267      * Characters from index 0 to index <code>getCommittedCharacterCount() - 1</code> are committed
 268      * text, the remaining characters are composed text.
 269      *
 270      * @return the text.
 271      * Always null for CARET_POSITION_CHANGED;
 272      * may be null for INPUT_METHOD_TEXT_CHANGED if there's no composed or committed text.
 273      */
 274     public AttributedCharacterIterator getText() {
 275         return text;
 276     }
 277 
 278     /**
 279      * Gets the number of committed characters in the text.
 280      * @return the number of committed characters in the text
 281      */
 282     public int getCommittedCharacterCount() {


 394         }
 395 
 396         String visiblePositionString;
 397         if (visiblePosition == null) {
 398             visiblePositionString = "no visible position";
 399         } else {
 400             visiblePositionString = "visible position: " + visiblePosition.toString();
 401         }
 402 
 403         return typeStr + ", " + textString + ", " + countString + ", " + caretString + ", " + visiblePositionString;
 404     }
 405 
 406     /**
 407      * Initializes the <code>when</code> field if it is not present in the
 408      * object input stream. In that case, the field will be initialized by
 409      * invoking {@link java.awt.EventQueue#getMostRecentEventTime()}.
 410      */
 411     private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException {
 412         s.defaultReadObject();
 413         if (when == 0) {
 414             when = EventQueue.getMostRecentEventTime();















 415         }



 416     }
 417 }


   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 sun.awt.AWTAccessor;
  29 import sun.awt.AppContext;
  30 import sun.awt.SunToolkit;
  31 
  32 import java.awt.AWTEvent;
  33 import java.awt.Component;
  34 import java.awt.EventQueue;
  35 import java.awt.font.TextHitInfo;
  36 import java.io.IOException;
  37 import java.io.ObjectInputStream;
  38 import java.text.AttributedCharacterIterator;
  39 import java.text.CharacterIterator;
  40 import java.lang.annotation.Native;
  41 
  42 /**
  43  * Input method events contain information about text that is being
  44  * composed using an input method. Whenever the text changes, the
  45  * input method sends an event. If the text component that's currently
  46  * using the input method is an active client, the event is dispatched
  47  * to that component. Otherwise, it is dispatched to a separate
  48  * composition window.
  49  *
  50  * <p>
  51  * The text included with the input method event consists of two parts:


 204      *      characters in the text
 205      * @param caret the caret (a.k.a. insertion point);
 206      *      <code>null</code> if there's no caret within current
 207      *      composed text
 208      * @param visiblePosition the position that's most important
 209      *      to be visible; <code>null</code> if there's no
 210      *      recommendation for a visible position within current
 211      *      composed text
 212      * @throws IllegalArgumentException if <code>id</code> is not
 213      *      in the range
 214      *      <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>;
 215      *      or if id is <code>CARET_POSITION_CHANGED</code> and
 216      *      <code>text</code> is not <code>null</code>;
 217      *      or if <code>committedCharacterCount</code> is not in the range
 218      *      <code>0</code>..<code>(text.getEndIndex() - text.getBeginIndex())</code>
 219      * @throws IllegalArgumentException if <code>source</code> is null
 220      */
 221     public InputMethodEvent(Component source, int id,
 222             AttributedCharacterIterator text, int committedCharacterCount,
 223             TextHitInfo caret, TextHitInfo visiblePosition) {
 224         this(source, id,
 225                 getMostRecentEventTimeForSource(source),
 226                 text, committedCharacterCount,
 227                 caret, visiblePosition);
 228     }
 229 
 230     /**
 231      * Constructs an <code>InputMethodEvent</code> with the
 232      * specified source component, type, caret, and visiblePosition.
 233      * The text is set to <code>null</code>,
 234      * <code>committedCharacterCount</code> to 0.
 235      * <p>
 236      * The offsets of <code>caret</code> and <code>visiblePosition</code>
 237      * are relative to the current composed text; that is,
 238      * the composed text within the <code>text</code> of the
 239      * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event if the
 240      * event being constructed as a <code>CARET_POSITION_CHANGED</code> event.
 241      * For an <code>INPUT_METHOD_TEXT_CHANGED</code> event without text,
 242      * <code>caret</code> and <code>visiblePosition</code> must be
 243      * <code>null</code>.
 244      * The time stamp for this event is initialized by invoking
 245      * {@link java.awt.EventQueue#getMostRecentEventTime()}.
 246      * <p>Note that passing in an invalid <code>id</code> results in
 247      * unspecified behavior. This method throws an
 248      * <code>IllegalArgumentException</code> if <code>source</code>
 249      * is <code>null</code>.
 250      *
 251      * @param source the object where the event originated
 252      * @param id the event type
 253      * @param caret the caret (a.k.a. insertion point);
 254      *      <code>null</code> if there's no caret within current
 255      *      composed text
 256      * @param visiblePosition the position that's most important
 257      *      to be visible; <code>null</code> if there's no
 258      *      recommendation for a visible position within current
 259      *      composed text
 260      * @throws IllegalArgumentException if <code>id</code> is not
 261      *      in the range
 262      *      <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>
 263      * @throws IllegalArgumentException if <code>source</code> is null
 264      */
 265     public InputMethodEvent(Component source, int id, TextHitInfo caret,
 266             TextHitInfo visiblePosition) {
 267         this(source, id,
 268                 getMostRecentEventTimeForSource(source),
 269                 null, 0, caret, visiblePosition);
 270     }
 271 
 272     /**
 273      * Gets the combined committed and composed text.
 274      * Characters from index 0 to index <code>getCommittedCharacterCount() - 1</code> are committed
 275      * text, the remaining characters are composed text.
 276      *
 277      * @return the text.
 278      * Always null for CARET_POSITION_CHANGED;
 279      * may be null for INPUT_METHOD_TEXT_CHANGED if there's no composed or committed text.
 280      */
 281     public AttributedCharacterIterator getText() {
 282         return text;
 283     }
 284 
 285     /**
 286      * Gets the number of committed characters in the text.
 287      * @return the number of committed characters in the text
 288      */
 289     public int getCommittedCharacterCount() {


 401         }
 402 
 403         String visiblePositionString;
 404         if (visiblePosition == null) {
 405             visiblePositionString = "no visible position";
 406         } else {
 407             visiblePositionString = "visible position: " + visiblePosition.toString();
 408         }
 409 
 410         return typeStr + ", " + textString + ", " + countString + ", " + caretString + ", " + visiblePositionString;
 411     }
 412 
 413     /**
 414      * Initializes the <code>when</code> field if it is not present in the
 415      * object input stream. In that case, the field will be initialized by
 416      * invoking {@link java.awt.EventQueue#getMostRecentEventTime()}.
 417      */
 418     private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException {
 419         s.defaultReadObject();
 420         if (when == 0) {
 421             when = getMostRecentEventTimeForSource(this.source);
 422         }
 423     }
 424 
 425     /**
 426      * Get the most recent event time in the {@code EventQueue} which the {@code source}
 427      * belongs to.
 428      *
 429      * @param source the source of the event
 430      * @exception  IllegalArgumentException  if source is null.
 431      * @return most recent event time in the {@code EventQueue}
 432      */
 433     private static long getMostRecentEventTimeForSource(Object source) {
 434         if (source == null) {
 435             // throw the IllegalArgumentException to conform to EventObject spec
 436             throw new IllegalArgumentException("null source");
 437         }
 438         AppContext appContext = SunToolkit.targetToAppContext(source);
 439         EventQueue eventQueue = SunToolkit.getSystemEventQueueImplPP(appContext);
 440         return AWTAccessor.getEventQueueAccessor().getMostRecentEventTime(eventQueue);
 441     }
 442 }