java.awt.im

接口
java.lang.Object
  继承者 java.awt.im.InputContext

public class InputContext
     
extends Object

提供控制诸如输入方法和键盘布局之类的文本输入设施的方法。两种方法可以处理输入方法和键盘布局:selectInputMethod 让客户端组件根据语言环境选择输入方法或键盘布局;getLocale 让客户端组件获得当前输入方法或键盘布局的语言环境。其他方法更明确地支持与输入方法之间的交互:它们让客户端组件控制输入方法的行为,并将客户端组件中的事件指派到该输入方法。

在默认情况下,每个 Window 实例创建一个 InputContext 实例,并且窗口的容器层次结构内部所有组件都共享此输入上下文。不过,这意味着在一个窗口中每一次只能进行一项文本输入操作,并且该文本需要在将焦点从一个文本组件中移到另一文本组件时提交。如果不需要此项操作,则文本组件可以创建自己的输入上下文实例。

Java 平台支持使用 java.awt.im.spi 包中的接口在 Java 编程语言中开发而且作为扩展安装在 Java SE 运行时环境中的输入方法。实现还可以支持使用其运行平台上的本机输入方法;不过,不是所有平台和语言环境都提供输入方法。键盘布局由主机平台提供。

如果 (a) 没有安装使用 Java 编程语言编写的输入方法和 (b) Java 平台实现或基础平台不支持本机输入方法,则输入方法不可用。在这种情况下,仍要创建和使用输入上下文;其行为可以根据下面的具体方法指定。

从以下版本开始:
1.2
另请参见:
Component.getInputContext(), Component.enableInputMethods(boolean)

构造方法摘要
protected InputContext()
          构造一个 InputContext。
 
方法摘要
 void dispatchEvent(AWTEvent event)
          将事件指派到处于活动状态的输入方法。
 void dispose()
          释放由此输入上下文使用过的资源。
 void endComposition()
          结束当前可能在此上下文进行的任何输入撰写。
 Object getInputMethodControlObject()
          返回当前输入方法中的一个控制对象,或 null。
static InputContext getInstance()
          返回新 InputContext 实例。
 Locale getLocale()
          返回当前输入方法或键盘布局的当前语言环境。
 boolean isCompositionEnabled()
          确定是否已启用当前输入方法以进行撰写。
 void reconvert()
          让当前输入方法从当前客户端组件中恢复文本。
 void removeNotify(Component client)
          通知输入上下文,客户端组件已从它的包含层次结构中移除,或该组件已禁用输入方法支持。
 boolean selectInputMethod(Locale locale)
          试图选择一个支持给定语言环境的输入方法或键盘布局,并返回指示是否成功选定此类输入方法或键盘布局的值。
 void setCharacterSubsets(Character.Subset[] subsets)
          设置此输入上下文的输入方法应允许输入的 Unicode 字符集的子集。
 void setCompositionEnabled(boolean enable)
          根据参数 enable 的值启用或禁用当前输入方法进行撰写。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

构造方法详细信息

InputContext

protected InputContext()
构造一个 InputContext。此方法受到保护,所以客户端不能直接实例化 InputContext。输入上下文通过调用 getInstance() 获得。

方法详细信息

getInstance

public static InputContext getInstance()
返回新 InputContext 实例。


selectInputMethod

public boolean selectInputMethod(Locale locale)
试图选择一个支持给定语言环境的输入方法或键盘布局,并返回指示是否成功选定此类输入方法或键盘布局的值。按以下步骤操作,直到选定了输入方法:

  • 如果当前已选定的输入方法或键盘布局支持所请求的语言环境,则保留已有选定。
  • 如果没有支持所请求的语言环境的可用输入方法或键盘布局,则仍保留选定当前输入方法或键盘布局。
  • 如果用户以前已从用户界面选择了所请求语言环境的输入方法或键盘布局,则重新选择最近选择的此类输入方法或键盘布局。
  • 否则,要依赖于实现选定支持所请求语言环境的输入方法或键盘布局。
切换输入方法之前,提交当前任何未提交的文本。如果没有支持所请求语言环境的输入方法或键盘布局,则返回 false。

不是所有主机操作系统都提供 API 来确定当前已选定的本机输入方法或键盘布局的语言环境,和选择语言环境的本机输入方法或键盘布局。对于未提供此类 API 的主机操作系统而言,selectInputMethod 假定该主机操作系统提供的本机输入方法或键盘布局只支持该系统默认的语言环境。

例如,当用户更改插入点时,文本编辑组件可能调用此方法,让用户立即使用周围文本的语言继续键入。

参数:
locale - 所需的新语言环境。
返回:
true 如果此调用后处于活动状态的输入方法或键盘布局支持所需语言环境。
抛出:
NullPointerException - 如果 locale 为 null

getLocale

public Locale getLocale()
返回当前输入方法或键盘布局的当前语言环境。如果输入上下文没有当前输入方法或键盘布局,或者当前输入方法的 InputMethod.getLocale() 方法返回 null,则返回 null。

