IAgentCharacter：：Activate

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

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

设置客户端是处于活动状态还是字符处于最顶层。

• 返回指示操作成功的S_OK。
• 返回指示操作不成功的S_FALSE。

sState

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

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

 

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

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

避免直接在 Show 方法之后调用此方法。 显示 自动设置输入-主动客户端。 隐藏字符时，如果在 Show 方法完成之前处理了 Activate 调用，则它可能会失败。

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

注意

在 状态 设置为 1 的情况下调用此方法通常不会生成 AgentNotifySink：：ActivateInputState 事件，除非没有加载其他字符或应用程序已输入活动。

 

另请参阅

IAgentCharacter：：HasOtherClients