java.awt.im.spi
接口 InputMethod

public interface InputMethod

定义支持复杂文本输入的输入方法接口。输入方法通常支持多语言文本输入，这些语言（如汉语、日语和韩语）都有无法在标准键盘上直接表示的字符。不过，它们也可以用来支持英语语音文本输入或泰语字符的重新排序。

InputMethod 的子类可以由输入方法框架加载；然后可以通过 API (InputContext.selectInputMethod) 或通过用户界面（输入方法选择菜单）对其进行选择。

从以下版本开始：

1.3

方法摘要

void	activate() 激活输入方法，以便立即进行输入处理。
void	deactivate(boolean isTemporary) 让输入方法处于非活动状态。
void	dispatchEvent(AWTEvent event) 将事件指派到输入方法。
void	dispose() 释放由此输入方法使用的资源。
void	endComposition() 结束当前可能在此上下文中正进行的任何输入撰写。
Object	getControlObject() 从此输入方法返回一个控制对象，或 null。
Locale	getLocale() 返回当前的输入语言环境。
void	hideWindows() 关闭或隐藏由此输入方法实例或其类打开的所有窗口。
boolean	isCompositionEnabled() 确定此输入方法是否已启用。
void	notifyClientWindowChange(Rectangle bounds) 通知此输入方法客户端窗口位置或状态的更改。
void	reconvert() 启动恢复操作。
void	removeNotify() 通知输入方法已从客户端组件所在容器层次结构中移除该客户端组件，或通知它该组件已禁用输入方法支持。
void	setCharacterSubsets(Character.Subset[] subsets) 设置允许此输入方法进行输入的 Unicode 字符集的子集。
void	setCompositionEnabled(boolean enable) 启用或禁用输入方法的撰写功能，具体取决于参数 enable 的值。
void	setInputMethodContext(InputMethodContext context) 设置输入方法的上下文，这样可以将输入方法事件指派到客户端组件并能从客户端组件请求信息。
boolean	setLocale(Locale locale) 试图设置输入语言环境。

方法详细信息

setInputMethodContext

void setInputMethodContext(InputMethodContext context)

设置输入方法的上下文，这样可以将输入方法事件指派到客户端组件并能从客户端组件请求信息。

实例化此输入方法之后马上就会调用一次此方法。

参数：

context - 此输入方法的输入方法上下文

抛出：

NullPointerException - 如果 context 为 null

setLocale

boolean setLocale(Locale locale)

试图设置输入语言环境。如果输入方法支持所需的语言环境，则此输入方法将更改自己的行为以支持该语言环境的输入并返回 true。否则，它将返回 false，且不会更改自己的行为。

以下情况可调用此方法

• 由 InputContext.selectInputMethod 调用。
• 如果用户指定了语言环境，或者以前已选定输入方法的 getLocale 方法返回一个非 null 值，则当通过用户界面切换为该输入方法时调用。

参数：

locale - 要输入的语言环境

返回：

是否支持指定的语言环境

抛出：

NullPointerException - 如果 locale 为 null

getLocale

Locale getLocale()

返回当前的输入语言环境。异常情况下可能返回 null。

以下情况可调用此方法

• 由 InputContext.getLocale 调用，和
• 通过用户界面从此输入方法切换为另一种输入方法时调用。

返回：

当前的输入语言环境，或 null

setCharacterSubsets

void setCharacterSubsets(Character.Subset[] subsets)

设置允许此输入方法进行输入的 Unicode 字符集的子集。可能会传入 Null，以指示允许输入所有字符。

以下情况可调用此方法

• 实例化此输入方法后立即调用，
• 当从另一种输入方法切换到此输入方法时，以及
• 由 InputContext.setCharacterSubsets 调用。

参数：

subsets - 可以从其输入字符的 Unicode 字符集的子集

setCompositionEnabled

void setCompositionEnabled(boolean enable)

启用或禁用输入方法的撰写功能，具体取决于参数 enable 的值。

