001 /*
002 * Copyright 1997-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.im;
027
028 import java.awt.Component;
029 import java.util.Locale;
030 import java.awt.AWTEvent;
031 import java.lang.Character.Subset;
032 import sun.awt.im.InputMethodContext;
033
034 /**
035 * Provides methods to control text input facilities such as input
036 * methods and keyboard layouts.
037 * Two methods handle both input methods and keyboard layouts: selectInputMethod
038 * lets a client component select an input method or keyboard layout by locale,
039 * getLocale lets a client component obtain the locale of the current input method
040 * or keyboard layout.
041 * The other methods more specifically support interaction with input methods:
042 * They let client components control the behavior of input methods, and
043 * dispatch events from the client component to the input method.
044 *
045 * <p>
046 * By default, one InputContext instance is created per Window instance,
047 * and this input context is shared by all components within the window's
048 * container hierarchy. However, this means that only one text input
049 * operation is possible at any one time within a window, and that the
050 * text needs to be committed when moving the focus from one text component
051 * to another. If this is not desired, text components can create their
052 * own input context instances.
053 *
054 * <p>
055 * The Java Platform supports input methods that have been developed in the Java
056 * programming language, using the interfaces in the {@link java.awt.im.spi} package,
057 * and installed into a Java SE Runtime Environment as extensions. Implementations
058 * may also support using the native input methods of the platforms they run on;
059 * however, not all platforms and locales provide input methods. Keyboard layouts
060 * are provided by the host platform.
061 *
062 * <p>
063 * Input methods are <em>unavailable</em> if (a) no input method written
064 * in the Java programming language has been installed and (b) the Java Platform implementation
065 * or the underlying platform does not support native input methods. In this case,
066 * input contexts can still be created and used; their behavior is specified with
067 * the individual methods below.
068 *
069 * @see java.awt.Component#getInputContext
070 * @see java.awt.Component#enableInputMethods
071 * @version 1.43, 05/05/07
072 * @author JavaSoft Asia/Pacific
073 * @since 1.2
074 */
075
076 public class InputContext {
077
078 /**
079 * Constructs an InputContext.
080 * This method is protected so clients cannot instantiate
081 * InputContext directly. Input contexts are obtained by
082 * calling {@link #getInstance}.
083 */
084 protected InputContext() {
085 // real implementation is in sun.awt.im.InputContext
086 }
087
088 /**
089 * Returns a new InputContext instance.
090 */
091 public static InputContext getInstance() {
092 return new sun.awt.im.InputMethodContext();
093 }
094
095 /**
096 * Attempts to select an input method or keyboard layout that
097 * supports the given locale, and returns a value indicating whether such
098 * an input method or keyboard layout has been successfully selected. The
099 * 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 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</code> 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</code>s. If the input method cannot
250 * reconvert the given text, the text is returned as committed
251 * text in an <code>InputMethodEvent</code>.
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</code> 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</code> 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 }
|