Java 1.2 How-To/JavaHowTo.iso/3rdParty/jbuilder/unsupported/JDK1.2beta3/SOURCE/SRC.ZIP/java/awt/im/InputMethodRequests.java

Java Source | 1998-03-20 | 5.9 KB | 137 lines

/*
 * @(#)InputMethodRequests.java    1.8 98/03/18
 *
 * Copyright 1997 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

package java.awt.im;

import java.awt.Rectangle;
import java.awt.font.TextHitInfo;
import java.text.AttributedCharacterIterator;

/**
 * InputMethodRequests defines the requests that a text editing component
 * has to handle in order to work with input methods. The component
 * can implement this interface itself or use a separate object that
 * implements it. The object implementing this interface must be returned
 * from the component's getInputMethodRequests method.
 *
 * <p>
 * The text editing component also has to provide an input method event
 * listener.
 *
 * @see java.awt.Component#getInputMethodRequests
 * @see java.awt.event.InputMethodListener
 *
 * @version 1.2 05/16/97
 * @author JavaSoft Asia/Pacific
 */

public interface InputMethodRequests {

    /**
     * Gets the location of a specified offset in the current composed text.
     * This information is, for example, used to position the candidate window near the
     * composed text. The offset is relative to the composed text, so offset 0
     * indicates the beginning of the composed text.
     * The location is represented as a 0-thickness caret, that is, it has 0 width if the
     * text is drawn horizontally, and 0 height if the text is drawn vertically. Other
     * text orientations need to be mapped to horizontal or vertical orientation. The
     * rectangle uses absolute screen coordinates.
     *
     * @param offset The offset within the composed text.
     * @return A rectangle representing the screen location of the offset.
     */
    Rectangle getOffsetLocation(TextHitInfo offset);

    /**
     * Gets the offset within the composed text for the specified absolute x and y
     * coordinates on the screen. This information is used, for example to handle mouse
     * clicks and the mouse cursor. The offset is relative to the composed text, so offset 0
     * indicates the beginning of the composed text.
     *
     * <p>
     * Return null if the location is outside the area occupied by the composed text.
     *
     * @param x The absolute x coordinate on screen.
     * @param y The absolute y coordinate on screen.
     * @return Text hit info about the offset in the composed text.
     */
    TextHitInfo getLocationOffset(int x, int y);

    /**
     * Gets the offset of the insert position in the committed text contained in the text
     * editing component. This is the offset at which characters entered through an input
     * method are inserted. This information is used by an input method, for example, to examine
     * the text surrounding the insert position.
     *
     * @return The offset of the insert position.
     */
    int getInsertPositionOffset();

    /**
     * Gets an iterator providing access to the entire text and attributes contained in the
     * text editing component except for uncommitted text. Uncommitted (composed) text should be ignored
     * for index calculations and should not be made accessible through the iterator.
     * The input method may provide a list of names of attributes that it is interested in.
     * In that case, information about other attributes that the implementor may have need
     * not be made accessible through the iterator. If the list is null, all available
     * attribute information should be made accessible.
     *
     * @param beginIndex the index of the first character
     * @param endIndex the index of the character following the last character
     * @param attributeNames a list of attributes that the input method is interested in
     * @return an iterator providing access to the text and its attributes
     */
    AttributedCharacterIterator getCommittedText(int beginIndex, int endIndex, String[] attributeNames);

    /**
     * Gets the length of the entire text contained in the text
     * editing component except for uncommitted (composed) text.
     *
     * @return length of text
     */
    int getCommittedTextLength();

    /**
     * Gets the latest committed text from the text editing component and removes
     * it from the component's text body.
     * This is used for the "Undo Commit" feature in some input methods, where the
     * committed text reverts to its previous composed state. The composed text will
     * be sent to the component using an InputMethodEvent.
     *
     * <p>
     * Generally, this feature should only be supported immediately after the text was
     * committed, not after the user performed other operations on the text. When the
     * feature is not supported, return null.
     *
     * @return The latest committed text, or null when the "Undo Commit" feature is not supported.
     */
    AttributedCharacterIterator cancelLatestCommittedText(String[] attributeNames);

    /**
     * Gets the currently selected text from the text editing component.
     * This is used for the "Reconvert" feature in some input methods. Typically,
     * the input method will send an input method event to replace the selected text
     * with composed text. Depending on the input method's capabilities, this may be
     * the original composed text for the selected text, the latest composed text
     * entered anywhere in the text, or a version of the text that's converted back
     * from the selected text.
     *
     * <p>
     * If a text component doesn't support this feature, return null.
     *
     * @return The currently selected text, or null when the "Reconvert" feature is not supported.
     */
    AttributedCharacterIterator getSelectedText(String[] attributeNames);
}