1/*
2 * Copyright (c) 1997, 2014, 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
26package java.awt.im;
27
28import java.awt.Component;
29import java.util.Locale;
30import java.awt.AWTEvent;
31import java.beans.Transient;
32import java.lang.Character.Subset;
33import 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
76public 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     * @return a new InputContext instance
91     */
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     */
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     */
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     */
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     */
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
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     */
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     */
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     */
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     */
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     */
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     */
333    public Object getInputMethodControlObject() {
334        // real implementation is in sun.awt.im.InputContext
335        return null;
336    }
337
338}
339