启用输入方法的撰写功能将出于撰写和控制目的解释传入事件，而禁用的输入方法不能解释出于撰写目的的事件。但要注意：无论输入方法是启用还是禁用，事件都会传到该输入方法；禁用输入方法的撰写功能可能仍会出于控制目的解释包括为撰写而启用或禁用自身在内的事件。

对于由主机操作系统提供的输入方法，并不总能确定是否支持此操作。例如，某个输入方法可能只对某些语言环境启用了撰写功能，而对另一些语言环境不执行任何操作。对于此类输入方法，此方法有可能既不抛出 UnsupportedOperationException，也不影响是否已启用撰写功能。

以下情况可调用此方法

• 由 InputContext.setCompositionEnabled 调用。
• 如果以前已选定输入方法的 isCompositionEnabled 方法在没有抛出异常的情况下返回，则当使用用户界面或 InputContext.selectInputMethod 从另一种输入方法切换到此输入方法时调用。

参数：

enable - 是否启用输入方法的撰写功能

抛出：

UnsupportedOperationException - 如果此输入方法不支持启用/禁用操作

另请参见：

isCompositionEnabled()

isCompositionEnabled

boolean isCompositionEnabled()

确定此输入方法是否已启用。启用撰写功能的输入方法将出于撰写和控制目的解释传入事件，而禁用的输入方法不会出于撰写目的解释事件。

以下情况可调用此方法

• 由 InputContext.isCompositionEnabled 调用，并且
• 当使用用户界面或 InputContext.selectInputMethod 从此输入方法切换到另一种输入方法时调用。

返回：

如果为进行撰写启用了此输入方法，则返回 true；否则返回 false。

抛出：

UnsupportedOperationException - 如果此输入方法不支持是否已启用撰写功能检查

另请参见：

setCompositionEnabled(boolean)

reconvert

void reconvert()

启动恢复操作。输入方法使用 InputMethodRequests.getSelectedText 方法从当前客户端组件中获得要恢复的文本。它也可以使用其他 InputMethodRequests 方法请求恢复操作所需的其他信息。此操作生成的已混合且已提交文本将作为 InputMethodEvent 序列发送到客户端组件。如果给定的文本不能恢复，则会把相同的文本作为已提交文本发送到客户端组件。

可由 InputContext.reconvert 调用此方法。

抛出：

UnsupportedOperationException - 如果输入方法不支持恢复操作。

dispatchEvent

void dispatchEvent(AWTEvent event)

将事件指派到输入方法。如果拥有焦点的组件已启用输入方法支持，某些类型的传入事件将被指派到此组件的当前输入方法，然后才指派到该组件的方法或事件侦听器。该输入方法决定是否需要处理此事件。如果需要处理，它还要调用该事件的 consume 方法；这样做会导致该事件不能被指派到组件的事件处理方法或事件侦听器。

如果事件为 InputEvent 或其子类的实例，则会指派它们。这包括 AWT 类 KeyEvent 和 MouseEvent 的实例。

可由 InputContext.dispatchEvent 调用此方法。

参数：

event - 正指派到输入方法的事件

抛出：

NullPointerException - 如果 event 为 null

notifyClientWindowChange

void notifyClientWindowChange(Rectangle bounds)

通知此输入方法客户端窗口位置或状态的更改。当该输入方法是其输入上下文的当前输入方法且已启用其通知时调用此方法（请参见 InputMethodContext.enableClientWindowNotification）。如果调用了输入上下文的 removeNotify 方法，则会临时挂起对此方法的调用；当新的客户端组件激活此输入方法时，将恢复此方法的调用。将在以下情形调用此方法：

• 包含当前客户端组件的窗口，其位置、大小、可见性、iconification 状态更改时，或关闭窗口时。
• 如果当前客户端组件存在，则从 enableClientWindowNotification(inputMethod, true) 调用。
• 如果调用期间没有可用的当前客户端组件，则在该输入方法调用 enableClientWindowNotification(inputMethod, true) 后首次激活它时调用。
• 在调用输入上下文的 removeNotify 方法之后，激活新客户端组件的输入方法时调用。

