libjava/java/awt/im/spi/InputMethod.java

   1 /* InputMethod.java -- defines an interface for complex text input
   2    Copyright (C) 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.awt.im.spi;
  39
  40 import java.awt.AWTEvent;
  41 import java.awt.Rectangle;
  42 import java.util.Locale;
  43
  44 /**
  45  * This interface supports complex text input, often for situations where
  46  * the text is more complex than a keyboard will accomodate. For example,
  47  * this can be used for Chinese, Japanese, and Korean, where multiple
  48  * keystrokes are necessary to compose text. This could also support things
  49  * like phonetic English, or reordering Thai.
  50  *
  51  * <p>These contexts can be loaded by the input method framework, using
  52  * {@link InputContext#selectInputMethod(Locale)}.
  53  *
  54  * @author Eric Blake (ebb9@email.byu.edu)
  55  * @since 1.3
  56  * @status updated to 1.4
  57  */
  58 public interface InputMethod
  59 {
  60   /**
  61    * Set the input method context, which ties the input method to a client
  62    * component. This is called once automatically when creating the input
  63    * method.
  64    *
  65    * @param context the context for this input method
  66    * @throws NullPointerException if context is null
  67    */
  68   void setInputMethodContext(InputMethodContext context);
  69
  70   /**
  71    * Sets the input locale. If the input method supports that locale, it
  72    * changes its behavior to be consistent with the locale and returns true.
  73    * Otherwise, it returns false. This is called by
  74    * {@link InputContext#selectInputMethod(Locale)} when the user specifies
  75    * a locale, or when the previously selected input method had a locale.
  76    *
  77    * @param locale the locale to use for input
  78    * @return true if the change is successful
  79    * @throws NullPointerException if locale is null
  80    */
  81   boolean setLocale(Locale locale);
  82
  83   /**
  84    * Returns the current input locale, or null if none is defined. This is
  85    * called by {@link InputContext#getLocale()}, or before switching input
  86    * methods.
  87    *
  88    * @return the current input locale, or null
  89    */
  90   Locale getLocale();
  91
  92   /**
  93    * Sets the allowed Unicode subsets that this input method can use. Null
  94    * indicates that all characters are allowed. This is called after creation,
  95    * or when switching to this input method, by
  96    * {@link InputContext#setCharacterSubsets(Character.Subset[])}.
  97    *
  98    * @param subsets the accepted subsets for this input method, or null for all
  99    */
 100   void setCharacterSubsets(Character.Subset[] subsets);
 101
 102   /**
 103    * Changes the enabled status of this input method. An enabled input method
 104    * accepts incoming events for composition and control purposes, while a
 105    * disabled input method ignores events (except for control purposes). This
 106    * is called by {@link InputContext#setCompositionEnabled(boolean)} or when
 107    * switching from an input method if the previous input method returned
 108    * without exception on {@link #isCompositionEnabled()}.
 109    *
 110    * @param enable whether to enable this input method
 111    * @throws UnsupportedOperationException if enabling/disabling is unsupported
 112    * @see #isCompositionEnabled()
 113    */
 114   void setCompositionEnabled(boolean enable);
 115
 116   /**
 117    * Find out if this input method is enabled. This is called by
 118    * {@link InputContext#isCompositionEnabled()}, or when switching input
 119    * methods via {@link InputContext#selectInputMethod(Locale)}.
 120    *
 121    * @return true if this input method is enabled
 122    * @throws UnsupportedOperationException if enabling/disabling is unsupported
 123    * @see #setCompositionEnabled(boolean)
 124    */
 125   boolean isCompositionEnabled();
 126
 127   /**
 128    * Starts a reconversion operation. The input method gets its text from the
 129    * client, using {@link InputMethodRequests#getSelectedText(Attribute[])}.
 130    * Then the composed and committed text produced by the operation is sent
 131    * back to the client using a sequence of InputMethodEvents. This is called
 132    * by {@link InputContext#reconvert()}.
 133    *
 134    * @throws UnsupportedOperationException if reconversion is unsupported
 135    */
 136   void reconvert();
 137
 138   /**
 139    * Dispatch an event to the input method. If input method support is enabled,
 140    * certain events are dispatched to the input method before the client
 141    * component or event listeners. The input method must either consume the
 142    * event or pass it on to the component. Instances of InputEvent, including
 143    * KeyEvent and MouseEvent, are given to this input method. This method is
 144    * called by {@link InputContext#dispatchEvent(AWTEvent)}.
 145    *
 146    * @param event the event to dispatch
 147    * @throws NullPointerException if event is null
 148    */
 149   void dispatchEvent(AWTEvent event);
 150
 151   /**
 152    * Notify this input method of changes in the client window. This is called
 153    * when notifications are enabled (see {@link
 154    * InputMethodContext#enableClientWindowNotification(InputMethod, boolean)},
 155    * if {@link #removeNotify(Component)} has not been called. The following
 156    * situations trigger a notification:<ul>
 157    * <li>The client window changes in location, size, visibility,
 158    * iconification, or is closed.</li>
 159    * <li>When enabling client notification (or on the first activation after
 160    * enabling if no client existed at the time).</li>
 161    * <li>When activating a new client after <code>removeNotify</code> was
 162    * called on a previous client.</li>
 163    * </ul>
 164    *
 165    * @param bounds the client window's current bounds, or null
 166    */
 167   void notifyClientWindowChange(Rectangle bounds);
 168
 169   /**
 170    * Activate this input method for input processing. If the input method
 171    * provides its own windows, it should make them open and visible at this
 172    * time. This method is called when a client component receives a
 173    * FOCUS_GAINED event, or when switching to this input method from another
 174    * one. It is only called when the input method is inactive, assuming that
 175    * new instances begin in an inactive state.
 176    */
 177   void activate();
 178
 179   /**
 180    * Deactivate this input method, either temporarily or permanently for the
 181    * given client. If the input method provides its own windows, it should
 182    * only close those related to the current composition (such as a lookup
 183    * choice panel), while leaving more persistant windows (like a control
 184    * panel) open to avoid screen flicker. Before control is given to another
 185    * input method, {@link #hideWindows()} will be called on this instance.
 186    * This method is called when a client component receives a
 187    * FOCUS_LOST event, when switching to another input method, or before
 188    * {@link #removeNotify()} when the client is removed.
 189    *
 190    * @param isTemporary true if the focus change is temporary
 191    */
 192   void deactivate(boolean isTemporary);
 193
 194   /**
 195    * Close or hide all windows opened by this input method. This is called
 196    * before activating a different input method, and before calling
 197    * {@link #dispose()} on this instance. It is only called when the input
 198    * method is inactive.
 199    */
 200   void hideWindows();
 201
 202   /**
 203    * Notify the input method that a client component has been removed from its
 204    * hierarchy, or that input method support has been disabled. This is
 205    * called by {@link InputContext#removeNotify()}, and only when the input
 206    * method is inactive.
 207    */
 208   void removeNotify();
 209
 210   /**
 211    * End any input composition currently taking place. Depending on the
 212    * platform and user preferences, this may commit or delete uncommitted text,
 213    * using input method events. This may be called for a variety of reasons,
 214    * such as when the user moves the insertion point in the client text outside
 215    * the range of the composed text, or when text is saved to file. This is
 216    * called by {@link InputContext#endComposition()}, when switching to a
 217    * new input method, or by {@link InputContext#selectInputMethod(Locale)}.
 218    */
 219   void endComposition();
 220
 221   /**
 222    * Disposes the input method and release any resources it is using. In
 223    * particular, the input method should dispose windows and close files. This
 224    * is called by {@link InputContext#dispose()}, when the input method is
 225    * inactive; and nothing will be called on this instance afterwards.
 226    */
 227   void dispose();
 228
 229   /**
 230    * Returns a control object from this input method, or null. A control object
 231    * provides method to control the behavior of this input method, as well as
 232    * query information about it. The object is implementation dependent, so
 233    * clients must compare the result against known input method control
 234    * object types. This is called by
 235    * {@link InputContext#getInputMethodControlObject()}.
 236    *
 237    * @return the control object, or null
 238    */
 239   Object getControlObject();
 240 } // interface InputMethod