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