java.awt.im
Class InputContext

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by java.awt.im.InputContext

public class InputContext
extends Object sample code for java.lang.Object definition code for java.lang.Object

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

Since:
1.2
See Also:
Component.getInputContext() sample code for java.awt.Component.getInputContext() definition code for java.awt.Component.getInputContext() , Component.enableInputMethods(boolean) sample code for java.awt.Component.enableInputMethods(boolean) definition code for java.awt.Component.enableInputMethods(boolean)

Constructor Summary
protected InputContext sample code for java.awt.im.InputContext.InputContext() definition code for java.awt.im.InputContext.InputContext() ()
          Constructs an InputContext.
 
Method Summary
 void dispatchEvent sample code for java.awt.im.InputContext.dispatchEvent(java.awt.AWTEvent) definition code for java.awt.im.InputContext.dispatchEvent(java.awt.AWTEvent) (AWTEvent sample code for java.awt.AWTEvent definition code for java.awt.AWTEvent  event)
          Dispatches an event to the active input method.
 void dispose sample code for java.awt.im.InputContext.dispose() definition code for java.awt.im.InputContext.dispose() ()
          Disposes of the input context and release the resources used by it.
 void endComposition sample code for java.awt.im.InputContext.endComposition() definition code for java.awt.im.InputContext.endComposition() ()
          Ends any input composition that may currently be going on in this context.
 Object sample code for java.lang.Object definition code for java.lang.Object getInputMethodControlObject sample code for java.awt.im.InputContext.getInputMethodControlObject() definition code for java.awt.im.InputContext.getInputMethodControlObject() ()
          Returns a control object from the current input method, or null.
static InputContext sample code for java.awt.im.InputContext definition code for java.awt.im.InputContext getInstance sample code for java.awt.im.InputContext.getInstance() definition code for java.awt.im.InputContext.getInstance() ()
          Returns a new InputContext instance.
 Locale sample code for java.util.Locale definition code for java.util.Locale getLocale sample code for java.awt.im.InputContext.getLocale() definition code for java.awt.im.InputContext.getLocale() ()
          Returns the current locale of the current input method or keyboard layout.
 boolean isCompositionEnabled sample code for java.awt.im.InputContext.isCompositionEnabled() definition code for java.awt.im.InputContext.isCompositionEnabled() ()
          Determines whether the current input method is enabled for composition.
 void reconvert sample code for java.awt.im.InputContext.reconvert() definition code for java.awt.im.InputContext.reconvert() ()
          Asks the current input method to reconvert text from the current client component.
 void removeNotify sample code for java.awt.im.InputContext.removeNotify(java.awt.Component) definition code for java.awt.im.InputContext.removeNotify(java.awt.Component) (Component sample code for java.awt.Component definition code for java.awt.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.
 boolean selectInputMethod sample code for java.awt.im.InputContext.selectInputMethod(java.util.Locale) definition code for java.awt.im.InputContext.selectInputMethod(java.util.Locale) (Locale sample code for java.util.Locale definition code for java.util.Locale  locale)
          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.
 void setCharacterSubsets sample code for java.awt.im.InputContext.setCharacterSubsets(java.lang.Character.Subset[]) definition code for java.awt.im.InputContext.setCharacterSubsets(java.lang.Character.Subset[]) (Character.Subset sample code for java.lang.Character.Subset definition code for java.lang.Character.Subset [] subsets)
          Sets the subsets of the Unicode character set that input methods of this input context should be allowed to input.
 void setCompositionEnabled sample code for java.awt.im.InputContext.setCompositionEnabled(boolean) definition code for java.awt.im.InputContext.setCompositionEnabled(boolean) (boolean enable)
          Enables or disables the current input method for composition, depending on the value of the parameter enable.
 
Methods inherited from class java.lang.Object sample code for java.lang.Object definition code for java.lang.Object
clone sample code for java.lang.Object.clone() definition code for java.lang.Object.clone() , equals sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) , finalize sample code for java.lang.Object.finalize() definition code for java.lang.Object.finalize() , getClass sample code for java.lang.Object.getClass() definition code for java.lang.Object.getClass() , hashCode sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode() , notify sample code for java.lang.Object.notify() definition code for java.lang.Object.notify() , notifyAll sample code for java.lang.Object.notifyAll() definition code for java.lang.Object.notifyAll() , toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() , wait sample code for java.lang.Object.wait() definition code for java.lang.Object.wait() , wait sample code for java.lang.Object.wait(long) definition code for java.lang.Object.wait(long) , wait sample code for java.lang.Object.wait(long, int) definition code for java.lang.Object.wait(long, int)
 

Constructor Detail

