IAgentCharacter::Activate

[从 Windows 7 开始,Microsoft代理已弃用,在后续版本的 Windows 中可能不可用。

HRESULT Activate(
   short sState, // topmost character or client setting
);

设置客户端是活动还是字符最顶层。

  • 返回S_OK以指示作成功。
  • 返回S_FALSE,指示作未成功。

sState

可以为此参数指定以下值:

价值 描述
0 设置为非活动客户端。
1 设置为活动客户端。
2 使最顶层的字符。

 

当多个字符可见时,一次只有一个字符接收语音输入。 同样,当多个客户端应用程序共享相同的字符时,每次只有一个客户端接收鼠标输入(例如,Microsoft代理控制单击或拖动事件)。 用于接收鼠标和语音输入的字符集是最顶层的字符,接收输入的客户端是字符的活动客户端。 (最顶部字符的窗口也显示在字符窗口的 z 顺序的顶部。通常,用户通过显式选择它来确定最顶层的字符。 但是,当显示或隐藏字符时,最顶层的激活也会更改(字符变为或不再最顶层。

还可以使用此方法显式管理客户端何时收到定向到字符的输入,例如应用程序本身处于活动状态时。 例如,将 状态 设置为 2 会使字符最顶层,并且客户端接收用户与字符交互生成的所有鼠标和语音输入事件。 因此,它还使客户端成为字符的输入活动客户端。 但是,还可以通过将 状态 设置为 1,为字符设置活动客户端,而不使字符最顶层。 这使客户端能够在字符最顶层时接收定向到该字符的输入。 同样,通过将 状态 设置为 0,可以将客户端设置为不活动客户端(无法接收输入)。 可以使用 IAgentCharacter::HasOtherClients确定字符是否具有其他当前客户端。

避免在 Show 方法之后直接调用此方法。 显示 会自动设置输入活动客户端。 当字符隐藏时,如果 Show 方法完成之前处理 激活 调用可能会失败。

尝试调用此方法时,State 参数设置为 2(隐藏指定字符时)将失败。 同样,如果将 状态 设置为 0,并且应用程序是唯一的客户端,则此调用将失败。 字符必须始终具有最顶层的客户端。

注意

调用 状态 设置为 1 的方法通常不会生成 AgentNotifySink::ActivateInputState 事件,除非加载了其他字符或应用程序已处于输入活动状态。

 

另请参阅

IAgentCharacter::HasOtherClients