001/* InputMethod.java -- defines an interface for complex text input
002   Copyright (C) 2002, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package java.awt.im.spi;
039
040import java.awt.AWTEvent;
041import java.awt.Component;
042import java.awt.Rectangle;
043import java.awt.im.InputContext;
044import java.awt.im.InputMethodRequests;
045import java.text.AttributedCharacterIterator.Attribute;
046import java.util.Locale;
047
048/**
049 * This interface supports complex text input, often for situations where
050 * the text is more complex than a keyboard will accomodate. For example,
051 * this can be used for Chinese, Japanese, and Korean, where multiple
052 * keystrokes are necessary to compose text. This could also support things
053 * like phonetic English, or reordering Thai.
054 *
055 * <p>These contexts can be loaded by the input method framework, using
056 * {@link InputContext#selectInputMethod(Locale)}.
057 *
058 * @author Eric Blake (ebb9@email.byu.edu)
059 * @since 1.3
060 * @status updated to 1.4
061 */
062public interface InputMethod
063{
064  /**
065   * Set the input method context, which ties the input method to a client
066   * component. This is called once automatically when creating the input
067   * method.
068   *
069   * @param context the context for this input method
070   * @throws NullPointerException if context is null
071   */
072  void setInputMethodContext(InputMethodContext context);
073
074  /**
075   * Sets the input locale. If the input method supports that locale, it
076   * changes its behavior to be consistent with the locale and returns true.
077   * Otherwise, it returns false. This is called by
078   * {@link InputContext#selectInputMethod(Locale)} when the user specifies
079   * a locale, or when the previously selected input method had a locale.
080   *
081   * @param locale the locale to use for input
082   * @return true if the change is successful
083   * @throws NullPointerException if locale is null
084   */
085  boolean setLocale(Locale locale);
086
087  /**
088   * Returns the current input locale, or null if none is defined. This is
089   * called by {@link InputContext#getLocale()}, or before switching input
090   * methods.
091   *
092   * @return the current input locale, or null
093   */
094  Locale getLocale();
095
096  /**
097   * Sets the allowed Unicode subsets that this input method can use. Null
098   * indicates that all characters are allowed. This is called after creation,
099   * 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