IAgentCharacter::Activate

[Microsoft エージェントは Windows 7 の時点で非推奨となり、以降のバージョンの Windows では使用できない場合があります。]

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

クライアントがアクティブか、または文字が一番上にあるかを設定します。

• 操作が成功したことを示すS_OKを返します。
• 操作が成功しなかったS_FALSEを返します。

sState

このパラメーターには、次の値を指定できます。

値	説明
0	アクティブなクライアントではなく として設定します。
1	アクティブなクライアントとして設定します。
2	一番上の文字を作成します。

 

複数の文字が表示されている場合、一度に 1 つの文字のみが音声入力を受け取ります。 同様に、複数のクライアント アプリケーションが同じ文字を共有する場合、一度にマウス入力を受け取るクライアントは 1 つだけです (たとえば、Microsoft Agent コントロールのクリックまたはドラッグ イベント)。 マウスと音声の入力を受け取る文字セットは最上位の文字であり、入力を受け取るクライアントは文字のアクティブなクライアントです。 (一番上の文字のウィンドウは、文字ウィンドウの z オーダーの上部にも表示されます)。通常、ユーザーは明示的に選択することで、最上位の文字を決定します。 ただし、一番上のアクティブ化は、文字が表示または非表示の場合にも変更されます (文字はそれぞれ最上位になるか、または一番上に表示されなくなります)。

また、このメソッドを使用して、アプリケーション自体がアクティブになったときなど、文字に対する入力をクライアントが受け取るタイミングを明示的に管理することもできます。 たとえば、 State を 2 に設定すると、文字が最上位になり、クライアントは、ユーザーが文字を操作して生成されたすべてのマウスと音声の入力イベントを受け取ります。 そのため、クライアントは文字の入力アクティブなクライアントにもなります。 ただし、 State を 1 に設定することで、文字を最上位にすることなく、文字のアクティブなクライアントを設定することもできます。 これにより、クライアントは、文字が最上位になったときに、その文字に送られた入力を受け取ることができます。 同様に、文字が最上位になったときに 、 State を 0 に設定することで、クライアントをアクティブなクライアント (入力を受信しないように) に設定できます。 文字に他の現在のクライアントがあるかどうかを判断するには 、IAgentCharacter::HasOtherClients を使用します。

Show メソッドの直後にこのメソッドを呼び出さないようにします。 [表示] を選択すると、入力アクティブなクライアントが自動的に設定されます。 文字が非表示の場合、Show メソッドが完了する前に処理されると、Activate 呼び出しが失敗する可能性があります。

State パラメーターを 2 に設定してこのメソッドを呼び出そうとすると (指定した文字が非表示の場合)、失敗します。 同様に、 State を 0 に設定し、アプリケーションが唯一のクライアントである場合、この呼び出しは失敗します。 文字には常に最上位のクライアントが必要です。

注意

State を 1 に設定してこのメソッドを呼び出しても、他の文字が読み込まれていないか、アプリケーションが既に入力アクティブでない限り、通常、AgentNotifySink::ActivateInputState イベントは生成されません。

 

参照

IAgentCharacter::HasOtherClients