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