001 /*
002 * Copyright 1997-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.im.spi;
027
028 import java.util.Locale;
029 import java.awt.AWTEvent;
030 import java.awt.Rectangle;
031 import java.lang.Character.Subset;
032
033 /**
034 * Defines the interface for an input method that supports complex text input.
035 * Input methods traditionally support text input for languages that have
036 * more characters than can be represented on a standard-size keyboard,
037 * such as Chinese, Japanese, and Korean. However, they may also be used to
038 * support phonetic text input for English or character reordering for Thai.
039 * <p>
040 * Subclasses of InputMethod can be loaded by the input method framework; they
041 * can then be selected either through the API
042 * ({@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod})
043 * or the user interface (the input method selection menu).
044 *
045 * @since 1.3
046 *
047 * @version 1.37, 05/05/07
048 * @author JavaSoft International
049 */
050
051 public interface InputMethod {
052
053 /**
054 * Sets the input method context, which is used to dispatch input method
055 * events to the client component and to request information from
056 * the client component.
057 * <p>
058 * This method is called once immediately after instantiating this input
059 * method.
060 *
061 * @param context the input method context for this input method
062 * @exception NullPointerException if <code>context</code> is null
063 */
064 public void setInputMethodContext(InputMethodContext context);
065
066 /**
067 * Attempts to set the input locale. If the input method supports the
068 * desired locale, it changes its behavior to support input for the locale
069 * and returns true.
070 * Otherwise, it returns false and does not change its behavior.
071 * <p>
072 * This method is called
073 * <ul>
074 * <li>by {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
075 * <li>when switching to this input method through the user interface if the user
076 * specified a locale or if the previously selected input method's
077 * {@link java.awt.im.spi.InputMethod#getLocale getLocale} method
078 * returns a non-null value.
079 * </ul>
080 *
081 * @param locale locale to input
082 * @return whether the specified locale is supported
083 * @exception NullPointerException if <code>locale</code> is null
084 */
085 public boolean setLocale(Locale locale);
086
087 /**
088 * Returns the current input locale. Might return null in exceptional cases.
089 * <p>
090 * This method is called
091 * <ul>
092 * <li>by {@link java.awt.im.InputContext#getLocale InputContext.getLocale} and
093 * <li>when switching from this input method to a different one through the
094 * user interface.
095 * </ul>
096 *
097 * @return the current input locale, or null
098 */
099 public Locale getLocale();
100
101 /**
102 * Sets the subsets of the Unicode character set that this input method
103 * is allowed to input. Null may be passed in to indicate that all
104 * characters are allowed.
105 * <p>
106 * This method is called
107 * <ul>
108 * <li>immediately after instantiating this input method,
109 * <li>when switching to this input method from a different one, and
110 * <li>by {@link java.awt.im.InputContext#setCharacterSubsets InputContext.setCharacterSubsets}.
111 * </ul>
112 *
113 * @param subsets the subsets of the Unicode character set from which
114 * characters may be input
115 */
116 public void setCharacterSubsets(Subset[] subsets);
117
118 /**
119 * Enables or disables this input method for composition,
120 * depending on the value of the parameter <code>enable</code>.
121 * <p>
122 * An input method that is enabled for composition interprets incoming
123 * events for both composition and control purposes, while a
124 * disabled input method does not interpret events for composition.
125 * Note however that events are passed on to the input method regardless
126 * whether it is enabled or not, and that an input method that is disabled
127 * for composition may still interpret events for control purposes,
128 * including to enable or disable itself for composition.
129 * <p>
130 * For input methods provided by host operating systems, it is not always possible to
131 * determine whether this operation is supported. For example, an input method may enable
132 * composition only for some locales, and do nothing for other locales. For such input
133 * methods, it is possible that this method does not throw
134 * {@link java.lang.UnsupportedOperationException UnsupportedOperationException},
135 * but also does not affect whether composition is enabled.
136 * <p>
137 * This method is called
138 * <ul>
139 * <li>by {@link java.awt.im.InputContext#setCompositionEnabled InputContext.setCompositionEnabled},
140 * <li>when switching to this input method from a different one using the
141 * user interface or
142 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
143 * if the previously selected input method's
144 * {@link java.awt.im.spi.InputMethod#isCompositionEnabled isCompositionEnabled}
145 * method returns without throwing an exception.
146 * </ul>
147 *
148 * @param enable whether to enable the input method for composition
149 * @throws UnsupportedOperationException if this input method does not
150 * support the enabling/disabling operation
151 * @see #isCompositionEnabled
152 */
153 public void setCompositionEnabled(boolean enable);
154
155 /**
156 * Determines whether this input method is enabled.
157 * An input method that is enabled for composition interprets incoming
158 * events for both composition and control purposes, while a
159 * disabled input method does not interpret events for composition.
160 * <p>
161 * This method is called
162 * <ul>
163 * <li>by {@link java.awt.im.InputContext#isCompositionEnabled InputContext.isCompositionEnabled} and
164 * <li>when switching from this input method to a different one using the
165 * user interface or
166 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
167 * </ul>
168 *
169 * @return <code>true</code> if this input method is enabled for
170 * composition; <code>false</code> otherwise.
171 * @throws UnsupportedOperationException if this input method does not
172 * support checking whether it is enabled for composition
173 * @see #setCompositionEnabled
174 */
175 public boolean isCompositionEnabled();
176
177 /**
178 * Starts the reconversion operation. The input method obtains the
179 * text to be reconverted from the current client component using the
180 * {@link java.awt.im.InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText}
181 * method. It can use other <code>InputMethodRequests</code>
182 * methods to request additional information required for the
183 * reconversion operation. The composed and committed text
184 * produced by the operation is sent to the client component as a
185 * sequence of <code>InputMethodEvent</code>s. If the given text
186 * cannot be reconverted, the same text should be sent to the
187 * client component as committed text.
188 * <p>
189 * This method is called by
190 * {@link java.awt.im.InputContext#reconvert() InputContext.reconvert}.
191 *
192 * @throws UnsupportedOperationException if the input method does not
193 * support the reconversion operation.
194 */
195 public void reconvert();
196
197 /**
198 * Dispatches the event to the input method. If input method support is
199 * enabled for the focussed component, incoming events of certain types
200 * are dispatched to the current input method for this component before
201 * they are dispatched to the component's methods or event listeners.
202 * The input method decides whether it needs to handle the event. If it
203 * does, it also calls the event's <code>consume</code> method; this
204 * causes the event to not get dispatched to the component's event
205 * processing methods or event listeners.
206 * <p>
207 * Events are dispatched if they are instances of InputEvent or its
208 * subclasses.
209 * This includes instances of the AWT classes KeyEvent and MouseEvent.
210 * <p>
211 * This method is called by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}.
212 *
213 * @param event the event being dispatched to the input method
214 * @exception NullPointerException if <code>event</code> is null
215 */
216 public void dispatchEvent(AWTEvent event);
217
218 /**
219 * Notifies this input method of changes in the client window
220 * location or state. This method is called while this input
221 * method is the current input method of its input context and
222 * notifications for it are enabled (see {@link
223 * InputMethodContext#enableClientWindowNotification
224 * InputMethodContext.enableClientWindowNotification}). Calls
225 * to this method are temporarily suspended if the input context's
226 * {@link java.awt.im.InputContext#removeNotify removeNotify}
227 * method is called, and resume when the input method is activated
228 * for a new client component. It is called in the following
229 * situations:
230 * <ul>
231 * <li>
232 * when the window containing the current client component changes
233 * in location, size, visibility, iconification state, or when the
234 * window is closed.</li>
235 * <li>
236 * from <code> enableClientWindowNotification(inputMethod,
237 * true)</code> if the current client component exists,</li>
238 * <li>
239 * when activating the input method for the first time after it
240 * called
241 * <code>enableClientWindowNotification(inputMethod,
242 * true)</code> if during the call no current client component was
243 * available,</li>
244 * <li>
245 * when activating the input method for a new client component
246 * after the input context's removeNotify method has been
247 * called.</li>
248 * </ul>
249 * @param bounds client window's {@link
250 * java.awt.Component#getBounds bounds} on the screen; or null if
251 * the client window is iconified or invisible
252 */
253 public void notifyClientWindowChange(Rectangle bounds);
254
255 /**
256 * Activates the input method for immediate input processing.
257 * <p>
258 * If an input method provides its own windows, it should make sure
259 * at this point that all necessary windows are open and visible.
260 * <p>
261 * This method is called
262 * <ul>
263 * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}
264 * when a client component receives a FOCUS_GAINED event,
265 * <li>when switching to this input method from a different one using the
266 * user interface or
267 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
268 * </ul>
269 * The method is only called when the input method is inactive.
270 * A newly instantiated input method is assumed to be inactive.
271 */
272 public void activate();
273
274 /**
275 * Deactivates the input method.
276 * The isTemporary argument has the same meaning as in
277 * {@link java.awt.event.FocusEvent#isTemporary FocusEvent.isTemporary}.
278 * <p>
279 * If an input method provides its own windows, only windows that relate
280 * to the current composition (such as a lookup choice window) should be
281 * closed at this point.
282 * It is possible that the input method will be immediately activated again
283 * for a different client component, and closing and reopening more
284 * persistent windows (such as a control panel) would create unnecessary
285 * screen flicker.
286 * Before an instance of a different input method class is activated,
287 * {@link #hideWindows} is called on the current input method.
288 * <p>
289 * This method is called
290 * <ul>
291 * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}
292 * when a client component receives a FOCUS_LOST event,
293 * <li>when switching from this input method to a different one using the
294 * user interface or
295 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
296 * <li>before {@link #removeNotify removeNotify} if the current client component is
297 * removed.
298 * </ul>
299 * The method is only called when the input method is active.
300 *
301 * @param isTemporary whether the focus change is temporary
302 */
303 public void deactivate(boolean isTemporary);
304
305 /**
306 * Closes or hides all windows opened by this input method instance or
307 * its class.
308 * <p>
309 * This method is called
310 * <ul>
311 * <li>before calling {@link #activate activate} on an instance of a different input
312 * method class,
313 * <li>before calling {@link #dispose dispose} on this input method.
314 * </ul>
315 * The method is only called when the input method is inactive.
316 */
317 public void hideWindows();
318
319 /**
320 * Notifies the input method that a client component has been
321 * removed from its containment hierarchy, or that input method
322 * support has been disabled for the component.
323 * <p>
324 * This method is called by {@link java.awt.im.InputContext#removeNotify InputContext.removeNotify}.
325 * <p>
326 * The method is only called when the input method is inactive.
327 */
328 public void removeNotify();
329
330 /**
331 * Ends any input composition that may currently be going on in this
332 * context. Depending on the platform and possibly user preferences,
333 * this may commit or delete uncommitted text. Any changes to the text
334 * are communicated to the active component using an input method event.
335 *
336 * <p>
337 * A text editing component may call this in a variety of situations,
338 * for example, when the user moves the insertion point within the text
339 * (but outside the composed text), or when the component's text is
340 * saved to a file or copied to the clipboard.
341 * <p>
342 * This method is called
343 * <ul>
344 * <li>by {@link java.awt.im.InputContext#endComposition InputContext.endComposition},
345 * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}
346 * when switching to a different client component
347 * <li>when switching from this input method to a different one using the
348 * user interface or
349 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
350 * </ul>
351 */
352 public void endComposition();
353
354 /**
355 * Releases the resources used by this input method.
356 * In particular, the input method should dispose windows and close files that are no
357 * longer needed.
358 * <p>
359 * This method is called by {@link java.awt.im.InputContext#dispose InputContext.dispose}.
360 * <p>
361 * The method is only called when the input method is inactive.
362 * No method of this interface is called on this instance after dispose.
363 */
364 public void dispose();
365
366 /**
367 * Returns a control object from this input method, or null. A
368 * control object provides methods that control the behavior of the
369 * input method or obtain information from the input method. The type
370 * of the object is an input method specific class. Clients have to
371 * compare the result against known input method control object
372 * classes and cast to the appropriate class to invoke the methods
373 * provided.
374 * <p>
375 * This method is called by
376 * {@link java.awt.im.InputContext#getInputMethodControlObject InputContext.getInputMethodControlObject}.
377 *
378 * @return a control object from this input method, or null
379 */
380 public Object getControlObject();
381
382 }
|