InputContext sample code for java.awt.im.InputContext() definition code for java.awt.im.InputContext()

protected InputContext()
Constructs an InputContext. This method is protected so clients cannot instantiate InputContext directly. Input contexts are obtained by calling getInstance() sample code for java.awt.im.InputContext.getInstance() definition code for java.awt.im.InputContext.getInstance() .

Method Detail

getInstance sample code for java.awt.im.InputContext.getInstance() definition code for java.awt.im.InputContext.getInstance()

public static InputContext sample code for java.awt.im.InputContext definition code for java.awt.im.InputContext  getInstance()
Returns a new InputContext instance.


selectInputMethod sample code for java.awt.im.InputContext.selectInputMethod(java.util.Locale) definition code for java.awt.im.InputContext.selectInputMethod(java.util.Locale)

public boolean selectInputMethod(Locale sample code for java.util.Locale definition code for java.util.Locale  locale)
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:

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.

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, selectInputMethod assumes that native input methods or keyboard layouts provided by the host operating system support only the system's default locale.

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.

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 sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if locale is null

getLocale sample code for java.awt.im.InputContext.getLocale() definition code for java.awt.im.InputContext.getLocale()

public Locale sample code for java.util.Locale definition code for java.util.Locale  getLocale()
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 InputMethod.getLocale() sample code for java.awt.im.spi.InputMethod.getLocale() definition code for java.awt.im.spi.InputMethod.getLocale() method returns null.

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

Returns:
the current locale of the current input method or keyboard layout
Since:
1.3

setCharacterSubsets sample code for java.awt.im.InputContext.setCharacterSubsets(java.lang.Character.Subset[]) definition code for java.awt.im.InputContext.setCharacterSubsets(java.lang.Character.Subset[])

public void setCharacterSubsets(Character.Subset sample code for java.lang.Character.Subset definition code for java.lang.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 sample code for java.awt.im.InputContext.setCompositionEnabled(boolean) definition code for java.awt.im.InputContext.setCompositionEnabled(boolean)

public void setCompositionEnabled(boolean enable)
Enables or disables the current input method for composition, depending on the value of the parameter enable.

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.

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 UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException , but also does not affect whether composition is enabled.

Parameters:
enable - whether to enable the current input method for composition
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.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() sample code for java.awt.im.InputContext.isCompositionEnabled() definition code for java.awt.im.InputContext.isCompositionEnabled()

isCompositionEnabled sample code for java.awt.im.InputContext.isCompositionEnabled() definition code for java.awt.im.InputContext.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 sample code for java.lang.UnsupportedOperationException definition code for java.lang.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) sample code for java.awt.im.InputContext.setCompositionEnabled(boolean) definition code for java.awt.im.InputContext.setCompositionEnabled(boolean)

reconvert sample code for java.awt.im.InputContext.reconvert() definition code for java.awt.im.InputContext.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 sample code for java.awt.im.InputMethodRequests.getSelectedText(java.text.AttributedCharacterIterator.Attribute[]) definition code for java.awt.im.InputMethodRequests.getSelectedText(java.text.AttributedCharacterIterator.Attribute[]) 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 sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - if there is no current input method available or the current input method does not support the reconversion operation.
Since:
1.3

dispatchEvent sample code for java.awt.im.InputContext.dispatchEvent(java.awt.AWTEvent) definition code for java.awt.im.InputContext.dispatchEvent(java.awt.AWTEvent)

public void dispatchEvent(AWTEvent sample code for java.awt.AWTEvent definition code for java.awt.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 sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if event is null

removeNotify sample code for java.awt.im.InputContext.removeNotify(java.awt.Component) definition code for java.awt.im.InputContext.removeNotify(java.awt.Component)

public void removeNotify(Component sample code for java.awt.Component definition code for java.awt.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 sample code for java.awt.Component.removeNotify() definition code for java.awt.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 sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if client is null

endComposition sample code for java.awt.im.InputContext.endComposition() definition code for java.awt.im.InputContext.endComposition()

public void endComposition()
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.

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.


dispose sample code for java.awt.im.InputContext.dispose() definition code for java.awt.im.InputContext.dispose()

public void dispose()
Disposes of the input context and release the resources used by it. Called by AWT for the default input context of each Window. If no input methods are available, then this method has no effect.


getInputMethodControlObject sample code for java.awt.im.InputContext.getInputMethodControlObject() definition code for java.awt.im.InputContext.getInputMethodControlObject()

public Object sample code for java.lang.Object definition code for java.lang.Object  getInputMethodControlObject()
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.

If no input methods are available or the current input method does not provide an input method control object, then null is returned.

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