/*

 * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.awt.event;

import java.awt.AWTEvent;

import java.awt.Component;

import java.awt.EventQueue;

import java.awt.font.TextHitInfo;

import java.io.IOException;

import java.io.ObjectInputStream;

import java.text.AttributedCharacterIterator;

import java.text.CharacterIterator;

/**

 * Input method events contain information about text that is being

 * composed using an input method. Whenever the text changes, the

 * input method sends an event. If the text component that's currently

 * using the input method is an active client, the event is dispatched

 * to that component. Otherwise, it is dispatched to a separate

 * composition window.

 *

 * <p>

 * The text included with the input method event consists of two parts:

 * committed text and composed text. Either part may be empty. The two

 * parts together replace any uncommitted composed text sent in previous events,

 * or the currently selected committed text.

 * Committed text should be integrated into the text component's persistent

 * data, it will not be sent again. Composed text may be sent repeatedly,

 * with changes to reflect the user's editing operations. Committed text

 * always precedes composed text.

 *

 * @author JavaSoft Asia/Pacific

 * @since 1.2

 */

public class InputMethodEvent extends AWTEvent {

    /**

     * Serial Version ID.

     */

    private static final long serialVersionUID = 4727190874778922661L;

    /**

     * Marks the first integer id for the range of input method event ids.

     */

    public static final int INPUT_METHOD_FIRST = 1100;

    /**

     * The event type indicating changed input method text. This event is

     * generated by input methods while processing input.

     */

    public static final int INPUT_METHOD_TEXT_CHANGED = INPUT_METHOD_FIRST;

    /**

     * The event type indicating a changed insertion point in input method text.

     * This event is

     * generated by input methods while processing input if only the caret changed.

     */

    public static final int CARET_POSITION_CHANGED = INPUT_METHOD_FIRST + 1;

    /**

     * Marks the last integer id for the range of input method event ids.

     */

    public static final int INPUT_METHOD_LAST = INPUT_METHOD_FIRST + 1;

    /**

     * The time stamp that indicates when the event was created.

     *

     * @serial

     * @see #getWhen

     * @since 1.4

     */

    long when;

    // Text object

    private transient AttributedCharacterIterator text;

    private transient int committedCharacterCount;

    private transient TextHitInfo caret;

    private transient TextHitInfo visiblePosition;

    /**

     * Constructs an <code>InputMethodEvent</code> with the specified

     * source component, type, time, text, caret, and visiblePosition.

     * <p>

     * The offsets of caret and visiblePosition are relative to the current

     * composed text; that is, the composed text within <code>text</code>

     * if this is an <code>INPUT_METHOD_TEXT_CHANGED</code> event,

     * the composed text within the <code>text</code> of the

     * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event otherwise.

     * <p>Note that passing in an invalid <code>id</code> results in

     * unspecified behavior. This method throws an

     * <code>IllegalArgumentException</code> if <code>source</code>

     * is <code>null</code>.

     *

     * @param source the object where the event originated

     * @param id the event type

     * @param when a long integer that specifies the time the event occurred

     * @param text the combined committed and composed text,

     *      committed text first; must be <code>null</code>

     *      when the event type is <code>CARET_POSITION_CHANGED</code>;

     *      may be <code>null</code> for

     *      <code>INPUT_METHOD_TEXT_CHANGED</code> if there's no

     *      committed or composed text

     * @param committedCharacterCount the number of committed

     *      characters in the text

     * @param caret the caret (a.k.a. insertion point);

     *      <code>null</code> if there's no caret within current

     *      composed text

     * @param visiblePosition the position that's most important

     *      to be visible; <code>null</code> if there's no

     *      recommendation for a visible position within current

     *      composed text

     * @throws IllegalArgumentException if <code>id</code> is not

     *      in the range

     *      <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>;

     *      or if id is <code>CARET_POSITION_CHANGED</code> and

     *      <code>text</code> is not <code>null</code>;

     *      or if <code>committedCharacterCount</code> is not in the range

     *      <code>0</code>..<code>(text.getEndIndex() - text.getBeginIndex())</code>

     * @throws IllegalArgumentException if <code>source</code> is null

     *

     * @since 1.4

     */

