IAgentCharacter::Activate

[Microsoft Agent est déconseillé à partir de Windows 7 et peut ne pas être disponible dans les versions ultérieures de Windows.]

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

Définit si un client est actif ou si un caractère est le plus haut.

• Retourne S_OK pour indiquer que l’opération a réussi.
• Retourne S_FALSE pour indiquer que l’opération n’a pas réussi.

sState

Vous pouvez spécifier les valeurs suivantes pour ce paramètre :

Valeur	Description
0	Définissez comme n’étant pas le client actif.
1	Défini comme client actif.
2	Créez le caractère le plus haut.

 

Lorsque plusieurs caractères sont visibles, un seul des caractères reçoit une entrée vocale à la fois. De même, lorsque plusieurs applications clientes partagent le même caractère, un seul des clients reçoit une entrée de souris (par exemple, des événements de clic ou de glissement de contrôle Microsoft Agent) à la fois. Le jeu de caractères pour recevoir l’entrée vocale et la souris est le caractère le plus élevé et le client qui reçoit l’entrée est le client actif du caractère. (La fenêtre du caractère le plus haut apparaît également en haut de l’ordre de plan de la fenêtre de caractères.) En règle générale, l’utilisateur détermine le caractère le plus élevé en le sélectionnant explicitement. Toutefois, l’activation la plus haute change également lorsqu’un caractère est affiché ou masqué (le caractère devient ou n’est plus le plus haut, respectivement.)

Vous pouvez également utiliser cette méthode pour gérer explicitement quand votre client reçoit une entrée dirigée vers le caractère, par exemple quand votre application devient active. Par exemple, si vous définissez État sur 2, le caractère est le plus haut, et votre client reçoit tous les événements d’entrée vocale et de souris générés à partir de l’interaction de l’utilisateur avec le caractère. Par conséquent, cela fait également de votre client le client d’entrée actif du caractère. Toutefois, vous pouvez également définir le client actif pour un caractère sans faire en sorte que le caractère soit le plus haut, en définissant État sur 1. Cela permet à votre client de recevoir une entrée dirigée vers ce caractère lorsque le caractère devient le plus haut. De même, vous pouvez définir votre client pour qu’il ne soit pas le client actif (pour ne pas recevoir d’entrée) lorsque le caractère devient le plus haut, en définissant État sur 0. Vous pouvez déterminer si un caractère a d’autres clients actuels à l’aide de IAgentCharacter::HasOtherClients.

Évitez d’appeler cette méthode directement après une méthode Show . Afficher définit automatiquement le client d’entrée actif. Lorsque le caractère est masqué, l’appel Activate peut échouer, s’il est traité avant la fin de la méthode Show .

Toute tentative d’appel de cette méthode avec le paramètre State défini sur 2 (lorsque le caractère spécifié est masqué) échoue. De même, si vous définissez État sur 0 et que votre application est le seul client, cet appel échoue. Un caractère doit toujours avoir un client le plus haut.

Notes

L’appel de cette méthode avec l’état défini sur 1 ne génère généralement pas d’événement AgentNotifySink::ActivateInputState , sauf s’il n’y a pas d’autres caractères chargés ou si votre application est déjà active en entrée.

 

Voir aussi

IAgentCharacter::HasOtherClients