IAgentCommands

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

Le serveur Microsoft Agent gère une liste de commandes actuellement disponibles pour l’utilisateur. Cette liste inclut les commandes que le serveur définit pour l’interaction générale, telles que Masquer et propriétés de l’agent Microsoft, la liste des clients disponibles (mais non actifs d’entrée) et les commandes définies par le client actif actuel. Les deux premiers ensembles de commandes sont des commandes globales ; autrement dit, ils sont disponibles à tout moment, quel que soit le client d’entrée actif. Les commandes définies par le client sont disponibles uniquement lorsque ce client est actif en entrée.

Récupérez une interface IAgentCommands en interrogeant l’interface IAgentCharacter pour IAgentCommands. Chaque application cliente Microsoft Agent peut définir une collection de commandes appelée collection Commands . Pour ajouter une commande à la collection, utilisez la méthode Add ou Insert . Bien que vous puissiez spécifier les propriétés d’une commande à l’aide des méthodes IAgentCommand , pour des performances de code optimales, spécifiez toutes les propriétés d’une commande dans les méthodes IAgentCommands::Add ou IAgentCommands::Insert lors de la définition initiale des propriétés d’une nouvelle commande. Vous pouvez utiliser les méthodes IAgentCommand pour interroger ou modifier les paramètres de propriété.

Pour chaque commande de la collection Commands , vous pouvez déterminer si la commande s’affiche dans le menu contextuel du caractère, dans la fenêtre Commandes vocales, dans les deux ou dans aucun des deux. Par exemple, si vous souhaitez qu’une commande apparaisse dans le menu contextuel du caractère, définissez les propriétés Légende et Visible de la commande. Pour afficher la commande dans la fenêtre Commandes vocales, définissez les propriétés Légende et Voix de la commande.

Un utilisateur peut accéder aux commandes individuelles de votre collection Commands uniquement lorsque votre application cliente est active en entrée et que le caractère est visible. Par conséquent, vous souhaiterez généralement définir les propriétés Caption, VoiceCaption et Voice pour l’objet de collection Commands ainsi que pour les commandes de la collection, car cela place une entrée pour votre collection Commands dans le menu contextuel d’un caractère et dans la fenêtre Commandes vocales. Lorsque l’utilisateur bascule vers votre client en choisissant son entrée Commandes , le serveur rend automatiquement votre entrée client active, en informant votre application cliente à l’aide de IAgentNotifySink::ActivateInputState et rend les commandes de sa collection disponibles. Le serveur avertit également le client qu’il n’est plus actif en entrée avec l’événement IAgentNotifySink::ActivateInputState . Cela permet au serveur de présenter et d’accepter uniquement les commandes qui s’appliquent au contexte du client actif d’entrée. Il permet également d’éviter les collisions de nom de commande entre les clients.

Un client peut également demander explicitement à se faire le client d’entrée actif à l’aide de la méthode IAgentCharacter::Activate . Cette méthode prend également en charge la définition de votre application pour qu’elle ne soit pas le client actif d’entrée. Vous pouvez utiliser cette méthode lors du partage d’un caractère avec une autre application, en définissant votre application comme étant input-active lorsque votre fenêtre d’application obtient le focus et non input-active quand elle perd le focus.

De même, vous pouvez utiliser IAgentCharacter::Activate pour définir votre application comme étant (ou non) le client actif du caractère. Le client actif est le client qui reçoit l’entrée lorsque son caractère est le caractère le plus élevé. Lorsque cette status change, le serveur avertit votre application avec l’événement IAgentNotifySinkEx::ActiveClientChange.

Lorsque le menu contextuel d’un caractère s’affiche, les modifications apportées aux propriétés d’une collection Commands ou aux commandes de sa collection n’apparaissent pas tant que l’utilisateur n’a pas réafficher le menu. Toutefois, lorsqu’elle est ouverte, la fenêtre Commandes vocales affiche les modifications à mesure qu’elles se produisent.

IAgentCommands définit une interface qui permet aux applications d’ajouter, supprimer, définir et interroger des propriétés pour une collection Commands . Ces fonctions sont également disponibles à partir de IAgentCommandsEx.

Une collection Commands peut apparaître sous la forme d’une commande dans le menu contextuel et dans la fenêtre Commandes vocales d’un caractère. Pour faire apparaître la collection Commands , vous devez définir sa propriété Caption . Le tableau suivant résume la façon dont les propriétés d’une collection Commands affectent sa présentation.

Propriété Caption	Voice-Caption, propriété	Voice, propriété	Visible, propriété	Apparaît dans le menu contextuel du caractère	Apparaît dans la fenêtre Commandes vocales
Oui	Oui	Oui	True	Oui, à l’aide de caption	Oui, à l’aide de VoiceCaption
Oui	Oui	Non¹	True	Oui, à l’aide de caption	Non
Oui	Oui	Oui	False	Non	Oui, à l’aide de VoiceCaption
Oui	Oui	Non¹	False	Non	Non
Non¹	Oui	Oui	True	Non	Oui, à l’aide de VoiceCaption
Non¹	Oui	Oui	False	Non	Oui, à l’aide de VoiceCaption
Non¹	Oui	Non¹	True	Non	Non
Non¹	Oui	Non¹	False	Non	Non
Oui	Non¹	Oui	True	Oui, à l’aide de caption	Oui, à l’aide de caption
Oui	Non¹	Non¹	True	Oui	Non
Oui	No¹	Oui	False	Non	Oui, à l’aide de la légende
Oui	No¹	No¹	False	Non	Non
No¹	No¹	Oui	True	Non	Non²
No¹	No¹	Oui	False	Non	Non²
No¹	No¹	No¹	True	Non	Non
No¹	No¹	No¹	False	Non	Non

 

¹Si le paramètre de propriété a la valeur Null. Dans certains langages de programmation, une chaîne vide peut ne pas être interprétée comme une chaîne null.

²La commande est toujours accessible par la voix.

Méthodes dans l'ordre Vtable

Méthodes IAgentCommands	Description
GetCommand	Récupère un objet Command de la collection Commands .
GetCount	Retourne la valeur du nombre de commandes dans une collection Commands .
SetCaption	Définit la valeur de la propriété Caption pour une collection Commands .
GetCaption	Retourne la valeur de la propriété Caption d’une collection Commands .
SetVoice	Définit la valeur de la propriété Voice pour une collection Commands .
GetVoice	Retourne la valeur de la propriété Voice d’une collection Commands .
SetVisible	Définit la valeur de la propriété Visible pour une collection Commands .
GetVisible	Retourne la valeur de la propriété Visible d’une collection Commands .
Ajouter	Ajoute un objet Command à une collection Commands .
Insérer	Insère un objet Command dans une collection Commands .
Supprimer	Supprime un objet Command dans une collection Commands .
RemoveAll	Supprime tous les objets Command d’une collection Commands .