001    /* InputMethod.java -- defines an interface for complex text input
002       Copyright (C) 2002, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package java.awt.im.spi;
039    
040    import java.awt.AWTEvent;
041    import java.awt.Component;
042    import java.awt.Rectangle;
043    import java.awt.im.InputContext;
044    import java.awt.im.InputMethodRequests;
045    import java.text.AttributedCharacterIterator.Attribute;
046    import 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     */
062    public 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