Class InputContext

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.

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.

The Java Platform supports input methods that have been developed in the Java programming language, using the interfaces in the 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.

Input methods are unavailable 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.

Constructors

InputContext

protected InputContext()

Constructs an InputContext. This method is protected so clients cannot instantiate InputContext directly. Input contexts are obtained by calling getInstance().

Methods

getInstance

public static InputContext getInstance()

Returns a new InputContext instance.

selectInputMethod

public boolean selectInputMethod(Locale locale)

Parameters:

locale - The desired new locale.

Returns:

true if the input method or keyboard layout that's active after this call supports the desired locale.

Throws:

NullPointerException - if locale is null

getLocale

public Locale getLocale()

Returns:

the current locale of the current input method or keyboard layout

Since:

1.3

setCharacterSubsets

public void setCharacterSubsets(Character.Subset[] subsets)

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.

Parameters:

subsets - The subsets of the Unicode character set from which characters may be input

setCompositionEnabled

public void setCompositionEnabled(boolean enable)

Parameters:

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

Since:

1.3

See Also:

isCompositionEnabled()

isCompositionEnabled

public boolean isCompositionEnabled()

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.

Returns:

true if the current input method is enabled for composition; false 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

Since:

1.3

See Also:

setCompositionEnabled(boolean)

reconvert

public void reconvert()

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 InputMethodRequests.getSelectedText method. The other InputMethodRequests 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 InputMethodEvents. If the input method cannot reconvert the given text, the text is returned as committed text in an InputMethodEvent.

Throws:

UnsupportedOperationException - if there is no current input method available or the current input method does not support the reconversion operation.

Since:

1.3

dispatchEvent

public void dispatchEvent(AWTEvent event)

Dispatches an event to the active input method. Called by AWT. If no input method is available, then the event will never be consumed.

Parameters:

event - The event

Throws:

NullPointerException - if event is null

removeNotify

public void removeNotify(Component client)

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 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.

Parameters:

client - Client component

Throws:

NullPointerException - if client is null

endComposition

public void endComposition()

dispose

public void dispose()

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.

getInputMethodControlObject

public Object getInputMethodControlObject()

Returns:

A control object from the current input method, or null.