Source for java.awt.event.InputMethodEvent

   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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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