IAgentCharacter::Activate

[O Microsoft Agent foi preterido a partir do Windows 7 e pode estar indisponível nas versões subsequentes do Windows.]

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

Define se um cliente está ativo ou um caractere é superior.

• 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 este parâmetro:

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

 

Quando vários caracteres estão visíveis, apenas um dos caracteres recebe a entrada de fala por vez. Da mesma forma, quando vários aplicativos cliente compartilham o mesmo caractere, apenas um dos clientes recebe a entrada do mouse (por exemplo, o controle do Microsoft Agent clica ou arrasta eventos) por vez. O conjunto de caracteres para receber o mouse e a entrada de fala é o caractere mais alto e o cliente que recebe a entrada é o cliente ativo do caractere. (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 é superior selecionando-o explicitamente. No entanto, a ativação superior também é alterada quando um caractere é mostrado ou oculto (o caractere se torna ou não é mais superior, respectivamente).)

Você também pode usar esse método para gerenciar explicitamente quando o cliente recebe a entrada direcionada para o caractere, como quando o próprio aplicativo se torna ativo. Por exemplo, definir State como 2 torna o caractere mais alto e seu cliente recebe todos os eventos de entrada de mouse e fala gerados da interação do usuário com o caractere. Portanto, ele também torna seu cliente o cliente ativo de entrada do caractere. No entanto, você também pode definir o cliente ativo para um caractere sem tornar o caractere mais alto, definindo State como 1. Isso permite que o cliente receba a entrada direcionada para esse caractere quando o caractere se tornar 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 mais alto, 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 método Show. Mostrar define automaticamente o cliente ativo de entrada. Quando o caractere estiver oculto, o Ativar chamada poderá falhar, se ele for processado antes que o método Show seja concluído.

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 caractere deve sempre ter um cliente superior.

Nota

Chamar esse método com State definido como 1 normalmente não gera um evento AgentNotifySink::ActivateInputState, a menos que não haja nenhum outro caractere carregado ou seu aplicativo já esteja ativo na entrada.

 

Consulte Também

IAgentCharacter::HasOtherClients