参数：

bounds - 屏幕上客户端窗口的 bounds；如果客户端窗口已图标化或不可见，则为 null

activate

void activate()

激活输入方法，以便立即进行输入处理。

如果某种输入方法提供了自己的窗口，则此时它应确保所有必要的窗口都已打开并可见。

以下情况可调用此方法

• 当客户端组件收到 FOCUS_GAINED 事件时由 InputContext.dispatchEvent 调用。
• 使用用户界面或 InputContext.selectInputMethod 从另一种输入方法切换到此输入方法时调用。

只有当输入方法处于非活动状态时才能调用该方法。假定新实例化的输入方法处于非活动状态。

deactivate

void deactivate(boolean isTemporary)

让输入方法处于非活动状态。isTemporary 参数与 FocusEvent.isTemporary 中的参数含义相同。

如果输入方法提供了自己的窗口，则此时只应关闭与当前撰写功能相关的窗口（如查找选择窗口）。该输入方法有可能被另一个客户端组件再次激活，并且关闭或重新打开较稳定的窗口（如控制面板）可能会造成不必要的屏幕闪烁。在激活另一种输入方法类的实例之前，当前输入方法将调用 hideWindows()。

以下情况可调用此方法

• 当客户端组件收到 FOCUS_LOST 事件时，由 InputContext.dispatchEvent 调用。
• 使用用户界面或 InputContext.selectInputMethod 从此输入方法切换到另一种输入方法时调用。
• 如果当前客户端组件被移除，则在 removeNotify 之前调用。

只有当输入方法处于活动状态时才能调用该方法。

参数：

isTemporary - 焦点更改是否为临时的

hideWindows

void hideWindows()

关闭或隐藏由此输入方法实例或其类打开的所有窗口。

以下情况可调用此方法

• 对另一种输入方法类实例调用 activate 之前调用。
• 对此输入方法调用 dispose 之前调用。

只有当输入方法处于非活动状态时才能调用该方法。

removeNotify

void removeNotify()

通知输入方法已从客户端组件所在容器层次结构中移除该客户端组件，或通知它该组件已禁用输入方法支持。

可由 InputContext.removeNotify 调用此方法。

只有当输入方法处于非活动状态时才能调用该方法。

endComposition

void endComposition()

结束当前可能在此上下文中正进行的任何输入撰写。这样做可能会提交或删除未提交的文本，具体取决于平台和用户可能做出的首选项。使用一个输入方法事件可将对文本的任何更改传送到处于活动状态的组件。

编辑组件的文本可以在各种情况下调用此方法，例如，用户可在文本内（但在撰写文本外）移动插入点时，或者在将组件的文本保存到文件上或复制到粘贴板上时都可调用。

以下情况可调用此方法

• 由 InputContext.endComposition 调用。
• 在切换到另一个客户端组件时可由 InputContext.dispatchEvent 调用
• 当使用用户界面或 InputContext.selectInputMethod 从此输入方法切换到另一种输入方法时调用。

dispose

void dispose()

释放由此输入方法使用的资源。特别要提出的是，输入方法应释放窗口并关闭不再需要的文件。

可由 InputContext.dispose 调用此方法。

只有当输入方法处于非活动状态时才能调用该方法。释放之后，就无法针对此实例调用该接口的方法了。

getControlObject

Object getControlObject()

从此输入方法返回一个控制对象，或 null。控制对象提供了控制该输入方法的行为或从该输入方法获得信息的方法。对象的类型是输入方法的特定类。客户端必须将其结果与已知输入方法的控制对象类进行对比，并传递给适当的类以调用所提供的方法。

可由 InputContext.getInputMethodControlObject 调用此方法。

返回：

此输入方法的一个控制对象，或 null