InputMethod


1   /*
2    * @(#)InputMethod.java 1.29 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt.im.spi;
9   
10  import java.util.Locale  ;
11  import java.awt.AWTEvent  ;
12  import java.awt.Rectangle  ;
13  import java.lang.Character.Subset;
14  
15  
16  /**
17   * Defines the interface for an input method that supports complex text input.
18   * Input methods traditionally support text input for languages that have
19   * more characters than can be represented on a standard-size keyboard,
20   * such as Chinese, Japanese, and Korean. However, they may also be used to
21   * support phonetic text input for English or character reordering for Thai.
22   * <p>
23   * Subclasses of InputMethod can be loaded by the input method framework; they
24   * can then be selected either through the API
25   * ({@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod})
26   * or the user interface (the input method selection menu).
27   *
28   * @since 1.3
29   *
30   * @version     1.29, 12/19/03
31   * @author JavaSoft International
32   */
33  
34  public interface InputMethod {
35  
36      /**
37       * Sets the input method context, which is used to dispatch input method
38       * events to the client component and to request information from
39       * the client component.
40       * <p>
41       * This method is called once immediately after instantiating this input
42       * method.
43       *
44       * @param context the input method context for this input method
45       * @exception NullPointerException if <code>context</code> is null
46       */
47      public void setInputMethodContext(InputMethodContext   context);
48  
49      /**
50       * Attempts to set the input locale. If the input method supports the
51       * desired locale, it changes its behavior to support input for the locale
52       * and returns true.
53       * Otherwise, it returns false and does not change its behavior.
54       * <p>
55       * This method is called
56       * <ul>
57       * <li>by {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
58       * <li>when switching to this input method through the user interface if the user
59       *     specified a locale or if the previously selected input method's
60       *     {@link java.awt.im.spi.InputMethod#getLocale getLocale} method
61       *     returns a non-null value.
62       * </ul>
63       *
64       * @param locale locale to input
65       * @return whether the specified locale is supported
66       * @exception NullPointerException if <code>locale</code> is null
67       */
68      public boolean setLocale(Locale   locale);
69  
70      /**
71       * Returns the current input locale. Might return null in exceptional cases.
72       * <p>
73       * This method is called
74       * <ul>
75       * <li>by {@link java.awt.im.InputContext#getLocale InputContext.getLocale} and
76       * <li>when switching from this input method to a different one through the
77       *     user interface.
78       * </ul>
79       *
80       * @return the current input locale, or null
81       */
82      public Locale   getLocale();
83      
84      /**
85       * Sets the subsets of the Unicode character set that this input method
86       * is allowed to input. Null may be passed in to indicate that all
87       * characters are allowed.
88       * <p>
89       * This method is called
90       * <ul>
91       * <li>immediately after instantiating this input method,
92       * <li>when switching to this input method from a different one, and
93       * <li>by {@link java.awt.im.InputContext#setCharacterSubsets InputContext.setCharacterSubsets}.
94       * </ul>
95       *
96       * @param subsets the subsets of the Unicode character set from which
97       * characters may be input
98       */
99      public void setCharacterSubsets(Subset[] subsets);
100 
101     /**
102      * Enables or disables this input method for composition,
103      * depending on the value of the parameter <code>enable</code>.
104      * <p>
105      * An input method that is enabled for composition interprets incoming
106      * events for both composition and control purposes, while a
107      * disabled input method does not interpret events for composition.
108      * Note however that events are passed on to the input method regardless
109      * whether it is enabled or not, and that an input method that is disabled
110      * for composition may still interpret events for control purposes,
111      * including to enable or disable itself for composition.
112      * <p>
113      * For input methods provided by host operating systems, it is not always possible to 
114      * determine whether this operation is supported. For example, an input method may enable
115      * composition only for some locales, and do nothing for other locales. For such input 
116      * methods, it is possible that this method does not throw 
117      * {@link java.lang.UnsupportedOperationException UnsupportedOperationException},
118      * but also does not affect whether composition is enabled.
119      * <p>
120      * This method is called
121      * <ul>
122      * <li>by {@link java.awt.im.InputContext#setCompositionEnabled InputContext.setCompositionEnabled},
123      * <li>when switching to this input method from a different one using the
124      *     user interface or
125      *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
126      *     if the previously selected input method's
127      *     {@link java.awt.im.spi.InputMethod#isCompositionEnabled isCompositionEnabled}
128      *     method returns without throwing an exception.
129      * </ul>
130      *
131      * @param enable whether to enable the input method for composition
132      * @throws UnsupportedOperationException if this input method does not
133      * support the enabling/disabling operation
134      * @see #isCompositionEnabled
135      */
136     public void setCompositionEnabled(boolean enable);
137 
138     /**
139      * Determines whether this input method is enabled.
140      * An input method that is enabled for composition interprets incoming
141      * events for both composition and control purposes, while a
142      * disabled input method does not interpret events for composition.
143      * <p>
144      * This method is called
145      * <ul>
146      * <li>by {@link java.awt.im.InputContext#isCompositionEnabled InputContext.isCompositionEnabled} and
147      * <li>when switching from this input method to a different one using the
148      *     user interface or
149      *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
150      * </ul>
151      *
152      * @return <code>true</code> if this input method is enabled for
153      * composition; <code>false</code> otherwise.
154      * @throws UnsupportedOperationException if this input method does not
155      * support checking whether it is enabled for composition
156      * @see #setCompositionEnabled
157      */
158     public boolean isCompositionEnabled();
159 
160     /**
161      * Starts the reconversion operation. The input method obtains the
162      * text to be reconverted from the current client component using the
163      * {@link java.awt.im.InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText}
164      * method. It can use other <code>InputMethodRequests</code>
165      * methods to request additional information required for the
166      * reconversion operation. The composed and committed text
167      * produced by the operation is sent to the client component as a
168      * sequence of <code>InputMethodEvent</code>s. If the given text
169      * cannot be reconverted, the same text should be sent to the
170      * client component as committed text.
171      * <p>
172      * This method is called by
173      * {@link java.awt.im.InputContext#reconvert() InputContext.reconvert}.
174      *
175      * @throws UnsupportedOperationException if the input method does not
176      * support the reconversion operation.
177      */
178     public void reconvert();
179 
180     /**
181      * Dispatches the event to the input method. If input method support is
182      * enabled for the focussed component, incoming events of certain types
183      * are dispatched to the current input method for this component before
184      * they are dispatched to the component's methods or event listeners.
185      * The input method decides whether it needs to handle the event. If it
186      * does, it also calls the event's <code>consume</code> method; this
187      * causes the event to not get dispatched to the component's event
188      * processing methods or event listeners.
189      * <p>
190      * Events are dispatched if they are instances of InputEvent or its
191      * subclasses.
192      * This includes instances of the AWT classes KeyEvent and MouseEvent.
193      * <p>
194      * This method is called by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}.
195      *
196      * @param event the event being dispatched to the input method
197      * @exception NullPointerException if <code>event</code> is null
198      */
199     public void dispatchEvent(AWTEvent   event);
200 
201     /**
202      * Notifies this input method of changes in the client window
203      * location or state. This method is called while this input
204      * method is the current input method of its input context and
205      * notifications for it are enabled (see {@link
206      * InputMethodContext#enableClientWindowNotification
207      * InputMethodContext.enableClientWindowNotification}). Calls
208      * to this method are temporarily suspended if the input context's
209      * {@link java.awt.im.InputContext#removeNotify removeNotify}
210      * method is called, and resume when the input method is activated
211      * for a new client component. It is called in the following
212      * situations:
213      * <ul>
214      * <li>
215      * when the window containing the current client component changes
216      * in location, size, visibility, iconification state, or when the
217      * window is closed.</li>
218      * <li>
219      * from <code> enableClientWindowNotification(inputMethod,
220      * true)</code> if the current client component exists,</li>
221      * <li>
222      * when activating the input method for the first time after it
223      * called
224      * <code>enableClientWindowNotification(inputMethod,
225      * true)</code> if during the call no current client component was
226      * available,</li>
227      * <li>
228      * when activating the input method for a new client component
229      * after the input context's removeNotify method has been
230      * called.</li>
231      * </ul>
232      * @param bounds client window's {@link
233      * java.awt.Component#getBounds bounds} on the screen; or null if
234      * the client window is iconified or invisible
235      */
236     public void notifyClientWindowChange(Rectangle   bounds);
237 
238     /**
239      * Activates the input method for immediate input processing.
240      * <p>
241      * If an input method provides its own windows, it should make sure
242      * at this point that all necessary windows are open and visible.
243      * <p>
244      * This method is called
245      * <ul>
246      * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}
247      *     when a client component receives a FOCUS_GAINED event,
248      * <li>when switching to this input method from a different one using the
249      *     user interface or
250      *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
251      * </ul>
252      * The method is only called when the input method is inactive.
253      * A newly instantiated input method is assumed to be inactive.
254      */
255     public void activate();
256 
257     /**
258      * Deactivates the input method.
259      * The isTemporary argument has the same meaning as in
260      * {@link java.awt.event.FocusEvent#isTemporary FocusEvent.isTemporary}.
261      * <p>
262      * If an input method provides its own windows, only windows that relate
263      * to the current composition (such as a lookup choice window) should be
264      * closed at this point.
265      * It is possible that the input method will be immediately activated again
266      * for a different client component, and closing and reopening more
267      * persistent windows (such as a control panel) would create unnecessary
268      * screen flicker.
269      * Before an instance of a different input method class is activated,
270      * {@link #hideWindows} is called on the current input method.
271      * <p>
272      * This method is called
273      * <ul>
274      * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}
275      *     when a client component receives a FOCUS_LOST event,
276      * <li>when switching from this input method to a different one using the
277      *     user interface or
278      *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
279      * <li>before {@link #removeNotify removeNotify} if the current client component is
280      *     removed.
281      * </ul>
282      * The method is only called when the input method is active.
283      *
284      * @param isTemporary whether the focus change is temporary
285      */
286     public void deactivate(boolean isTemporary);
287 
288     /**
289      * Closes or hides all windows opened by this input method instance or
290      * its class.
291      * <p>
292      * This method is called
293      * <ul>
294      * <li>before calling {@link #activate activate} on an instance of a different input
295      *     method class,
296      * <li>before calling {@link #dispose dispose} on this input method.
297      * </ul>
298      * The method is only called when the input method is inactive.
299      */
300     public void hideWindows();
301   
302     /**
303      * Notifies the input method that a client component has been
304      * removed from its containment hierarchy, or that input method
305      * support has been disabled for the component.
306      * <p>
307      * This method is called by {@link java.awt.im.InputContext#removeNotify InputContext.removeNotify}.
308      * <p>
309      * The method is only called when the input method is inactive.
310      */
311     public void removeNotify();
312 
313     /**
314      * Ends any input composition that may currently be going on in this
315      * context. Depending on the platform and possibly user preferences,
316      * this may commit or delete uncommitted text. Any changes to the text
317      * are communicated to the active component using an input method event.
318      *
319      * <p>
320      * A text editing component may call this in a variety of situations,
321      * for example, when the user moves the insertion point within the text
322      * (but outside the composed text), or when the component's text is
323      * saved to a file or copied to the clipboard.
324      * <p>
325      * This method is called
326      * <ul>
327      * <li>by {@link java.awt.im.InputContext#endComposition InputContext.endComposition},
328      * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}
329      *     when switching to a different client component
330      * <li>when switching from this input method to a different one using the
331      *     user interface or
332      *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
333      * </ul>
334      */
335     public void endComposition();
336 
337     /**
338      * Disposes of the input method and releases the resources used by it.
339      * In particular, the input method should dispose windows and close files that are no
340      * longer needed.
341      * <p>
342      * This method is called by {@link java.awt.im.InputContext#dispose InputContext.dispose}.
343      * <p>
344      * The method is only called when the input method is inactive.
345      * No method of this interface is called on this instance after dispose.
346      */
347     public void dispose();
348 
349     /**
350      * Returns a control object from this input method, or null. A
351      * control object provides methods that control the behavior of the
352      * input method or obtain information from the input method. The type
353      * of the object is an input method specific class. Clients have to
354      * compare the result against known input method control object
355      * classes and cast to the appropriate class to invoke the methods
356      * provided.
357      * <p>
358      * This method is called by
359      * {@link java.awt.im.InputContext#getInputMethodControlObject InputContext.getInputMethodControlObject}.
360      *
361      * @return a control object from this input method, or null
362      */
363     public Object   getControlObject();
364 
365 }
366
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags