source: trunk/gcc/libjava/java/awt/im/spi/InputMethod.java

/* InputMethod.java -- defines an interface for complex text input
   Copyright (C) 2002 Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath 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 for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */

package java.awt.im.spi;

import java.awt.AWTEvent;
import java.awt.Rectangle;
import java.util.Locale;

/**
 * This interface supports complex text input, often for situations where
 * the text is more complex than a keyboard will accomodate. For example,
 * this can be used for Chinese, Japanese, and Korean, where multiple
 * keystrokes are necessary to compose text. This could also support things
 * like phonetic English, or reordering Thai.
 *
 * <p>These contexts can be loaded by the input method framework, using
 * {@link InputContext#selectInputMethod(Locale)}.
 *
 * @author Eric Blake <[email protected]>
 * @since 1.3
 * @status updated to 1.4
 */
public interface InputMethod
{
  /**
   * Set the input method context, which ties the input method to a client
   * component. This is called once automatically when creating the input
   * method.
   *
   * @param context the context for this input method
   * @throws NullPointerException if context is null
   */
  void setInputMethodContext(InputMethodContext context);

  /**
   * Sets the input locale. If the input method supports that locale, it
   * changes its behavior to be consistent with the locale and returns true.
   * Otherwise, it returns false. This is called by
   * {@link InputContext#selectInputMethod(Locale)} when the user specifies
   * a locale, or when the previously selected input method had a locale.
   *
   * @param locale the locale to use for input
   * @return true if the change is successful
   * @throws NullPointerException if locale is null
   */
  boolean setLocale(Locale locale);

  /**
   * Returns the current input locale, or null if none is defined. This is
   * called by {@link InputContext#getLocale()}, or before switching input
   * methods.
   *
   * @return the current input locale, or null
   */
  Locale getLocale();

  /**
   * Sets the allowed Unicode subsets that this input method can use. Null
   * indicates that all characters are allowed. This is called after creation,
   * or when switching to this input method, by
   * {@link InputContext#setCharacterSubsets(Character.Subset[])}.
   *
   * @param subsets the accepted subsets for this input method, or null for all
   */