Back to index...

	/*
	* Copyright (c) 1997, 2013, 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:
	*
	* <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>
	*
	* </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;
	}

	}

Back to index...