IAgentCharacter::Ativar

[O Microsoft Agent foi preterido a partir do Windows 7 e pode não estar disponível em versões subsequentes do Windows.]

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

Define se um cliente está ativo ou se um caractere está no topo.

• Retorna S_OK para indicar que a operação foi bem-sucedida.
• Retorna S_FALSE para indicar que a operação não foi bem-sucedida.

sState

Você pode especificar os seguintes valores para esse parâmetro:

Valor	Descrição
0	Defina como não sendo o cliente ativo.
1	Defina como o cliente ativo.
2	Faça o personagem mais alto.

 

Quando vários caracteres são visíveis, apenas um dos caracteres recebe entrada de fala de cada vez. Da mesma forma, quando vários aplicativos cliente compartilham o mesmo caractere, apenas um dos clientes recebe entrada do mouse (por exemplo, eventos de clique ou arrastar do controle do Microsoft Agent) de cada vez. O conjunto de caracteres para receber a entrada do mouse e da fala é o caractere mais alto e o cliente que recebe a entrada é o cliente ativo do personagem. (A janela do caractere mais alto também aparece na parte superior da ordem z da janela do caractere.) Normalmente, o usuário determina qual caractere é o mais alto, selecionando-o explicitamente. No entanto, a ativação superior também muda quando um caractere é mostrado ou oculto (o personagem se torna ou não é mais superior, respectivamente).

Você também pode usar esse método para gerenciar explicitamente quando seu cliente recebe entrada direcionada ao caractere, como quando o próprio aplicativo se torna ativo. Por exemplo, definir State como 2 torna o caractere o mais alto, e seu cliente recebe todos os eventos de entrada de mouse e fala gerados a partir da interação do usuário com o caractere. Portanto, ele também torna seu cliente o cliente ativo de entrada do personagem. No entanto, você também pode definir o cliente ativo para um caractere sem torná-lo superior, definindo State como 1. Isso permite que seu cliente receba informações direcionadas para esse personagem quando o personagem se tornar o mais alto. Da mesma forma, você pode definir seu cliente para não ser o cliente ativo (para não receber entrada) quando o caractere se tornar superior, definindo State como 0. Você pode determinar se um caractere tem outros clientes atuais usando IAgentCharacter::HasOtherClients.

Evite chamar esse método diretamente após um Mostrar método. Mostrar define automaticamente o cliente ativo de entrada. Quando o caractere está oculto, a chamada Activate pode falhar, se for processada antes da conclusão do método Show .

A tentativa de chamar esse método com o parâmetro State definido como 2 (quando o caractere especificado estiver oculto) falhará. Da mesma forma, se você definir State como 0 e seu aplicativo for o único cliente, essa chamada falhará. Um personagem deve sempre ter um cliente de topo.

Ver também

IAgentCharacter::HasOtherClients