001: /*
002: * @(#)InputContext.java 1.33 04/02/17
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.awt.im;
028:
029: import java.awt.Component;
030: import java.util.Locale;
031: import java.awt.AWTEvent;
032: import java.lang.Character.Subset;
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 2 platform supports input methods that have been developed in the Java
056: * programming language, using the interfaces in the {@link sun.awt.im.spi} package,
057: * and installed into a Java 2 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 2 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.33, 02/17/04
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 sun.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: *
203: * @param enable whether to enable the current input method for composition
204: * @throws UnsupportedOperationException if there is no current input
205: * method available or the current input method does not support
206: * the enabling/disabling operation
207: * @see #isCompositionEnabled
208: * @since 1.3
209: */
210: public void setCompositionEnabled(boolean enable) {
211: // real implementation is in sun.awt.im.InputContext
212: }
213:
214: /**
215: * Determines whether the current input method is enabled for composition.
216: * An input method that is enabled for composition interprets incoming
217: * events for both composition and control purposes, while a
218: * disabled input method does not interpret events for composition.
219: *
220: * @return <code>true</code> if the current input method is enabled for
221: * composition; <code>false</code> otherwise
222: * @throws UnsupportedOperationException if there is no current input
223: * method available or the current input method does not support
224: * checking whether it is enabled for composition
225: * @see #setCompositionEnabled
226: * @since 1.3
227: */
228: public boolean isCompositionEnabled() {
229: // real implementation is in sun.awt.im.InputContext
230: return false;
231: }
232:
233: /**
234: * Asks the current input method to reconvert text from the
235: * current client component. The input method obtains the text to
236: * be reconverted from the client component using the
237: * {@link InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText}
238: * method. The other <code>InputMethodRequests</code> methods
239: * must be prepared to deal with further information requests by
240: * the input method. The composed and/or committed text will be
241: * sent to the client component as a sequence of
242: * <code>InputMethodEvent</code>s. If the input method cannot
243: * reconvert the given text, the text is returned as committed
244: * text in an <code>InputMethodEvent</code>.
245: *
246: * @throws UnsupportedOperationException if there is no current input
247: * method available or the current input method does not support
248: * the reconversion operation.
249: *
250: * @since 1.3
251: */
252: public void reconvert() {
253: // real implementation is in sun.awt.im.InputContext
254: }
255:
256: /**
257: * Dispatches an event to the active input method. Called by AWT.
258: * If no input method is available, then the event will never be consumed.
259: *
260: * @param event The event
261: * @exception NullPointerException if <code>event</code> is null
262: */
263: public void dispatchEvent(AWTEvent event) {
264: // real implementation is in sun.awt.im.InputContext
265: }
266:
267: /**
268: * Notifies the input context that a client component has been
269: * removed from its containment hierarchy, or that input method
270: * support has been disabled for the component. This method is
271: * usually called from the client component's
272: * {@link java.awt.Component#removeNotify() Component.removeNotify}
273: * method. Potentially pending input from input methods
274: * for this component is discarded.
275: * If no input methods are available, then this method has no effect.
276: *
277: * @param client Client component
278: * @exception NullPointerException if <code>client</code> is null
279: */
280: public void removeNotify(Component client) {
281: // real implementation is in sun.awt.im.InputContext
282: }
283:
284: /**
285: * Ends any input composition that may currently be going on in this
286: * context. Depending on the platform and possibly user preferences,
287: * this may commit or delete uncommitted text. Any changes to the text
288: * are communicated to the active component using an input method event.
289: * If no input methods are available, then this method has no effect.
290: *
291: * <p>
292: * A text editing component may call this in a variety of situations,
293: * for example, when the user moves the insertion point within the text
294: * (but outside the composed text), or when the component's text is
295: * saved to a file or copied to the clipboard.
296: *
297: */
298: public void endComposition() {
299: // real implementation is in sun.awt.im.InputContext
300: }
301:
302: /**
303: * Disposes of the input context and release the resources used by it.
304: * Called by AWT for the default input context of each Window.
305: * If no input methods are available, then this method
306: * has no effect.
307: */
308: public void dispose() {
309: // real implementation is in sun.awt.im.InputContext
310: }
311:
312: /**
313: * Returns a control object from the current input method, or null. A
314: * control object provides methods that control the behavior of the
315: * input method or obtain information from the input method. The type
316: * of the object is an input method specific class. Clients have to
317: * compare the result against known input method control object
318: * classes and cast to the appropriate class to invoke the methods
319: * provided.
320: * <p>
321: * If no input methods are available or the current input method does
322: * not provide an input method control object, then null is returned.
323: *
324: * @return A control object from the current input method, or null.
325: */
326: public Object getInputMethodControlObject() {
327: // real implementation is in sun.awt.im.InputContext
328: return null;
329: }
330:
331: }
|