View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.awt.im;
27  
28  import java.awt.Component;
29  import java.util.Locale;
30  import java.awt.AWTEvent;
31  import java.beans.Transient;
32  import java.lang.Character.Subset;
33  import sun.awt.im.InputMethodContext;
34  
35  /**
36   * Provides methods to control text input facilities such as input
37   * methods and keyboard layouts.
38   * Two methods handle both input methods and keyboard layouts: selectInputMethod
39   * lets a client component select an input method or keyboard layout by locale,
40   * getLocale lets a client component obtain the locale of the current input method
41   * or keyboard layout.
42   * The other methods more specifically support interaction with input methods:
43   * They let client components control the behavior of input methods, and
44   * dispatch events from the client component to the input method.
45   *
46   * <p>
47   * By default, one InputContext instance is created per Window instance,
48   * and this input context is shared by all components within the window's
49   * container hierarchy. However, this means that only one text input
50   * operation is possible at any one time within a window, and that the
51   * text needs to be committed when moving the focus from one text component
52   * to another. If this is not desired, text components can create their
53   * own input context instances.
54   *
55   * <p>
56   * The Java Platform supports input methods that have been developed in the Java
57   * programming language, using the interfaces in the {@link java.awt.im.spi} package,
58   * and installed into a Java SE Runtime Environment as extensions. Implementations
59   * may also support using the native input methods of the platforms they run on;
60   * however, not all platforms and locales provide input methods. Keyboard layouts
61   * are provided by the host platform.
62   *
63   * <p>
64   * Input methods are <em>unavailable</em> if (a) no input method written
65   * in the Java programming language has been installed and (b) the Java Platform implementation
66   * or the underlying platform does not support native input methods. In this case,
67   * input contexts can still be created and used; their behavior is specified with
68   * the individual methods below.
69   *
70   * @see java.awt.Component#getInputContext
71   * @see java.awt.Component#enableInputMethods
72   * @author JavaSoft Asia/Pacific
73   * @since 1.2
74   */
75  
76  public class InputContext {
77  
78      /**
79       * Constructs an InputContext.
80       * This method is protected so clients cannot instantiate
81       * InputContext directly. Input contexts are obtained by
82       * calling {@link #getInstance}.
83       */
84      protected InputContext() {
85          // real implementation is in sun.awt.im.InputContext
86      }
87  
88      /**
89       * Returns a new InputContext instance.
90       */
91      public static InputContext getInstance() {
92          return new sun.awt.im.InputMethodContext();
93      }
94  
95      /**
96       * Attempts to select an input method or keyboard layout that
97       * supports the given locale, and returns a value indicating whether such
98       * an input method or keyboard layout has been successfully selected. The
99       * following steps are taken until an input method has been selected:
100      *
101      * <ul>
102      * <li>
103      * If the currently selected input method or keyboard layout supports the
104      * requested locale, it remains selected.</li>
105      *
106      * <li>
107      * If there is no input method or keyboard layout available that supports
108      * the requested locale, the current input method or keyboard layout remains
109      * selected.</li>
110      *
111      * <li>
112      * If the user has previously selected an input method or keyboard layout
113      * for the requested locale from the user interface, then the most recently
114      * selected such input method or keyboard layout is reselected.</li>
115      *
116      * <li>
117      * Otherwise, an input method or keyboard layout that supports the requested
118      * locale is selected in an implementation dependent way.</li>
119      *
120      * </ul>
121      * Before switching away from an input method, any currently uncommitted text
122      * is committed. If no input method or keyboard layout supporting the requested
123      * locale is available, then false is returned.
124      *
125      * <p>
126      * Not all host operating systems provide API to determine the locale of
127      * the currently selected native input method or keyboard layout, and to
128      * select a native input method or keyboard layout by locale.
129      * For host operating systems that don't provide such API,
130      * <code>selectInputMethod</code> assumes that native input methods or
131      * keyboard layouts provided by the host operating system support only the
132      * system's default locale.
133      *
134      * <p>
135      * A text editing component may call this method, for example, when
136      * the user changes the insertion point, so that the user can
137      * immediately continue typing in the language of the surrounding text.
138      *
139      * @param locale The desired new locale.
140      * @return true if the input method or keyboard layout that's active after
141      *         this call supports the desired locale.
142      * @exception NullPointerException if <code>locale</code> is null
143      */
144     public boolean selectInputMethod(Locale locale) {
145         // real implementation is in sun.awt.im.InputContext
146         return false;
147     }
148 
149     /**
150      * Returns the current locale of the current input method or keyboard
151      * layout.
152      * Returns null if the input context does not have a current input method
153      * or keyboard layout or if the current input method's
154      * {@link java.awt.im.spi.InputMethod#getLocale()} method returns null.
155      *
156      * <p>
157      * Not all host operating systems provide API to determine the locale of
158      * the currently selected native input method or keyboard layout.
159      * For host operating systems that don't provide such API,
160      * <code>getLocale</code> assumes that the current locale of all native
161      * input methods or keyboard layouts provided by the host operating system
162      * is the system's default locale.
163      *
164      * @return the current locale of the current input method or keyboard layout
165      * @since 1.3
166      */
167     public Locale getLocale() {
168         // real implementation is in sun.awt.im.InputContext
169         return null;
170     }
171 
172     /**
173      * Sets the subsets of the Unicode character set that input methods of this input
174      * context should be allowed to input. Null may be passed in to
175      * indicate that all characters are allowed. The initial value
176      * is null. The setting applies to the current input method as well
177      * as input methods selected after this call is made. However,
178      * applications cannot rely on this call having the desired effect,
179      * since this setting cannot be passed on to all host input methods -
180      * applications still need to apply their own character validation.
181      * If no input methods are available, then this method has no effect.
182      *
183      * @param subsets The subsets of the Unicode character set from which characters may be input
184      */
185     public void setCharacterSubsets(Subset[] subsets) {
186         // real implementation is in sun.awt.im.InputContext
187     }
188 
189     /**
190      * Enables or disables the current input method for composition,
191      * depending on the value of the parameter <code>enable</code>.
192      * <p>
193      * An input method that is enabled for composition interprets incoming
194      * events for both composition and control purposes, while a
195      * disabled input method does not interpret events for composition.
196      * Note however that events are passed on to the input method regardless
197      * whether it is enabled or not, and that an input method that is disabled
198      * for composition may still interpret events for control purposes,
199      * including to enable or disable itself for composition.
200      * <p>
201      * For input methods provided by host operating systems, it is not always possible to
202      * determine whether this operation is supported. For example, an input method may enable
203      * composition only for some locales, and do nothing for other locales. For such input
204      * methods, it is possible that this method does not throw
205      * {@link java.lang.UnsupportedOperationException UnsupportedOperationException},
206      * but also does not affect whether composition is enabled.
207      *
208      * @param enable whether to enable the current input method for composition
209      * @throws UnsupportedOperationException if there is no current input
210      * method available or the current input method does not support
211      * the enabling/disabling operation
212      * @see #isCompositionEnabled
213      * @since 1.3
214      */
215     public void setCompositionEnabled(boolean enable) {
216         // real implementation is in sun.awt.im.InputContext
217     }
218 
219     /**
220      * Determines whether the current input method is enabled for composition.
221      * An input method that is enabled for composition interprets incoming
222      * events for both composition and control purposes, while a
223      * disabled input method does not interpret events for composition.
224      *
225      * @return <code>true</code> if the current input method is enabled for
226      * composition; <code>false</code> otherwise
227      * @throws UnsupportedOperationException if there is no current input
228      * method available or the current input method does not support
229      * checking whether it is enabled for composition
230      * @see #setCompositionEnabled
231      * @since 1.3
232      */
233     @Transient
234     public boolean isCompositionEnabled() {
235         // real implementation is in sun.awt.im.InputContext
236         return false;
237     }
238 
239     /**
240      * Asks the current input method to reconvert text from the
241      * current client component. The input method obtains the text to
242      * be reconverted from the client component using the
243      * {@link InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText}
244      * method. The other <code>InputMethodRequests</code> methods
245      * must be prepared to deal with further information requests by
246      * the input method. The composed and/or committed text will be
247      * sent to the client component as a sequence of
248      * <code>InputMethodEvent</code>s. If the input method cannot
249      * reconvert the given text, the text is returned as committed
250      * text in an <code>InputMethodEvent</code>.
251      *
252      * @throws UnsupportedOperationException if there is no current input
253      * method available or the current input method does not support
254      * the reconversion operation.
255      *
256      * @since 1.3
257      */
258     public void reconvert() {
259         // real implementation is in sun.awt.im.InputContext
260     }
261 
262     /**
263      * Dispatches an event to the active input method. Called by AWT.
264      * If no input method is available, then the event will never be consumed.
265      *
266      * @param event The event
267      * @exception NullPointerException if <code>event</code> is null
268      */
269     public void dispatchEvent(AWTEvent event) {
270         // real implementation is in sun.awt.im.InputContext
271     }
272 
273     /**
274      * Notifies the input context that a client component has been
275      * removed from its containment hierarchy, or that input method
276      * support has been disabled for the component. This method is
277      * usually called from the client component's
278      * {@link java.awt.Component#removeNotify() Component.removeNotify}
279      * method. Potentially pending input from input methods
280      * for this component is discarded.
281      * If no input methods are available, then this method has no effect.
282      *
283      * @param client Client component
284      * @exception NullPointerException if <code>client</code> is null
285      */
286     public void removeNotify(Component client) {
287         // real implementation is in sun.awt.im.InputContext
288     }
289 
290     /**
291      * Ends any input composition that may currently be going on in this
292      * context. Depending on the platform and possibly user preferences,
293      * this may commit or delete uncommitted text. Any changes to the text
294      * are communicated to the active component using an input method event.
295      * If no input methods are available, then this method has no effect.
296      *
297      * <p>
298      * A text editing component may call this in a variety of situations,
299      * for example, when the user moves the insertion point within the text
300      * (but outside the composed text), or when the component's text is
301      * saved to a file or copied to the clipboard.
302      *
303      */
304     public void endComposition() {
305         // real implementation is in sun.awt.im.InputContext
306     }
307 
308     /**
309      * Releases the resources used by this input context.
310      * Called by AWT for the default input context of each Window.
311      * If no input methods are available, then this method
312      * has no effect.
313      */
314     public void dispose() {
315         // real implementation is in sun.awt.im.InputContext
316     }
317 
318     /**
319      * Returns a control object from the current input method, or null. A
320      * control object provides methods that control the behavior of the
321      * input method or obtain information from the input method. The type
322      * of the object is an input method specific class. Clients have to
323      * compare the result against known input method control object
324      * classes and cast to the appropriate class to invoke the methods
325      * provided.
326      * <p>
327      * If no input methods are available or the current input method does
328      * not provide an input method control object, then null is returned.
329      *
330      * @return A control object from the current input method, or null.
331      */
332     public Object getInputMethodControlObject() {
333         // real implementation is in sun.awt.im.InputContext
334         return null;
335     }
336 
337 }