inputmethod.java

Mobile 应用程序使用 Java Micro Edition (Java ME) 平台

/*
 * @(#)InputMethod.java	1.31 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package java.awt.im.spi;

import java.util.Locale;
import java.awt.AWTEvent;
import java.awt.Rectangle;
import java.lang.Character.Subset;


/**
 * Defines the interface for an input method that supports complex text input.
 * Input methods traditionally support text input for languages that have
 * more characters than can be represented on a standard-size keyboard,
 * such as Chinese, Japanese, and Korean. However, they may also be used to
 * support phonetic text input for English or character reordering for Thai.
 * <p>
 * Subclasses of InputMethod can be loaded by the input method framework; they
 * can then be selected either through the API
 * ({@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod})
 * or the user interface (the input method selection menu).
 *
 * @since 1.3
 *
 * @version 	1.31, 11/17/05
 * @author JavaSoft International
 */

public interface InputMethod {

    /**
     * Sets the input method context, which is used to dispatch input method
     * events to the client component and to request information from
     * the client component.
     * <p>
     * This method is called once immediately after instantiating this input
     * method.
     *
     * @param context the input method context for this input method
     * @exception NullPointerException if <code>context</code> is null
     */
    public void setInputMethodContext(InputMethodContext context);

    /**
     * Attempts to set the input locale. If the input method supports the
     * desired locale, it changes its behavior to support input for the locale
     * and returns true.
     * Otherwise, it returns false and does not change its behavior.
     * <p>
     * This method is called
     * <ul>
     * <li>by {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
     * <li>when switching to this input method through the user interface if the user
     *     specified a locale or if the previously selected input method's
     *     {@link java.awt.im.spi.InputMethod#getLocale getLocale} method
     *     returns a non-null value.
     * </ul>
     *
     * @param locale locale to input
     * @return whether the specified locale is supported
     * @exception NullPointerException if <code>locale</code> is null
     */
    public boolean setLocale(Locale locale);

    /**
     * Returns the current input locale. Might return null in exceptional cases.
     * <p>
     * This method is called
     * <ul>
     * <li>by {@link java.awt.im.InputContext#getLocale InputContext.getLocale} and
     * <li>when switching from this input method to a different one through the
     *     user interface.
     * </ul>
     *
     * @return the current input locale, or null
     */
    public Locale getLocale();
    
    /**
     * Sets the subsets of the Unicode character set that this input method
     * is allowed to input. Null may be passed in to indicate that all
     * characters are allowed.
     * <p>
     * This method is called
     * <ul>
     * <li>immediately after instantiating this input method,
     * <li>when switching to this input method from a different one, and
     * <li>by {@link java.awt.im.InputContext#setCharacterSubsets InputContext.setCharacterSubsets}.
     * </ul>
     *
     * @param subsets the subsets of the Unicode character set from which
     * characters may be input
     */
    public void setCharacterSubsets(Subset[] subsets);

    /**
     * Enables or disables this input method for composition,
     * depending on the value of the parameter <code>enable</code>.
     * <p>
     * An input method that is enabled for composition interprets incoming
     * events for both composition and control purposes, while a
     * disabled input method does not interpret events for composition.
     * Note however that events are passed on to the input method regardless
     * whether it is enabled or not, and that an input method that is disabled
     * for composition may still interpret events for control purposes,
     * including to enable or disable itself for composition.
     * <p>
     * For input methods provided by host operating systems, it is not always possible to 
     * determine whether this operation is supported. For example, an input method may enable
     * composition only for some locales, and do nothing for other locales. For such input 
     * methods, it is possible that this method does not throw 
     * {@link java.lang.UnsupportedOperationException UnsupportedOperationException},
     * but also does not affect whether composition is enabled.
     * <p>
     * This method is called
     * <ul>
     * <li>by {@link java.awt.im.InputContext#setCompositionEnabled InputContext.setCompositionEnabled},
     * <li>when switching to this input method from a different one using the
     *     user interface or
     *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
     *     if the previously selected input method's
     *     {@link java.awt.im.spi.InputMethod#isCompositionEnabled isCompositionEnabled}
     *     method returns without throwing an exception.
     * </ul>
     *
     * @param enable whether to enable the input method for composition
     * @throws UnsupportedOperationException if this input method does not
     * support the enabling/disabling operation
     * @see #isCompositionEnabled
     */
    public void setCompositionEnabled(boolean enable);

    /**
     * Determines whether this input method is enabled.
     * An input method that is enabled for composition interprets incoming
     * events for both composition and control purposes, while a
     * disabled input method does not interpret events for composition.
     * <p>
     * This method is called
     * <ul>
     * <li>by {@link java.awt.im.InputContext#isCompositionEnabled InputContext.isCompositionEnabled} and
     * <li>when switching from this input method to a different one using the
     *     user interface or
     *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
     * </ul>
     *
     * @return <code>true</code> if this input method is enabled for
     * composition; <code>false</code> otherwise.
     * @throws UnsupportedOperationException if this input method does not
     * support checking whether it is enabled for composition
     * @see #setCompositionEnabled
     */
    public boolean isCompositionEnabled();

    /**
     * Starts the reconversion operation. The input method obtains the
     * text to be reconverted from the current client component using the
     * {@link java.awt.im.InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText}
     * method. It can use other <code>InputMethodRequests</code>
     * methods to request additional information required for the
     * reconversion operation. The composed and committed text
     * produced by the operation is sent to the client component as a
     * sequence of <code>InputMethodEvent</code>s. If the given text
     * cannot be reconverted, the same text should be sent to the
     * client component as committed text.
     * <p>
     * This method is called by
     * {@link java.awt.im.InputContext#reconvert() InputContext.reconvert}.
     *
     * @throws UnsupportedOperationException if the input method does not
     * support the reconversion operation.
     */
    public void reconvert();

    /**
     * Dispatches the event to the input method. If input method support is
     * enabled for the focussed component, incoming events of certain types
     * are dispatched to the current input method for this component before