java.awt.im.spi
Interface InputMethod


public interface InputMethod

Defines the interface for an input method that supports complex text input. Input methods traditionally support text input for languages that have more characters than can be represented on a standard-size keyboard, such as Chinese, Japanese, and Korean. However, they may also be used to support phonetic text input for English or character reordering for Thai.

Subclasses of InputMethod can be loaded by the input method framework; they can then be selected either through the API (InputContext.selectInputMethod sample code for java.awt.im.InputContext.selectInputMethod(java.util.Locale) definition code for java.awt.im.InputContext.selectInputMethod(java.util.Locale) ) or the user interface (the input method selection menu).

Since:
1.3

Method Summary
 void activate sample code for java.awt.im.spi.InputMethod.activate() definition code for java.awt.im.spi.InputMethod.activate() ()
          Activates the input method for immediate input processing.
 void deactivate sample code for java.awt.im.spi.InputMethod.deactivate(boolean) definition code for java.awt.im.spi.InputMethod.deactivate(boolean) (boolean isTemporary)
          Deactivates the input method.
 void dispatchEvent sample code for java.awt.im.spi.InputMethod.dispatchEvent(java.awt.AWTEvent) definition code for java.awt.im.spi.InputMethod.dispatchEvent(java.awt.AWTEvent) (AWTEvent sample code for java.awt.AWTEvent definition code for java.awt.AWTEvent  event)
          Dispatches the event to the input method.
 void dispose sample code for java.awt.im.spi.InputMethod.dispose() definition code for java.awt.im.spi.InputMethod.dispose() ()
          Disposes of the input method and releases the resources used by it.
 void endComposition sample code for java.awt.im.spi.InputMethod.endComposition() definition code for java.awt.im.spi.InputMethod.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 getControlObject sample code for java.awt.im.spi.InputMethod.getControlObject() definition code for java.awt.im.spi.InputMethod.getControlObject() ()
          Returns a control object from this input method, or null.
 Locale sample code for java.util.Locale definition code for java.util.Locale getLocale sample code for java.awt.im.spi.InputMethod.getLocale() definition code for java.awt.im.spi.InputMethod.getLocale() ()
          Returns the current input locale.
 void hideWindows sample code for java.awt.im.spi.InputMethod.hideWindows() definition code for java.awt.im.spi.InputMethod.hideWindows() ()
          Closes or hides all windows opened by this input method instance or its class.
 boolean isCompositionEnabled sample code for java.awt.im.spi.InputMethod.isCompositionEnabled() definition code for java.awt.im.spi.InputMethod.isCompositionEnabled() ()
          Determines whether this input method is enabled.
 void notifyClientWindowChange sample code for java.awt.im.spi.InputMethod.notifyClientWindowChange(java.awt.Rectangle) definition code for java.awt.im.spi.InputMethod.notifyClientWindowChange(java.awt.Rectangle) (Rectangle sample code for java.awt.Rectangle definition code for java.awt.Rectangle  bounds)
          Notifies this input method of changes in the client window location or state.
 void reconvert sample code for java.awt.im.spi.InputMethod.reconvert() definition code for java.awt.im.spi.InputMethod.reconvert() ()
          Starts the reconversion operation.
 void removeNotify sample code for java.awt.im.spi.InputMethod.removeNotify() definition code for java.awt.im.spi.InputMethod.removeNotify() ()
          Notifies the input method that a client component has been removed from its containment hierarchy, or that input method support has been disabled for the component.
 void setCharacterSubsets sample code for java.awt.im.spi.InputMethod.setCharacterSubsets(java.lang.Character.Subset[]) definition code for java.awt.im.spi.InputMethod.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 this input method is allowed to input.
 void setCompositionEnabled sample code for java.awt.im.spi.InputMethod.setCompositionEnabled(boolean) definition code for java.awt.im.spi.InputMethod.setCompositionEnabled(boolean) (boolean enable)
          Enables or disables this input method for composition, depending on the value of the parameter enable.
 void setInputMethodContext sample code for java.awt.im.spi.InputMethod.setInputMethodContext(java.awt.im.spi.InputMethodContext) definition code for java.awt.im.spi.InputMethod.setInputMethodContext(java.awt.im.spi.InputMethodContext) (InputMethodContext sample code for java.awt.im.spi.InputMethodContext definition code for java.awt.im.spi.InputMethodContext  context)
          Sets the input method context, which is used to dispatch input method events to the client component and to request information from the client component.
 boolean setLocale sample code for java.awt.im.spi.InputMethod.setLocale(java.util.Locale) definition code for java.awt.im.spi.InputMethod.setLocale(java.util.Locale) (Locale sample code for java.util.Locale definition code for java.util.Locale  locale)
          Attempts to set the input locale.
 

