libjava/java/awt/event/InputMethodEvent.java

   1 /* InputMethodEvent.java -- events from a text input method
   2    Copyright (C) 1999, 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt.event;
  40
  41 import java.awt.AWTEvent;
  42 import java.awt.Component;
  43 import java.awt.EventQueue;
  44 import java.awt.font.TextHitInfo;
  45 import java.io.IOException;
  46 import java.io.ObjectInputStream;
  47 import java.text.AttributedCharacterIterator;
  48
  49 /**
  50  * This class is for event generated by change in a text input method.
  51  *
  52  * @author Aaron M. Renn (arenn@urbanophile.com)
  53  * @see InputMethodListener
  54  * @since 1.2
  55  * @status updated to 1.4
  56  */
  57 public class InputMethodEvent extends AWTEvent
  58 {
  59   /**
  60    * Compatible with JDK 1.2+.
  61    */
  62   private static final long serialVersionUID = 4727190874778922661L;
  63
  64   /** This is the first id in the range of event ids used by this class. */
  65   public static final int INPUT_METHOD_FIRST = 1100;
  66
  67   /** This event id indicates that the text in the input method has changed. */
  68   public static final int INPUT_METHOD_TEXT_CHANGED = 1100;
  69
  70   /** This event id indicates that the input method curor point has changed. */
  71   public static final int CARET_POSITION_CHANGED = 1101;
  72
  73   /** This is the last id in the range of event ids used by this class. */
  74   public static final int INPUT_METHOD_LAST = 1101;
  75
  76   /**
  77    * The timestamp when this event was created.
  78    *
  79    * @serial the timestamp
  80    * @since 1.4
  81    */
  82   private long when;
  83
  84   /** The input method text. */
  85   private final transient AttributedCharacterIterator text;
  86
  87   /** The number of committed characters in the text. */
  88   private final transient int committedCharacterCount;
  89
  90   /** The caret. */
  91   private final transient TextHitInfo caret;
  92
  93   /** The most important position to be visible. */
  94   private final transient TextHitInfo visiblePosition;
  95
  96   /**
  97    * Initializes a new instance of <code>InputMethodEvent</code> with the
  98    * specified source, id, timestamp, text, char count, caret, and visible
  99    * position.
 100    *
 101    * @param source the source that generated the event
 102    * @param id the event id
 103    * @param when the timestamp of the event
 104    * @param text the input text
 105    * @param committedCharacterCount the number of committed characters
 106    * @param caret the caret position
 107    * @param visiblePosition the position most important to make visible
 108    * @throws IllegalArgumentException if source is null, id is invalid, id is
 109    *         CARET_POSITION_CHANGED and text is non-null, or if
 110    *         committedCharacterCount is out of range
 111    * @since 1.4
 112    */
 113   public InputMethodEvent(Component source, int id, long when,
 114                           AttributedCharacterIterator text,
 115                           int committedCharacterCount, TextHitInfo caret,
 116                           TextHitInfo visiblePosition)
 117   {
 118     super(source, id);
 119     this.when = when;
 120     this.text = text;
 121     this.committedCharacterCount = committedCharacterCount;
 122     this.caret = caret;
 123     this.visiblePosition = visiblePosition;
 124     if (id < INPUT_METHOD_FIRST || id > INPUT_METHOD_LAST
 125         || (id == CARET_POSITION_CHANGED && text != null)
 126         || committedCharacterCount < 0
 127         || (committedCharacterCount
 128             > (text == null ? 0 : text.getEndIndex() - text.getBeginIndex())))
 129       throw new IllegalArgumentException();
 130   }
 131
 132   /**
 133    * Initializes a new instance of <code>InputMethodEvent</code> with the
 134    * specified source, id, text, char count, caret, and visible position.
 135    *
 136    * @param source the source that generated the event
 137    * @param id the event id
 138    * @param text the input text
 139    * @param committedCharacterCount the number of committed characters
 140    * @param caret the caret position
 141    * @param visiblePosition the position most important to make visible
 142    * @throws IllegalArgumentException if source is null, id is invalid, id is
 143    *         CARET_POSITION_CHANGED and text is non-null, or if
 144    *         committedCharacterCount is out of range
 145    * @since 1.4
 146    */
 147   public InputMethodEvent(Component source, int id,
 148                           AttributedCharacterIterator text,
 149                           int committedCharacterCount, TextHitInfo caret,
 150                           TextHitInfo visiblePosition)
 151   {
 152     this(source, id, EventQueue.getMostRecentEventTime(), text,
 153          committedCharacterCount, caret, visiblePosition);
 154   }
 155
 156   /**
 157    * Initializes a new instance of <code>InputMethodEvent</code> with the
 158    * specified source, id, caret, and visible position, and with a null
 159    * text and char count.
 160    *
 161    * @param source the source that generated the event
 162    * @param id the event id
 163    * @param caret the caret position
 164    * @param visiblePosition the position most important to make visible
 165    * @throws IllegalArgumentException if source is null or id is invalid
 166    * @since 1.4
 167    */
 168   public InputMethodEvent(Component source, int id, TextHitInfo caret,
 169                           TextHitInfo visiblePosition)
 170   {
 171     this(source, id, EventQueue.getMostRecentEventTime(), null, 0, caret,
 172          visiblePosition);
 173   }
 174
 175   /**
 176    * This method returns the input method text. This can be <code>null</code>,
 177    * and will always be null for <code>CARET_POSITION_CHANGED</code> events.
 178    * Characters from 0 to <code>getCommittedCharacterCount()-1</code> have
 179    * been committed, the remaining characters are composed text.
 180    *
 181    * @return the input method text, or null
 182    */
 183   public AttributedCharacterIterator getText()
 184   {
 185     return text;
 186   }
 187
 188   /**
 189    * Returns the number of committed characters in the input method text.
 190    *
 191    * @return the number of committed characters in the input method text
 192    */
 193   public int getCommittedCharacterCount()
 194   {
 195     return committedCharacterCount;
 196   }
 197
 198   /**
 199    * Returns the caret position. The caret offset is relative to the composed
 200    * text of the most recent <code>INPUT_METHOD_TEXT_CHANGED</code> event.
 201    *
 202    * @return the caret position, or null
 203    */
 204   public TextHitInfo getCaret()
 205   {
 206     return caret;
 207   }
 208
 209   /**
 210    * Returns the position that is most important to be visible, or null if
 211    * such a hint is not necessary. The caret offset is relative to the composed
 212    * text of the most recent <code>INPUT_METHOD_TEXT_CHANGED</code> event.
 213    *
 214    * @return the position that is most important to be visible
 215    */
 216   public TextHitInfo getVisiblePosition()
 217   {
 218     return visiblePosition;
 219   }
 220
 221   /**
 222    * This method consumes the event.  A consumed event is not processed
 223    * in the default manner by the component that generated it.
 224    */
 225   public void consume()
 226   {
 227     consumed = true;
 228   }
 229
 230   /**
 231    * This method tests whether or not this event has been consumed.
 232    *
 233    * @return true if the event has been consumed
 234    */
 235   public boolean isConsumed()
 236   {
 237     return consumed;
 238   }
 239
 240   /**
 241    * Return the timestamp of this event.
 242    *
 243    * @return the timestamp
 244    * @since 1.4
 245    */
 246   public long getWhen()
 247   {
 248     return when;
 249   }
 250
 251   /**
 252    * This method returns a string identifying the event. This contains the
 253    * event ID, the committed and composed characters separated by '+', the
 254    * number of committed characters, the caret, and the visible position.
 255    *
 256    * @return a string identifying the event
 257    */
 258   public String paramString()
 259   {
 260     StringBuffer s
 261       = new StringBuffer(80 + (text == null ? 0
 262                                : text.getEndIndex() - text.getBeginIndex()));
 263     s.append(id == INPUT_METHOD_TEXT_CHANGED ? "INPUT_METHOD_TEXT_CHANGED, "
 264              : "CARET_POSITION_CHANGED, ");
 265     if (text == null)
 266       s.append("no text, 0 characters committed, caret: ");
 267     else
 268       {
 269         s.append('"');
 270         int i = text.getBeginIndex();
 271         int j = committedCharacterCount;
 272         while (--j >= 0)
 273           s.append(text.setIndex(i++));
 274         s.append("\" + \"");
 275         j = text.getEndIndex() - i;
 276         while (--j >= 0)
 277           s.append(text.setIndex(i++));
 278         s.append("\", ").append(committedCharacterCount)
 279           .append(" characters committed, caret: ");
 280       }
 281     s.append(caret == null ? (Object) "no caret" : caret).append(", ")
 282       .append(visiblePosition == null ? (Object) "no visible position"
 283               : visiblePosition);
 284     return s.toString();
 285   }
 286
 287   /**
 288    * Reads in the object from a serial stream, updating when to
 289    * {@link EventQueue#getMostRecentEventTime()} if necessary.
 290    *
 291    * @param s the stream to read from
 292    * @throws IOException if deserialization fails
 293    * @throws ClassNotFoundException if deserialization fails
 294    * @serialData default, except for updating when
 295    */
 296   private void readObject(ObjectInputStream s)
 297     throws IOException, ClassNotFoundException
 298   {
 299     s.defaultReadObject();
 300     if (when == 0)
 301       when = EventQueue.getMostRecentEventTime();
 302   }
 303 } // class InputMethodEvent