    public InputMethodEvent(Component source, int id, long when,

            AttributedCharacterIterator text, int committedCharacterCount,

            TextHitInfo caret, TextHitInfo visiblePosition) {

        super(source, id);

        if (id < INPUT_METHOD_FIRST || id > INPUT_METHOD_LAST) {

            throw new IllegalArgumentException("id outside of valid range");

        }

        if (id == CARET_POSITION_CHANGED && text != null) {

            throw new IllegalArgumentException("text must be null for CARET_POSITION_CHANGED");

        }

        this.when = when;

        this.text = text;

        int textLength = 0;

        if (text != null) {

            textLength = text.getEndIndex() - text.getBeginIndex();

        }

        if (committedCharacterCount < 0 || committedCharacterCount > textLength) {

            throw new IllegalArgumentException("committedCharacterCount outside of valid range");

        }

        this.committedCharacterCount = committedCharacterCount;

        this.caret = caret;

        this.visiblePosition = visiblePosition;

   }

    /**

     * Constructs an <code>InputMethodEvent</code> with the specified

     * source component, type, text, caret, and visiblePosition.

     * <p>

     * The offsets of caret and visiblePosition are relative to the current

     * composed text; that is, the composed text within <code>text</code>

     * if this is an <code>INPUT_METHOD_TEXT_CHANGED</code> event,

     * the composed text within the <code>text</code> of the

     * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event otherwise.

     * The time stamp for this event is initialized by invoking

     * {@link java.awt.EventQueue#getMostRecentEventTime()}.

     * <p>Note that passing in an invalid <code>id</code> results in

     * unspecified behavior. This method throws an

     * <code>IllegalArgumentException</code> if <code>source</code>

     * is <code>null</code>.

     *

     * @param source the object where the event originated

     * @param id the event type

     * @param text the combined committed and composed text,

     *      committed text first; must be <code>null</code>

     *      when the event type is <code>CARET_POSITION_CHANGED</code>;

     *      may be <code>null</code> for

     *      <code>INPUT_METHOD_TEXT_CHANGED</code> if there's no

     *      committed or composed text

     * @param committedCharacterCount the number of committed

     *      characters in the text

     * @param caret the caret (a.k.a. insertion point);

     *      <code>null</code> if there's no caret within current

     *      composed text

     * @param visiblePosition the position that's most important

     *      to be visible; <code>null</code> if there's no

     *      recommendation for a visible position within current

     *      composed text

     * @throws IllegalArgumentException if <code>id</code> is not

     *      in the range

     *      <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>;

     *      or if id is <code>CARET_POSITION_CHANGED</code> and

     *      <code>text</code> is not <code>null</code>;

     *      or if <code>committedCharacterCount</code> is not in the range

     *      <code>0</code>..<code>(text.getEndIndex() - text.getBeginIndex())</code>

     * @throws IllegalArgumentException if <code>source</code> is null

     */

    public InputMethodEvent(Component source, int id,

            AttributedCharacterIterator text, int committedCharacterCount,

            TextHitInfo caret, TextHitInfo visiblePosition) {

        this(source, id, EventQueue.getMostRecentEventTime(), text,

             committedCharacterCount, caret, visiblePosition);

    }

    /**

     * Constructs an <code>InputMethodEvent</code> with the

     * specified source component, type, caret, and visiblePosition.

     * The text is set to <code>null</code>,

     * <code>committedCharacterCount</code> to 0.

     * <p>

     * The offsets of <code>caret</code> and <code>visiblePosition</code>

     * are relative to the current composed text; that is,

     * the composed text within the <code>text</code> of the

     * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event if the

     * event being constructed as a <code>CARET_POSITION_CHANGED</code> event.

     * For an <code>INPUT_METHOD_TEXT_CHANGED</code> event without text,

     * <code>caret</code> and <code>visiblePosition</code> must be

     * <code>null</code>.

     * The time stamp for this event is initialized by invoking

     * {@link java.awt.EventQueue#getMostRecentEventTime()}.

     * <p>Note that passing in an invalid <code>id</code> results in

     * unspecified behavior. This method throws an

     * <code>IllegalArgumentException</code> if <code>source</code>

     * is <code>null</code>.

     *

     * @param source the object where the event originated

     * @param id the event type

     * @param caret the caret (a.k.a. insertion point);

     *      <code>null</code> if there's no caret within current

     *      composed text

     * @param visiblePosition the position that's most important

     *      to be visible; <code>null</code> if there's no

     *      recommendation for a visible position within current

     *      composed text

     * @throws IllegalArgumentException if <code>id</code> is not

     *      in the range

     *      <code>INPUT_METHOD_FIRST</code>..<code>INPUT_METHOD_LAST</code>

     * @throws IllegalArgumentException if <code>source</code> is null

     */

