1 /*
2  * Copyright (c) 1997, 2017, 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  * which can be made available by adding them to the application's class path.
59  * Implementations 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      */
InputContext()84     protected InputContext() {
85         // real implementation is in sun.awt.im.InputContext
86     }
87 
88     /**
89      * Returns a new InputContext instance.
90      * @return a new InputContext instance
91      */
getInstance()92     public static InputContext getInstance() {
93         return new sun.awt.im.InputMethodContext();
94     }
95 
96     /**
97      * Attempts to select an input method or keyboard layout that
98      * supports the given locale, and returns a value indicating whether such
99      * an input method or keyboard layout has been successfully selected. The
100      * following steps are taken until an input method has been selected:
101      *
102      * <ul>
103      * <li>
104      * If the currently selected input method or keyboard layout supports the
105      * requested locale, it remains selected.</li>
106      *
107      * <li>
108      * If there is no input method or keyboard layout available that supports
109      * the requested locale, the current input method or keyboard layout remains
110      * selected.</li>
111      *
112      * <li>
113      * If the user has previously selected an input method or keyboard layout
114      * for the requested locale from the user interface, then the most recently
115      * selected such input method or keyboard layout is reselected.</li>
116      *
117      * <li>
118      * Otherwise, an input method or keyboard layout that supports the requested
119      * locale is selected in an implementation dependent way.</li>
120      *
121      * </ul>
122      * Before switching away from an input method, any currently uncommitted text
123      * is committed. If no input method or keyboard layout supporting the requested
124      * locale is available, then false is returned.
125      *
126      * <p>
127      * Not all host operating systems provide API to determine the locale of
128      * the currently selected native input method or keyboard layout, and to
129      * select a native input method or keyboard layout by locale.
130      * For host operating systems that don't provide such API,
131      * {@code selectInputMethod} assumes that native input methods or
132      * keyboard layouts provided by the host operating system support only the
133      * system's default locale.
134      *
135      * <p>
136      * A text editing component may call this method, for example, when
137      * the user changes the insertion point, so that the user can
138      * immediately continue typing in the language of the surrounding text.
139      *
140      * @param locale The desired new locale.
141      * @return true if the input method or keyboard layout that's active after
142      *         this call supports the desired locale.
143      * @exception NullPointerException if {@code locale} is null
144      */
selectInputMethod(Locale locale)145     public boolean selectInputMethod(Locale locale) {
146         // real implementation is in sun.awt.im.InputContext
147         return false;
148     }
149 
150     /**
151      * Returns the current locale of the current input method or keyboard
152      * layout.
153      * Returns null if the input context does not have a current input method
154      * or keyboard layout or if the current input method's
155      * {@link java.awt.im.spi.InputMethod#getLocale()} method returns null.
156      *
157      * <p>
158      * Not all host operating systems provide API to determine the locale of
159      * the currently selected native input method or keyboard layout.
160      * For host operating systems that don't provide such API,
161      * {@code getLocale} assumes that the current locale of all native
162      * input methods or keyboard layouts provided by the host operating system
163      * is the system's default locale.
164      *
165      * @return the current locale of the current input method or keyboard layout
166      * @since 1.3
167      */
getLocale()168     public Locale getLocale() {
169         // real implementation is in sun.awt.im.InputContext
170         return null;
171     }
172 
173     /**
174      * Sets the subsets of the Unicode character set that input methods of this input
175      * context should be allowed to input. Null may be passed in to
176      * indicate that all characters are allowed. The initial value
177      * is null. The setting applies to the current input method as well
178      * as input methods selected after this call is made. However,
179      * applications cannot rely on this call having the desired effect,
180      * since this setting cannot be passed on to all host input methods -
181      * applications still need to apply their own character validation.
182      * If no input methods are available, then this method has no effect.
183      *
184      * @param subsets The subsets of the Unicode character set from which characters may be input
185      */
setCharacterSubsets(Subset[] subsets)186     public void setCharacterSubsets(Subset[] subsets) {
187         // real implementation is in sun.awt.im.InputContext
188     }
189 
190     /**
191      * Enables or disables the current input method for composition,
192      * depending on the value of the parameter {@code enable}.
193      * <p>
194      * An input method that is enabled for composition interprets incoming
195      * events for both composition and control purposes, while a
196      * disabled input method does not interpret events for composition.
197      * Note however that events are passed on to the input method regardless
198      * whether it is enabled or not, and that an input method that is disabled
199      * for composition may still interpret events for control purposes,
200      * including to enable or disable itself for composition.
201      * <p>
202      * For input methods provided by host operating systems, it is not always possible to
203      * determine whether this operation is supported. For example, an input method may enable
204      * composition only for some locales, and do nothing for other locales. For such input
205      * methods, it is possible that this method does not throw
206      * {@link java.lang.UnsupportedOperationException UnsupportedOperationException},
207      * but also does not affect whether composition is enabled.
208      *
209      * @param enable whether to enable the current input method for composition
210      * @throws UnsupportedOperationException if there is no current input
211      * method available or the current input method does not support
212      * the enabling/disabling operation
213      * @see #isCompositionEnabled
214      * @since 1.3
215      */
setCompositionEnabled(boolean enable)216     public void setCompositionEnabled(boolean enable) {
217         // real implementation is in sun.awt.im.InputContext
218     }
219 
220     /**
221      * Determines whether the current input method is enabled for composition.
222      * An input method that is enabled for composition interprets incoming
223      * events for both composition and control purposes, while a
224      * disabled input method does not interpret events for composition.
225      *
226      * @return {@code true} if the current input method is enabled for
227      * composition; {@code false} otherwise
228      * @throws UnsupportedOperationException if there is no current input
229      * method available or the current input method does not support
230      * checking whether it is enabled for composition
231      * @see #setCompositionEnabled
232      * @since 1.3
233      */
234     @Transient
isCompositionEnabled()235     public boolean isCompositionEnabled() {
236         // real implementation is in sun.awt.im.InputContext
237         return false;
238     }
239 
240     /**
241      * Asks the current input method to reconvert text from the
242      * current client component. The input method obtains the text to
243      * be reconverted from the client component using the
244      * {@link InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText}
245      * method. The other {@code InputMethodRequests} methods
246      * must be prepared to deal with further information requests by
247      * the input method. The composed and/or committed text will be
248      * sent to the client component as a sequence of
249      * {@code InputMethodEvent}s. If the input method cannot
250      * reconvert the given text, the text is returned as committed
251      * text in an {@code InputMethodEvent}.
252      *
253      * @throws UnsupportedOperationException if there is no current input
254      * method available or the current input method does not support
255      * the reconversion operation.
256      *
257      * @since 1.3
258      */
reconvert()259     public void reconvert() {
260         // real implementation is in sun.awt.im.InputContext
261     }
262 
263     /**
264      * Dispatches an event to the active input method. Called by AWT.
265      * If no input method is available, then the event will never be consumed.
266      *
267      * @param event The event
268      * @exception NullPointerException if {@code event} is null
269      */
dispatchEvent(AWTEvent event)270     public void dispatchEvent(AWTEvent event) {
271         // real implementation is in sun.awt.im.InputContext
272     }
273 
274     /**
275      * Notifies the input context that a client component has been
276      * removed from its containment hierarchy, or that input method
277      * support has been disabled for the component. This method is
278      * usually called from the client component's
279      * {@link java.awt.Component#removeNotify() Component.removeNotify}
280      * method. Potentially pending input from input methods
281      * for this component is discarded.
282      * If no input methods are available, then this method has no effect.
283      *
284      * @param client Client component
285      * @exception NullPointerException if {@code client} is null
286      */
removeNotify(Component client)287     public void removeNotify(Component client) {
288         // real implementation is in sun.awt.im.InputContext
289     }
290 
291     /**
292      * Ends any input composition that may currently be going on in this
293      * context. Depending on the platform and possibly user preferences,
294      * this may commit or delete uncommitted text. Any changes to the text
295      * are communicated to the active component using an input method event.
296      * If no input methods are available, then this method has no effect.
297      *
298      * <p>
299      * A text editing component may call this in a variety of situations,
300      * for example, when the user moves the insertion point within the text
301      * (but outside the composed text), or when the component's text is
302      * saved to a file or copied to the clipboard.
303      *
304      */
endComposition()305     public void endComposition() {
306         // real implementation is in sun.awt.im.InputContext
307     }
308 
309     /**
310      * Releases the resources used by this input context.
311      * Called by AWT for the default input context of each Window.
312      * If no input methods are available, then this method
313      * has no effect.
314      */
dispose()315     public void dispose() {
316         // real implementation is in sun.awt.im.InputContext
317     }
318 
319     /**
320      * Returns a control object from the current input method, or null. A
321      * control object provides methods that control the behavior of the
322      * input method or obtain information from the input method. The type
323      * of the object is an input method specific class. Clients have to
324      * compare the result against known input method control object
325      * classes and cast to the appropriate class to invoke the methods
326      * provided.
327      * <p>
328      * If no input methods are available or the current input method does
329      * not provide an input method control object, then null is returned.
330      *
331      * @return A control object from the current input method, or null.
332      */
getInputMethodControlObject()333     public Object getInputMethodControlObject() {
334         // real implementation is in sun.awt.im.InputContext
335         return null;
336     }
337 
338 }
339