| /* |
| * Copyright (c) 1997, 2008, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package java.awt.im; |
| |
| import java.awt.Component; |
| import java.util.Locale; |
| import java.awt.AWTEvent; |
| import java.beans.Transient; |
| import java.lang.Character.Subset; |
| import sun.awt.im.InputMethodContext; |
| |
| /** |
| * Provides methods to control text input facilities such as input |
| * methods and keyboard layouts. |
| * Two methods handle both input methods and keyboard layouts: selectInputMethod |
| * lets a client component select an input method or keyboard layout by locale, |
| * getLocale lets a client component obtain the locale of the current input method |
| * or keyboard layout. |
| * The other methods more specifically support interaction with input methods: |
| * They let client components control the behavior of input methods, and |
| * dispatch events from the client component to the input method. |
| * |
| * <p> |
| * By default, one InputContext instance is created per Window instance, |
| * and this input context is shared by all components within the window's |
| * container hierarchy. However, this means that only one text input |
| * operation is possible at any one time within a window, and that the |
| * text needs to be committed when moving the focus from one text component |
| * to another. If this is not desired, text components can create their |
| * own input context instances. |
| * |
| * <p> |
| * The Java Platform supports input methods that have been developed in the Java |
| * programming language, using the interfaces in the {@link java.awt.im.spi} package, |
| * and installed into a Java SE Runtime Environment as extensions. Implementations |
| * may also support using the native input methods of the platforms they run on; |
| * however, not all platforms and locales provide input methods. Keyboard layouts |
| * are provided by the host platform. |
| * |
| * <p> |
| * Input methods are <em>unavailable</em> if (a) no input method written |
| * in the Java programming language has been installed and (b) the Java Platform implementation |
| * or the underlying platform does not support native input methods. In this case, |
| * input contexts can still be created and used; their behavior is specified with |
| * the individual methods below. |
| * |
| * @see java.awt.Component#getInputContext |
| * @see java.awt.Component#enableInputMethods |
| * @author JavaSoft Asia/Pacific |
| * @since 1.2 |
| */ |
| |
| public class InputContext { |
| |
| /** |
| * Constructs an InputContext. |
| * This method is protected so clients cannot instantiate |
| * InputContext directly. Input contexts are obtained by |
| * calling {@link #getInstance}. |
| */ |
| protected InputContext() { |
| // real implementation is in sun.awt.im.InputContext |
| } |
| |
| /** |
| * Returns a new InputContext instance. |
| */ |
| public static InputContext getInstance() { |
| return new sun.awt.im.InputMethodContext(); |
| } |
| |
| /** |
| * Attempts to select an input method or keyboard layout that |
| * supports the given locale, and returns a value indicating whether such |
| * an input method or keyboard layout has been successfully selected. The |
| * following steps are taken until an input method has been selected: |
| * |
| * <p> |
| * <ul> |
| * <li> |
| * If the currently selected input method or keyboard layout supports the |
| * requested locale, it remains selected.</li> |
| * |
| * <li> |
| * If there is no input method or keyboard layout available that supports |
| * the requested locale, the current input method or keyboard layout remains |
| * selected.</li> |
| * |
| * <li> |
| * If the user has previously selected an input method or keyboard layout |
| * for the requested locale from the user interface, then the most recently |
| * selected such input method or keyboard layout is reselected.</li> |
| * |
| * <li> |
| * Otherwise, an input method or keyboard layout that supports the requested |
| * locale is selected in an implementation dependent way.</li> |
| * |
| * <p> |
| * </ul> |
| * Before switching away from an input method, any currently uncommitted text |
| * is committed. If no input method or keyboard layout supporting the requested |
| * locale is available, then false is returned. |
| * |
| * <p> |
| * Not all host operating systems provide API to determine the locale of |
| * the currently selected native input method or keyboard layout, and to |
| * select a native input method or keyboard layout by locale. |
| * For host operating systems that don't provide such API, |
| * <code>selectInputMethod</code> assumes that native input methods or |
| * keyboard layouts provided by the host operating system support only the |
| * system's default locale. |
| * |
| * <p> |
| * A text editing component may call this method, for example, when |
| * the user changes the insertion point, so that the user can |
| * immediately continue typing in the language of the surrounding text. |
| * |
| * @param locale The desired new locale. |
| * @return true if the input method or keyboard layout that's active after |
| * this call supports the desired locale. |
| * @exception NullPointerException if <code>locale</code> is null |
| */ |
| public boolean selectInputMethod(Locale locale) { |
| // real implementation is in sun.awt.im.InputContext |
| return false; |
| } |
| |
| /** |
| * Returns the current locale of the current input method or keyboard |
| * layout. |
| * Returns null if the input context does not have a current input method |
| * or keyboard layout or if the current input method's |
| * {@link java.awt.im.spi.InputMethod#getLocale()} method returns null. |
| * |
| * <p> |
| * Not all host operating systems provide API to determine the locale of |
| * the currently selected native input method or keyboard layout. |
| * For host operating systems that don't provide such API, |
| * <code>getLocale</code> assumes that the current locale of all native |
| * input methods or keyboard layouts provided by the host operating system |
| * is the system's default locale. |
| * |
| * @return the current locale of the current input method or keyboard layout |
| * @since 1.3 |
| */ |
| public Locale getLocale() { |
| // real implementation is in sun.awt.im.InputContext |
| return null; |
| } |
| |
| /** |
| * Sets the subsets of the Unicode character set that input methods of this input |
| * context should be allowed to input. Null may be passed in to |
| * indicate that all characters are allowed. The initial value |
| * is null. The setting applies to the current input method as well |
| * as input methods selected after this call is made. However, |
| * applications cannot rely on this call having the desired effect, |
| * since this setting cannot be passed on to all host input methods - |
| * applications still need to apply their own character validation. |
| * If no input methods are available, then this method has no effect. |
| * |
| * @param subsets The subsets of the Unicode character set from which characters may be input |
| */ |
| public void setCharacterSubsets(Subset[] subsets) { |
| // real implementation is in sun.awt.im.InputContext |
| } |
| |
| /** |
| * Enables or disables the current input method for composition, |
| * depending on the value of the parameter <code>enable</code>. |
| * <p> |
| * An input method that is enabled for composition interprets incoming |
| * events for both composition and control purposes, while a |
| * disabled input method does not interpret events for composition. |
| * Note however that events are passed on to the input method regardless |
| * whether it is enabled or not, and that an input method that is disabled |
| * for composition may still interpret events for control purposes, |
| * including to enable or disable itself for composition. |
| * <p> |
| * For input methods provided by host operating systems, it is not always possible to |
| * determine whether this operation is supported. For example, an input method may enable |
| * composition only for some locales, and do nothing for other locales. For such input |
| * methods, it is possible that this method does not throw |
| * {@link java.lang.UnsupportedOperationException UnsupportedOperationException}, |
| * but also does not affect whether composition is enabled. |
| * |
| * @param enable whether to enable the current input method for composition |
| * @throws UnsupportedOperationException if there is no current input |
| * method available or the current input method does not support |
| * the enabling/disabling operation |
| * @see #isCompositionEnabled |
| * @since 1.3 |
| */ |
| public void setCompositionEnabled(boolean enable) { |
| // real implementation is in sun.awt.im.InputContext |
| } |
| |
| /** |
| * Determines whether the current input method is enabled for composition. |
| * An input method that is enabled for composition interprets incoming |
| * events for both composition and control purposes, while a |
| * disabled input method does not interpret events for composition. |
| * |
| * @return <code>true</code> if the current input method is enabled for |
| * composition; <code>false</code> otherwise |
| * @throws UnsupportedOperationException if there is no current input |
| * method available or the current input method does not support |
| * checking whether it is enabled for composition |
| * @see #setCompositionEnabled |
| * @since 1.3 |
| */ |
| @Transient |
| public boolean isCompositionEnabled() { |
| // real implementation is in sun.awt.im.InputContext |
| return false; |
| } |
| |
| /** |
| * Asks the current input method to reconvert text from the |
| * current client component. The input method obtains the text to |
| * be reconverted from the client component using the |
| * {@link InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText} |
| * method. The other <code>InputMethodRequests</code> methods |
| * must be prepared to deal with further information requests by |
| * the input method. The composed and/or committed text will be |
| * sent to the client component as a sequence of |
| * <code>InputMethodEvent</code>s. If the input method cannot |
| * reconvert the given text, the text is returned as committed |
| * text in an <code>InputMethodEvent</code>. |
| * |
| * @throws UnsupportedOperationException if there is no current input |
| * method available or the current input method does not support |
| * the reconversion operation. |
| * |
| * @since 1.3 |
| */ |
| public void reconvert() { |
| // real implementation is in sun.awt.im.InputContext |
| } |
| |
| /** |
| * Dispatches an event to the active input method. Called by AWT. |
| * If no input method is available, then the event will never be consumed. |
| * |
| * @param event The event |
| * @exception NullPointerException if <code>event</code> is null |
| */ |
| public void dispatchEvent(AWTEvent event) { |
| // real implementation is in sun.awt.im.InputContext |
| } |
| |
| /** |
| * Notifies the input context that a client component has been |
| * removed from its containment hierarchy, or that input method |
| * support has been disabled for the component. This method is |
| * usually called from the client component's |
| * {@link java.awt.Component#removeNotify() Component.removeNotify} |
| * method. Potentially pending input from input methods |
| * for this component is discarded. |
| * If no input methods are available, then this method has no effect. |
| * |
| * @param client Client component |
| * @exception NullPointerException if <code>client</code> is null |
| */ |
| public void removeNotify(Component client) { |
| // real implementation is in sun.awt.im.InputContext |
| } |
| |
| /** |
| * Ends any input composition that may currently be going on in this |
| * context. Depending on the platform and possibly user preferences, |
| * this may commit or delete uncommitted text. Any changes to the text |
| * are communicated to the active component using an input method event. |
| * If no input methods are available, then this method has no effect. |
| * |
| * <p> |
| * A text editing component may call this in a variety of situations, |
| * for example, when the user moves the insertion point within the text |
| * (but outside the composed text), or when the component's text is |
| * saved to a file or copied to the clipboard. |
| * |
| */ |
| public void endComposition() { |
| // real implementation is in sun.awt.im.InputContext |
| } |
| |
| /** |
| * Releases the resources used by this input context. |
| * Called by AWT for the default input context of each Window. |
| * If no input methods are available, then this method |
| * has no effect. |
| */ |
| public void dispose() { |
| // real implementation is in sun.awt.im.InputContext |
| } |
| |
| /** |
| * Returns a control object from the current input method, or null. A |
| * control object provides methods that control the behavior of the |
| * input method or obtain information from the input method. The type |
| * of the object is an input method specific class. Clients have to |
| * compare the result against known input method control object |
| * classes and cast to the appropriate class to invoke the methods |
| * provided. |
| * <p> |
| * If no input methods are available or the current input method does |
| * not provide an input method control object, then null is returned. |
| * |
| * @return A control object from the current input method, or null. |
| */ |
| public Object getInputMethodControlObject() { |
| // real implementation is in sun.awt.im.InputContext |
| return null; |
| } |
| |
| } |