libjava/classpath/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., 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 gnu.java.lang.CPStringBuilder;
  42
  43 import java.awt.AWTEvent;
  44 import java.awt.Component;
  45 import java.awt.EventQueue;
  46 import java.awt.font.TextHitInfo;
  47 import java.io.IOException;
  48 import java.io.ObjectInputStream;
  49 import java.text.AttributedCharacterIterator;
  50
  51 /**
  52  * This class is for event generated by change in a text input method.
  53  *
  54  * @author Aaron M. Renn (arenn@urbanophile.com)
  55  * @see InputMethodListener
  56  * @since 1.2
  57  * @status updated to 1.4
  58  */
  59 public class InputMethodEvent extends AWTEvent
  60 {
  61   /**
  62    * Compatible with JDK 1.2+.
  63    */
  64   private static final long serialVersionUID = 4727190874778922661L;
  65
  66   /** This is the first id in the range of event ids used by this class. */
  67   public static final int INPUT_METHOD_FIRST = 1100;
  68
  69   /** This event id indicates that the text in the input method has changed. */
  70   public static final int INPUT_METHOD_TEXT_CHANGED = 1100;
  71
  72   /** This event id indicates that the input method curor point has changed. */
  73   public static final int CARET_POSITION_CHANGED = 1101;
  74
  75   /** This is the last id in the range of event ids used by this class. */
  76   public static final int INPUT_METHOD_LAST = 1101;
  77
  78   /**
  79    * The timestamp when this event was created.
  80    *
  81    * @serial the timestamp
  82    * @since 1.4
  83    */
  84   private long when;
  85
  86   /** The input method text. */
  87   private final transient AttributedCharacterIterator text;
  88
  89   /** The number of committed characters in the text. */
  90   private final transient int committedCharacterCount;
  91
  92   /** The caret. */
  93   private final transient TextHitInfo caret;
  94
  95   /** The most important position to be visible. */
  96   private final transient TextHitInfo visiblePosition;
  97
  98   /**
  99    * Initializes a new instance of <code>InputMethodEvent</code> with the
 100    * specified source, id, timestamp, text, char count, caret, and visible
 101    * position.
 102    *
 103    * @param source the source that generated the event
 104    * @param id the event id
 105    * @param when the timestamp of the event
 106    * @param text the input text
 107    * @param committedCharacterCount the number of committed characters
 108    * @param caret the caret position
 109    * @param visiblePosition the position most important to make visible
 110    * @throws IllegalArgumentException if source is null, id is invalid, id is
 111    *         CARET_POSITION_CHANGED and text is non-null, or if
 112    *         committedCharacterCount is out of range
 113    * @since 1.4
 114    */
 115   public InputMethodEvent(Component source, int id, long when,
 116                           AttributedCharacterIterator text,
 117                           int committedCharacterCount, TextHitInfo caret,
 118                           TextHitInfo visiblePosition)
 119   {
 120     super(source, id);
 121     this.when = when;
 122     this.text = text;
 123     this.committedCharacterCount = committedCharacterCount;
 124     this.caret = caret;
 125     this.visiblePosition = visiblePosition;
 126     if (id < INPUT_METHOD_FIRST || id > INPUT_METHOD_LAST
 127         || (id == CARET_POSITION_CHANGED && text != null)
 128         || committedCharacterCount < 0
 129         || (committedCharacterCount
 130             > (text == null ? 0 : text.getEndIndex() - text.getBeginIndex())))
 131       throw new IllegalArgumentException();
 132   }
 133
 134   /**
 135    * Initializes a new instance of <code>InputMethodEvent</code> with the
 136    * specified source, id, text, char count, caret, and visible position.
 137    *
 138    * @param source the source that generated the event
 139    * @param id the event id
 140    * @param text the input text
 141    * @param committedCharacterCount the number of committed characters
 142    * @param caret the caret position
 143    * @param visiblePosition the position most important to make visible
 144    * @throws IllegalArgumentException if source is null, id is invalid, id is
 145    *         CARET_POSITION_CHANGED and text is non-null, or if
 146    *         committedCharacterCount is out of range
 147    * @since 1.4
 148    */
 149   public InputMethodEvent(Component source, int id,
 150                           AttributedCharacterIterator text,
 151                           int committedCharacterCount, TextHitInfo caret,
 152                           TextHitInfo visiblePosition)
 153   {
 154     this(source, id, EventQueue.getMostRecentEventTime(), text,
 155          committedCharacterCount, caret, visiblePosition);
 156   }
 157
 158   /**
 159    * Initializes a new instance of <code>InputMethodEvent</code> with the
 160    * specified source, id, caret, and visible position, and with a null
 161    * text and char count.
 162    *
 163    * @param source the source that generated the event
 164    * @param id the event id
 165    * @param caret the caret position
 166    * @param visiblePosition the position most important to make visible
 167    * @throws IllegalArgumentException if source is null or id is invalid
 168    * @since 1.4
 169    */
 170   public InputMethodEvent(Component source, int id, TextHitInfo caret,
 171                           TextHitInfo visiblePosition)
 172   {
 173     this(source, id, EventQueue.getMostRecentEventTime(), null, 0, caret,
 174          visiblePosition);
 175   }
 176
 177   /**
 178    * This method returns the input method text. This can be <code>null</code>,
 179    * and will always be null for <code>CARET_POSITION_CHANGED</code> events.
 180    * Characters from 0 to <code>getCommittedCharacterCount()-1</code> have
 181    * been committed, the remaining characters are composed text.
 182    *
 183    * @return the input method text, or null
 184    */
 185   public AttributedCharacterIterator getText()
 186   {
 187     return text;
 188   }
 189
 190   /**
 191    * Returns the number of committed characters in the input method text.
 192    *
 193    * @return the number of committed characters in the input method text
 194    */
 195   public int getCommittedCharacterCount()
 196   {
 197     return committedCharacterCount;
 198   }
 199
 200   /**
 201    * Returns the caret position. The caret offset is relative to the composed
 202    * text of the most recent <code>INPUT_METHOD_TEXT_CHANGED</code> event.
 203    *
 204    * @return the caret position, or null
 205    */
 206   public TextHitInfo getCaret()
 207   {
 208     return caret;
 209   }
 210
 211   /**
 212    * Returns the position that is most important to be visible, or null if
 213    * such a hint is not necessary. The caret offset is relative to the composed
 214    * text of the most recent <code>INPUT_METHOD_TEXT_CHANGED</code> event.
 215    *
 216    * @return the position that is most important to be visible
 217    */
 218   public TextHitInfo getVisiblePosition()
 219   {
 220     return visiblePosition;
 221   }
 222
 223   /**
 224    * This method consumes the event.  A consumed event is not processed
 225    * in the default manner by the component that generated it.
 226    */
 227   public void consume()
 228   {
 229     consumed = true;
 230   }
 231
 232   /**
 233    * This method tests whether or not this event has been consumed.
 234    *
 235    * @return true if the event has been consumed
 236    */
 237   public boolean isConsumed()
 238   {
 239     return consumed;
 240   }
 241
 242   /**
 243    * Return the timestamp of this event.
 244    *
 245    * @return the timestamp
 246    * @since 1.4
 247    */
 248   public long getWhen()
 249   {
 250     return when;
 251   }
 252
 253   /**
 254    * This method returns a string identifying the event. This contains the
 255    * event ID, the committed and composed characters separated by '+', the
 256    * number of committed characters, the caret, and the visible position.
 257    *
 258    * @return a string identifying the event
 259    */
 260   public String paramString()
 261   {
 262     CPStringBuilder s
 263       = new CPStringBuilder(80 + (text == null ? 0
 264                                : text.getEndIndex() - text.getBeginIndex()));
 265     s.append(id == INPUT_METHOD_TEXT_CHANGED ? "INPUT_METHOD_TEXT_CHANGED, "
 266              : "CARET_POSITION_CHANGED, ");
 267     if (text == null)
 268       s.append("no text, 0 characters committed, caret: ");
 269     else
 270       {
 271         s.append('"');
 272         int i = text.getBeginIndex();
 273         int j = committedCharacterCount;
 274         while (--j >= 0)
 275           s.append(text.setIndex(i++));
 276         s.append("\" + \"");
 277         j = text.getEndIndex() - i;
 278         while (--j >= 0)
 279           s.append(text.setIndex(i++));
 280         s.append("\", ").append(committedCharacterCount)
 281           .append(" characters committed, caret: ");
 282       }
 283     s.append(caret == null ? (Object) "no caret" : caret).append(", ")
 284       .append(visiblePosition == null ? (Object) "no visible position"
 285               : visiblePosition);
 286     return s.toString();
 287   }
 288
 289   /**
 290    * Reads in the object from a serial stream, updating when to
 291    * {@link EventQueue#getMostRecentEventTime()} if necessary.
 292    *
 293    * @param s the stream to read from
 294    * @throws IOException if deserialization fails
 295    * @throws ClassNotFoundException if deserialization fails
 296    * @serialData default, except for updating when
 297    */
 298   private void readObject(ObjectInputStream s)
 299     throws IOException, ClassNotFoundException
 300   {
 301     s.defaultReadObject();
 302     if (when == 0)
 303       when = EventQueue.getMostRecentEventTime();
 304   }
 305 } // class InputMethodEvent