gomp-20050608-branch/libjava/classpath/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., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 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.Component;
  42 import java.awt.Rectangle;
  43 import java.awt.im.InputContext;
  44 import java.awt.im.InputMethodRequests;
  45 import java.text.AttributedCharacterIterator.Attribute;
  46 import java.util.Locale;
  47
  48 /**
  49  * This interface supports complex text input, often for situations where
  50  * the text is more complex than a keyboard will accomodate. For example,
  51  * this can be used for Chinese, Japanese, and Korean, where multiple
  52  * keystrokes are necessary to compose text. This could also support things
  53  * like phonetic English, or reordering Thai.
  54  *
  55  * <p>These contexts can be loaded by the input method framework, using
  56  * {@link InputContext#selectInputMethod(Locale)}.
  57  *
  58  * @author Eric Blake (ebb9@email.byu.edu)
  59  * @since 1.3
  60  * @status updated to 1.4
  61  */
  62 public interface InputMethod
  63 {
  64   /**
  65    * Set the input method context, which ties the input method to a client
  66    * component. This is called once automatically when creating the input
  67    * method.
  68    *
  69    * @param context the context for this input method
  70    * @throws NullPointerException if context is null
  71    */
  72   void setInputMethodContext(InputMethodContext context);
  73
  74   /**
  75    * Sets the input locale. If the input method supports that locale, it
  76    * changes its behavior to be consistent with the locale and returns true.
  77    * Otherwise, it returns false. This is called by
  78    * {@link InputContext#selectInputMethod(Locale)} when the user specifies
  79    * a locale, or when the previously selected input method had a locale.
  80    *
  81    * @param locale the locale to use for input
  82    * @return true if the change is successful
  83    * @throws NullPointerException if locale is null
  84    */
  85   boolean setLocale(Locale locale);
  86
  87   /**
  88    * Returns the current input locale, or null if none is defined. This is
  89    * called by {@link InputContext#getLocale()}, or before switching input
  90    * methods.
  91    *
  92    * @return the current input locale, or null
  93    */
  94   Locale getLocale();
  95
  96   /**
  97    * Sets the allowed Unicode subsets that this input method can use. Null
  98    * indicates that all characters are allowed. This is called after creation,
  99    * or when switching to this input method, by
 100    * {@link InputContext#setCharacterSubsets(Character.Subset[])}.
 101    *
 102    * @param subsets the accepted subsets for this input method, or null for all
 103    */
 104   void setCharacterSubsets(Character.Subset[] subsets);
 105
 106   /**
 107    * Changes the enabled status of this input method. An enabled input method
 108    * accepts incoming events for composition and control purposes, while a
 109    * disabled input method ignores events (except for control purposes). This
 110    * is called by {@link InputContext#setCompositionEnabled(boolean)} or when
 111    * switching from an input method if the previous input method returned
 112    * without exception on {@link #isCompositionEnabled()}.
 113    *
 114    * @param enable whether to enable this input method
 115    * @throws UnsupportedOperationException if enabling/disabling is unsupported
 116    * @see #isCompositionEnabled()
 117    */
 118   void setCompositionEnabled(boolean enable);
 119
 120   /**
 121    * Find out if this input method is enabled. This is called by
 122    * {@link InputContext#isCompositionEnabled()}, or when switching input
 123    * methods via {@link InputContext#selectInputMethod(Locale)}.
 124    *
 125    * @return true if this input method is enabled
 126    * @throws UnsupportedOperationException if enabling/disabling is unsupported
 127    * @see #setCompositionEnabled(boolean)
 128    */
 129   boolean isCompositionEnabled();
 130
 131   /**
 132    * Starts a reconversion operation. The input method gets its text from the
 133    * client, using {@link InputMethodRequests#getSelectedText(Attribute[])}.
 134    * Then the composed and committed text produced by the operation is sent
 135    * back to the client using a sequence of InputMethodEvents. This is called
 136    * by {@link InputContext#reconvert()}.
 137    *
 138    * @throws UnsupportedOperationException if reconversion is unsupported
 139    */
 140   void reconvert();
 141
 142   /**
 143    * Dispatch an event to the input method. If input method support is enabled,
 144    * certain events are dispatched to the input method before the client
 145    * component or event listeners. The input method must either consume the
 146    * event or pass it on to the component. Instances of InputEvent, including
 147    * KeyEvent and MouseEvent, are given to this input method. This method is
 148    * called by {@link InputContext#dispatchEvent(AWTEvent)}.
 149    *
 150    * @param event the event to dispatch
 151    * @throws NullPointerException if event is null
 152    */
 153   void dispatchEvent(AWTEvent event);
 154
 155   /**
 156    * Notify this input method of changes in the client window. This is called
 157    * when notifications are enabled (see {@link
 158    * InputMethodContext#enableClientWindowNotification(InputMethod, boolean)},
 159    * if {@link InputContext#removeNotify(Component)} has not been called.
 160    * The following situations trigger a notification:<ul>
 161    * <li>The client window changes in location, size, visibility,
 162    * iconification, or is closed.</li>
 163    * <li>When enabling client notification (or on the first activation after
 164    * enabling if no client existed at the time).</li>
 165    * <li>When activating a new client after <code>removeNotify</code> was
 166    * called on a previous client.</li>
 167    * </ul>
 168    *
 169    * @param bounds the client window's current bounds, or null
 170    */
 171   void notifyClientWindowChange(Rectangle bounds);
 172
 173   /**
 174    * Activate this input method for input processing. If the input method
 175    * provides its own windows, it should make them open and visible at this
 176    * time. This method is called when a client component receives a
 177    * FOCUS_GAINED event, or when switching to this input method from another
 178    * one. It is only called when the input method is inactive, assuming that
 179    * new instances begin in an inactive state.
 180    */
 181   void activate();
 182
 183   /**
 184    * Deactivate this input method, either temporarily or permanently for the
 185    * given client. If the input method provides its own windows, it should
 186    * only close those related to the current composition (such as a lookup
 187    * choice panel), while leaving more persistant windows (like a control
 188    * panel) open to avoid screen flicker. Before control is given to another
 189    * input method, {@link #hideWindows()} will be called on this instance.
 190    * This method is called when a client component receives a
 191    * FOCUS_LOST event, when switching to another input method, or before
 192    * {@link #removeNotify()} when the client is removed.
 193    *
 194    * @param isTemporary true if the focus change is temporary
 195    */
 196   void deactivate(boolean isTemporary);
 197
 198   /**
 199    * Close or hide all windows opened by this input method. This is called
 200    * before activating a different input method, and before calling
 201    * {@link #dispose()} on this instance. It is only called when the input
 202    * method is inactive.
 203    */
 204   void hideWindows();
 205
 206   /**
 207    * Notify the input method that a client component has been removed from its
 208    * hierarchy, or that input method support has been disabled. This is
 209    * called by {@link InputContext#removeNotify(Component)}, and only when the input
 210    * method is inactive.
 211    */
 212   void removeNotify();
 213
 214   /**
 215    * End any input composition currently taking place. Depending on the
 216    * platform and user preferences, this may commit or delete uncommitted text,
 217    * using input method events. This may be called for a variety of reasons,
 218    * such as when the user moves the insertion point in the client text outside
 219    * the range of the composed text, or when text is saved to file. This is
 220    * called by {@link InputContext#endComposition()}, when switching to a
 221    * new input method, or by {@link InputContext#selectInputMethod(Locale)}.
 222    */
 223   void endComposition();
 224
 225   /**
 226    * Disposes the input method and release any resources it is using. In
 227    * particular, the input method should dispose windows and close files. This
 228    * is called by {@link InputContext#dispose()}, when the input method is
 229    * inactive; and nothing will be called on this instance afterwards.
 230    */
 231   void dispose();
 232
 233   /**
 234    * Returns a control object from this input method, or null. A control object
 235    * provides method to control the behavior of this input method, as well as
 236    * query information about it. The object is implementation dependent, so
 237    * clients must compare the result against known input method control
 238    * object types. This is called by
 239    * {@link InputContext#getInputMethodControlObject()}.
 240    *
 241    * @return the control object, or null
 242    */
 243   Object getControlObject();
 244 } // interface InputMethod