home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / event / InputMethodEvent.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  8.5 KB  |  245 lines
  1. /*
  2.  * @(#)InputMethodEvent.java    1.7 98/03/18
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.awt.event;
  16.  
  17. import java.awt.AWTEvent;
  18. import java.awt.Component;
  19. import java.lang.Integer;
  20. import java.awt.font.TextHitInfo;
  21. import java.text.AttributedCharacterIterator;
  22. import java.text.CharacterIterator;
  23.  
  24. /**
  25.  * Input method events contain information about text that is being
  26.  * composed using an input method. Whenever the text changes, the
  27.  * input method sends an event to the text editing component that
  28.  * uses it.
  29.  *
  30.  * <p>
  31.  * The text included with the input method event consists of two parts:
  32.  * committed text and composed text. Either part may be empty. The two
  33.  * parts together replace any uncommitted composed text sent in previous events,
  34.  * or the currently selected committed text.
  35.  * Committed text should be integrated into the text component's persistent
  36.  * data, it will not be sent again. Composed text may be sent repeatedly,
  37.  * with changes to reflect the user's editing operations. Committed text
  38.  * always precedes composed text.
  39.  *
  40.  * @version 1.7 03/18/98
  41.  * @author JavaSoft Asia/Pacific
  42.  */
  43.  
  44. public class InputMethodEvent extends AWTEvent {
  45.  
  46.     /**
  47.      * Marks the first integer id for the range of input method event ids.
  48.      */
  49.     public static final int INPUT_METHOD_FIRST = 1100;
  50.  
  51.     /**
  52.      * The event type indicating changed input method text. This event is
  53.      * generated by input methods while processing input.
  54.      */
  55.     public static final int INPUT_METHOD_TEXT_CHANGED = INPUT_METHOD_FIRST;
  56.  
  57.     /**
  58.      * The event type indicating a changed insertion point in input method text.
  59.      * This event is
  60.      * generated by input methods while processing input if only the caret changed.
  61.      */
  62.     public static final int CARET_POSITION_CHANGED = INPUT_METHOD_FIRST + 1;
  63.  
  64.     /**
  65.      * Marks the last integer id for the range of input method event ids.
  66.      */
  67.     public static final int INPUT_METHOD_LAST = INPUT_METHOD_FIRST + 1;
  68.  
  69.     /**
  70.      * Constant indicating that the entire text sent with this event is committed.
  71.      */
  72.     public static final int ALL_CHARACTERS_COMMITTED = Integer.MAX_VALUE;
  73.  
  74.     // Text object
  75.     private AttributedCharacterIterator text;
  76.     private int committedCharacterCount;
  77.     private TextHitInfo caret;
  78.     private TextHitInfo visiblePosition;
  79.  
  80.     /**
  81.      * Constructs an InputMethodEvent with the specified source component, type,
  82.      * text, caret, and visiblePosition.
  83.      *
  84.      * @param source The object where the event originated.
  85.      * @param id The event type.
  86.      * @param text The combined committed and composed text, committed text first.
  87.      * @param committedCharacterCount The number of committed characters in the text, ALL_CHARACTERS_COMMITTED if all characters are committed.
  88.      * @param caret The caret (a.k.a. insertion point), with offset relative to <code>text</code>. Null if there's no caret.
  89.      * @param visiblePosition The position that's most important to be visible. Null if there's no recommendation.
  90.      */
  91.     public InputMethodEvent(Component source, int id,
  92.             AttributedCharacterIterator text, int committedCharacterCount,
  93.             TextHitInfo caret, TextHitInfo visiblePosition) {
  94.         super(source, id);
  95.         if (id < INPUT_METHOD_FIRST || id > INPUT_METHOD_LAST) {
  96.             throw new IllegalArgumentException("id outside of valid range");
  97.         }
  98.  
  99.         this.text = text;
  100.         int textLength = 0;
  101.         if (text != null) {
  102.             textLength = text.getEndIndex() - text.getBeginIndex();
  103.         }
  104.  
  105.         if (committedCharacterCount != ALL_CHARACTERS_COMMITTED &&
  106.                 (committedCharacterCount < 0 || committedCharacterCount > textLength)) {
  107.             throw new IllegalArgumentException("committedCharacterCount outside of valid range");
  108.         }
  109.         this.committedCharacterCount = committedCharacterCount;
  110.  
  111.         this.caret = caret;
  112.         this.visiblePosition = visiblePosition;
  113.    }
  114.  
  115.     /**
  116.      * Constructs an InputMethodEvent with the specified source component, type,
  117.      * caret, and visiblePosition.
  118.      *
  119.      * @param source The object where the event originated.
  120.      * @param id The event type.
  121.      * @param caret The caret (a.k.a. insertion point), with offset relative to <code>text</code>. Null if there's no caret.
  122.      * @param visiblePosition The position that's most important to be visible. Null if there's no recommendation.
  123.      */
  124.     public InputMethodEvent(Component source, int id, TextHitInfo caret,
  125.             TextHitInfo visiblePosition) {
  126.         this(source, id, null, 0, caret, visiblePosition);
  127.     }
  128.  
  129.     /**
  130.      * Gets the combined committed and composed text. If <code>getCommittedCharacterCount</code>
  131.      * returns ALL_CHARACTERS_COMMITTED, then the entire text is committed. Otherwise,
  132.      * Characters from offset 0 to offset <code>getCommittedCharacterCount()</code> are committed
  133.      * text, the remaining characters are composed text.
  134.      *
  135.      * @return the text
  136.      */
  137.     public AttributedCharacterIterator getText() {
  138.         return text;
  139.     }
  140.  
  141.     /**
  142.      * Gets the number of committed characters in the text. If all characters are committed,
  143.      * ALL_CHARACTERS_COMMITTED is returned.
  144.      */
  145.     public int getCommittedCharacterCount() {
  146.         return committedCharacterCount;
  147.     }
  148.  
  149.     /**
  150.      * Gets the caret. Null if there's no caret.
  151.      */
  152.     public TextHitInfo getCaret() {
  153.         return caret;
  154.     }
  155.  
  156.     /**
  157.      * Gets the position that's most important to be visible. Null if there's no recommendation.
  158.      */
  159.     public TextHitInfo getVisiblePosition() {
  160.         return visiblePosition;
  161.     }
  162.  
  163.     /**
  164.      * Consumes this event so that it will not be processed
  165.      * in the default manner by the source which originated it.
  166.      */
  167.     public void consume() {
  168.         consumed = true;
  169.     }
  170.  
  171.     /**
  172.      * Returns whether or not this event has been consumed.
  173.      * @see #consume
  174.      */
  175.     public boolean isConsumed() {
  176.         return consumed;
  177.     }
  178.     
  179.     /**
  180.      * Returns a parameter string identifying this event.
  181.      * This method is useful for event-logging and for debugging.
  182.      *
  183.      * @return a string identifying the event and its attributes
  184.      */
  185.     public String paramString() {
  186.         String typeStr;
  187.         switch(id) {
  188.           case INPUT_METHOD_TEXT_CHANGED:
  189.               typeStr = "INPUT_METHOD_TEXT_CHANGED";
  190.               break;
  191.           case CARET_POSITION_CHANGED:
  192.               typeStr = "CARET_POSITION_CHANGED";
  193.               break;
  194.           default:
  195.               typeStr = "unknown type";
  196.         }
  197.  
  198.         String textString;
  199.         if (text == null) {
  200.             textString = "no text";
  201.         } else {
  202.             StringBuffer textBuffer = new StringBuffer("\"");
  203.             int committedCharacterCount = this.committedCharacterCount;
  204.             if (committedCharacterCount == ALL_CHARACTERS_COMMITTED) {
  205.                 committedCharacterCount = text.getEndIndex() - text.getBeginIndex();
  206.             }
  207.             char c = text.first();
  208.             while (committedCharacterCount-- > 0) {
  209.                 textBuffer.append(c);
  210.                 c = text.next();
  211.             }
  212.             textBuffer.append("\" + \"");
  213.             while (c != CharacterIterator.DONE) {
  214.                 textBuffer.append(c);
  215.                 c = text.next();
  216.             }
  217.             textBuffer.append("\"");
  218.             textString = textBuffer.toString();
  219.         }
  220.         
  221.         String countString;
  222.         if (committedCharacterCount == ALL_CHARACTERS_COMMITTED) {
  223.             countString = "ALL_CHARACTERS_COMMITTED";
  224.         } else {
  225.             countString = committedCharacterCount + " characters committed";
  226.         }
  227.         
  228.         String caretString;
  229.         if (caret == null) {
  230.             caretString = "no caret";
  231.         } else {
  232.             caretString = "caret: " + caret.toString();
  233.         }
  234.         
  235.         String visiblePositionString;
  236.         if (visiblePosition == null) {
  237.             visiblePositionString = "no visible position";
  238.         } else {
  239.             visiblePositionString = "visible position: " + visiblePosition.toString();
  240.         }
  241.         
  242.         return typeStr + ", " + textString + ", " + countString + ", " + caretString + ", " + visiblePositionString;
  243.     }
  244. }
  245.