不是所有主机操作系统都提供 API 来确定当前已选定的本机输入方法或键盘布局的语言环境。对于未提供此类 API 的主机操作系统而言,getLocale 假定该主机操作系统提供的所有本机输入方法或键盘布局的当前语言环境是该系统的默认语言环境。

返回:
当前输入方法或键盘布局的当前语言环境
从以下版本开始:
1.3

setCharacterSubsets

public void setCharacterSubsets(Character.Subset[] subsets)
设置此输入上下文的输入方法应允许输入的 Unicode 字符集的子集。可能会传入 Null,以指示允许输入所有字符。初始值为 null。该设置适用于当前输入方法,也适用于进行此调用后选定的输入方法。不过,应用程序不能依靠此具有所需影响的调用,因为不能将此设置传递到所有主机输入方法 - 应用程序仍需要应用自己的字符验证。如果没有可用的输入方法,则此方法不起作用。

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

setCompositionEnabled

public void setCompositionEnabled(boolean enable)
根据参数 enable 的值启用或禁用当前输入方法进行撰写。

撰写中已启用的输入方法将解释用于撰写和控制的传入事件,而禁用的输入方法不会解释用于撰写的事件。但要注意,不管是否已启用该输入方法,都要将事件传入其中;已禁用进行撰写的输入方法可能仍会因控制目的而解释事件,包括启用或禁用自身进行撰写。

因为输入方法是由主机操作系统提供的,所以可能无法一直确定是否支持此项操作。例如,一个输入方法可能只对某些语言环境启用撰写,而对另一些语言环境不执行任何操作。对于此类输入方法,此方法可能不会抛出 UnsupportedOperationException,并且也不会影响是否已启用撰写。

参数:
enable - 是否启用撰写的当前输入方法
抛出:
UnsupportedOperationException - 如果没有当前可用的输入方法或当前输入方法不支持启用/禁用操作
从以下版本开始:
1.3
另请参见:
isCompositionEnabled()

isCompositionEnabled

public boolean isCompositionEnabled()
确定是否已启用当前输入方法以进行撰写。撰写中已启用的输入方法将解释用于撰写和控制的传入事件,而禁用的输入方法不会解释用于撰写的事件。

返回:
如果当前输入方法已启用撰写,则返回 true;否则返回 false
抛出:
UnsupportedOperationException - 如果没有当前可用的输入方法或当前输入方法不支持检查是否已启用撰写
从以下版本开始:
1.3
另请参见:
setCompositionEnabled(boolean)

reconvert

public void reconvert()
让当前输入方法从当前客户端组件中恢复文本。该输入方法使用 InputMethodRequests.getSelectedText 方法获得要从客户端组件恢复的文本。必须准备其他 InputMethodRequests 方法来处理该输入方法需要的深层信息请求。将撰写文本和/或提交文本作为 InputMethodEvent 的序列发送到客户端组件。如果输入方法不能恢复给定的文本,则会将该文本作为 InputMethodEvent 中的提交文本返回。

抛出:
UnsupportedOperationException - 如果没有当前可用的输入方法,或当前输入方法不支持恢复操作。
从以下版本开始:
1.3

dispatchEvent

public void dispatchEvent(AWTEvent event)
将事件指派到处于活动状态的输入方法。由 AWT 调用。如果没有可用的输入方法,则永远无法使用该事件。

参数:
event - 事件
抛出:
NullPointerException - 如果 event 为 null

removeNotify

public void removeNotify(Component client)
通知输入上下文,客户端组件已从它的包含层次结构中移除,或该组件已禁用输入方法支持。此方法通常从客户端组件的 Component.removeNotify 方法中调用。丢弃此组件的输入方法中可能挂起的输入。如果没有可用的输入方法,则此方法不起作用。

参数:
client - 客户端组件
抛出:
NullPointerException - 如果 client 为 null

endComposition

public void endComposition()
结束当前可能在此上下文进行的任何输入撰写。这样做可能会提交或删除未提交的文本,具体取决于平台和用户可能做出的首选项。对该文本做出的任何更改都可以使用一个输入方法事件传送到处于活动状态的组件。如果没有可用的输入方法,则此方法不起作用。

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


dispose

public void dispose()
释放由此输入上下文使用过的资源。由 AWT 调用,用于每个 Window 的默认输入上下文。如果没有可用的输入方法,则此方法不起作用。


getInputMethodControlObject

public Object getInputMethodControlObject()
返回当前输入方法中的一个控制对象,或 null。控制对象提供了控制该输入方法的行为或从该输入方法获得信息的方法。对象的类型是输入方法的特定类。客户端必须将其结果与已知输入方法的控制对象类进行对比,并强制转换为适当的类,以调用所提供的方法。

如果没有可用的输入方法,或当前输入方法没有提供输入方法控制对象,则返回 null。

返回:
当前输入方法中的一个控制对象,或 null。