Method Detail

setInputMethodContext sample code for java.awt.im.spi.InputMethod.setInputMethodContext(java.awt.im.spi.InputMethodContext) definition code for java.awt.im.spi.InputMethod.setInputMethodContext(java.awt.im.spi.InputMethodContext)

void setInputMethodContext(InputMethodContext sample code for java.awt.im.spi.InputMethodContext definition code for java.awt.im.spi.InputMethodContext  context)
Sets the input method context, which is used to dispatch input method events to the client component and to request information from the client component.

This method is called once immediately after instantiating this input method.

Parameters:
context - the input method context for this input method
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if context is null

setLocale sample code for java.awt.im.spi.InputMethod.setLocale(java.util.Locale) definition code for java.awt.im.spi.InputMethod.setLocale(java.util.Locale)

boolean setLocale(Locale sample code for java.util.Locale definition code for java.util.Locale  locale)
Attempts to set the input locale. If the input method supports the desired locale, it changes its behavior to support input for the locale and returns true. Otherwise, it returns false and does not change its behavior.

This method is called

Parameters:
locale - locale to input
Returns:
whether the specified locale is supported
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.spi.InputMethod.getLocale() definition code for java.awt.im.spi.InputMethod.getLocale()

Locale sample code for java.util.Locale definition code for java.util.Locale  getLocale()
Returns the current input locale. Might return null in exceptional cases.

This method is called

Returns:
the current input locale, or null

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

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 this input method is allowed to input. Null may be passed in to indicate that all characters are allowed.

This method is called

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

setCompositionEnabled sample code for java.awt.im.spi.InputMethod.setCompositionEnabled(boolean) definition code for java.awt.im.spi.InputMethod.setCompositionEnabled(boolean)

void setCompositionEnabled(boolean enable)
Enables or disables this 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.

This method is called

Parameters:
enable - whether to enable the input method for composition
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - if this input method does not support the enabling/disabling operation
See Also:
isCompositionEnabled() sample code for java.awt.im.spi.InputMethod.isCompositionEnabled() definition code for java.awt.im.spi.InputMethod.isCompositionEnabled()

isCompositionEnabled sample code for java.awt.im.spi.InputMethod.isCompositionEnabled() definition code for java.awt.im.spi.InputMethod.isCompositionEnabled()

boolean isCompositionEnabled()
Determines whether this input method is enabled. 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.

This method is called

Returns:
true if this input method is enabled for composition; false otherwise.
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - if this input method does not support checking whether it is enabled for composition
See Also:
setCompositionEnabled(boolean) sample code for java.awt.im.spi.InputMethod.setCompositionEnabled(boolean) definition code for java.awt.im.spi.InputMethod.setCompositionEnabled(boolean)

reconvert sample code for java.awt.im.spi.InputMethod.reconvert() definition code for java.awt.im.spi.InputMethod.reconvert()

void reconvert()
Starts the reconversion operation. The input method obtains the text to be reconverted from the current 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. It can use other InputMethodRequests methods to request additional information required for the reconversion operation. The composed and committed text produced by the operation is sent to the client component as a sequence of InputMethodEvents. If the given text cannot be reconverted, the same text should be sent to the client component as committed text.

This method is called by InputContext.reconvert sample code for java.awt.im.InputContext.reconvert() definition code for java.awt.im.InputContext.reconvert() .

Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - if the input method does not support the reconversion operation.

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

void dispatchEvent(AWTEvent sample code for java.awt.AWTEvent definition code for java.awt.AWTEvent  event)
Dispatches the event to the input method. If input method support is enabled for the focussed component, incoming events of certain types are dispatched to the current input method for this component before they are dispatched to the component's methods or event listeners. The input method decides whether it needs to handle the event. If it does, it also calls the event's consume method; this causes the event to not get dispatched to the component's event processing methods or event listeners.

Events are dispatched if they are instances of InputEvent or its subclasses. This includes instances of the AWT classes KeyEvent and MouseEvent.

This method is called by InputContext.dispatchEvent sample code for java.awt.im.InputContext.dispatchEvent(java.awt.AWTEvent) definition code for java.awt.im.InputContext.dispatchEvent(java.awt.AWTEvent) .