    public InputMethodEvent(Component source, int id, TextHitInfo caret,

            TextHitInfo visiblePosition) {

        this(source, id, EventQueue.getMostRecentEventTime(), null,

             0, caret, visiblePosition);

    }

    /**

     * Gets the combined committed and composed text.

     * Characters from index 0 to index <code>getCommittedCharacterCount() - 1</code> are committed

     * text, the remaining characters are composed text.

     *

     * @return the text.

     * Always null for CARET_POSITION_CHANGED;

     * may be null for INPUT_METHOD_TEXT_CHANGED if there's no composed or committed text.

     */

    public AttributedCharacterIterator getText() {

        return text;

    }

    /**

     * Gets the number of committed characters in the text.

     */

    public int getCommittedCharacterCount() {

        return committedCharacterCount;

    }

    /**

     * Gets the caret.

     * <p>

     * The offset of the caret is relative to the current

     * composed text; that is, the composed text within getText()

     * if this is an <code>INPUT_METHOD_TEXT_CHANGED</code> event,

     * the composed text within getText() of the

     * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event otherwise.

     *

     * @return the caret (a.k.a. insertion point).

     * Null if there's no caret within current composed text.

     */

    public TextHitInfo getCaret() {

        return caret;

    }

    /**

     * Gets the position that's most important to be visible.

     * <p>

     * The offset of the visible position is relative to the current

     * composed text; that is, the composed text within getText()

     * if this is an <code>INPUT_METHOD_TEXT_CHANGED</code> event,

     * the composed text within getText() of the

     * preceding <code>INPUT_METHOD_TEXT_CHANGED</code> event otherwise.

     *

     * @return the position that's most important to be visible.

     * Null if there's no recommendation for a visible position within current composed text.

     */

    public TextHitInfo getVisiblePosition() {

        return visiblePosition;

    }

    /**

     * Consumes this event so that it will not be processed

     * in the default manner by the source which originated it.

     */

    public void consume() {

        consumed = true;

    }

    /**

     * Returns whether or not this event has been consumed.

     * @see #consume

     */

    public boolean isConsumed() {

        return consumed;

    }

    /**

     * Returns the time stamp of when this event occurred.

     *

     * @return this event's timestamp

     * @since 1.4

     */

    public long getWhen() {

      return when;

    }

    /**

     * Returns a parameter string identifying this event.

     * This method is useful for event-logging and for debugging.

     * It contains the event ID in text form, the characters of the

     * committed and composed text

     * separated by "+", the number of committed characters,

     * the caret, and the visible position.

     *

     * @return a string identifying the event and its attributes

     */

    public String paramString() {

        String typeStr;

        switch(id) {

          case INPUT_METHOD_TEXT_CHANGED:

              typeStr = "INPUT_METHOD_TEXT_CHANGED";

              break;

          case CARET_POSITION_CHANGED:

              typeStr = "CARET_POSITION_CHANGED";

              break;

          default:

              typeStr = "unknown type";

        }

        String textString;

        if (text == null) {

            textString = "no text";

        } else {

            StringBuilder textBuffer = new StringBuilder("\"");

            int committedCharacterCount = this.committedCharacterCount;

            char c = text.first();

            while (committedCharacterCount-- > 0) {

                textBuffer.append(c);

                c = text.next();

            }

            textBuffer.append("\" + \"");

            while (c != CharacterIterator.DONE) {

                textBuffer.append(c);

                c = text.next();

            }

            textBuffer.append("\"");

            textString = textBuffer.toString();

        }

        String countString = committedCharacterCount + " characters committed";

        String caretString;

        if (caret == null) {

            caretString = "no caret";

        } else {

            caretString = "caret: " + caret.toString();

        }

        String visiblePositionString;

        if (visiblePosition == null) {

            visiblePositionString = "no visible position";

        } else {

            visiblePositionString = "visible position: " + visiblePosition.toString();

        }

        return typeStr + ", " + textString + ", " + countString + ", " + caretString + ", " + visiblePositionString;

    }

    /**

     * Initializes the <code>when</code> field if it is not present in the

     * object input stream. In that case, the field will be initialized by

     * invoking {@link java.awt.EventQueue#getMostRecentEventTime()}.

     */

    private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException {

        s.defaultReadObject();

        if (when == 0) {

            when = EventQueue.getMostRecentEventTime();

        }

    }

}