Parameters:
event - the event being dispatched to the input method
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if event is null

notifyClientWindowChange sample code for java.awt.im.spi.InputMethod.notifyClientWindowChange(java.awt.Rectangle) definition code for java.awt.im.spi.InputMethod.notifyClientWindowChange(java.awt.Rectangle)

void notifyClientWindowChange(Rectangle sample code for java.awt.Rectangle definition code for java.awt.Rectangle  bounds)
Notifies this input method of changes in the client window location or state. This method is called while this input method is the current input method of its input context and notifications for it are enabled (see InputMethodContext.enableClientWindowNotification sample code for java.awt.im.spi.InputMethodContext.enableClientWindowNotification(java.awt.im.spi.InputMethod, boolean) definition code for java.awt.im.spi.InputMethodContext.enableClientWindowNotification(java.awt.im.spi.InputMethod, boolean) ). Calls to this method are temporarily suspended if the input context's removeNotify sample code for java.awt.im.InputContext.removeNotify(java.awt.Component) definition code for java.awt.im.InputContext.removeNotify(java.awt.Component) method is called, and resume when the input method is activated for a new client component. It is called in the following situations:

Parameters:
bounds - client window's bounds sample code for java.awt.Component.getBounds() definition code for java.awt.Component.getBounds() on the screen; or null if the client window is iconified or invisible

activate sample code for java.awt.im.spi.InputMethod.activate() definition code for java.awt.im.spi.InputMethod.activate()

void activate()
Activates the input method for immediate input processing.

If an input method provides its own windows, it should make sure at this point that all necessary windows are open and visible.

This method is called

The method is only called when the input method is inactive. A newly instantiated input method is assumed to be inactive.


deactivate sample code for java.awt.im.spi.InputMethod.deactivate(boolean) definition code for java.awt.im.spi.InputMethod.deactivate(boolean)

void deactivate(boolean isTemporary)
Deactivates the input method. The isTemporary argument has the same meaning as in FocusEvent.isTemporary sample code for java.awt.event.FocusEvent.isTemporary() definition code for java.awt.event.FocusEvent.isTemporary() .

If an input method provides its own windows, only windows that relate to the current composition (such as a lookup choice window) should be closed at this point. It is possible that the input method will be immediately activated again for a different client component, and closing and reopening more persistent windows (such as a control panel) would create unnecessary screen flicker. Before an instance of a different input method class is activated, hideWindows() sample code for java.awt.im.spi.InputMethod.hideWindows() definition code for java.awt.im.spi.InputMethod.hideWindows() is called on the current input method.

This method is called

The method is only called when the input method is active.

Parameters:
isTemporary - whether the focus change is temporary

hideWindows sample code for java.awt.im.spi.InputMethod.hideWindows() definition code for java.awt.im.spi.InputMethod.hideWindows()

void hideWindows()
Closes or hides all windows opened by this input method instance or its class.

This method is called

The method is only called when the input method is inactive.


removeNotify sample code for java.awt.im.spi.InputMethod.removeNotify() definition code for java.awt.im.spi.InputMethod.removeNotify()

void removeNotify()
Notifies the input method 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 called by InputContext.removeNotify sample code for java.awt.im.InputContext.removeNotify(java.awt.Component) definition code for java.awt.im.InputContext.removeNotify(java.awt.Component) .

The method is only called when the input method is inactive.


endComposition sample code for java.awt.im.spi.InputMethod.endComposition() definition code for java.awt.im.spi.InputMethod.endComposition()

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.

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.

This method is called


dispose sample code for java.awt.im.spi.InputMethod.dispose() definition code for java.awt.im.spi.InputMethod.dispose()

void dispose()
Disposes of the input method and releases the resources used by it. In particular, the input method should dispose windows and close files that are no longer needed.

This method is called by InputContext.dispose sample code for java.awt.im.InputContext.dispose() definition code for java.awt.im.InputContext.dispose() .

The method is only called when the input method is inactive. No method of this interface is called on this instance after dispose.


getControlObject sample code for java.awt.im.spi.InputMethod.getControlObject() definition code for java.awt.im.spi.InputMethod.getControlObject()

Object sample code for java.lang.Object definition code for java.lang.Object  getControlObject()
Returns a control object from this 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.

This method is called by InputContext.getInputMethodControlObject sample code for java.awt.im.InputContext.getInputMethodControlObject() definition code for java.awt.im.InputContext.getInputMethodControlObject() .

Returns:
a control object from this input method, or null