IAgentCommands
[Microsoft Agent está en desuso a partir de Windows 7 y puede no estar disponible en versiones posteriores de Windows].
El servidor de Microsoft Agent mantiene una lista de comandos que están disponibles actualmente para el usuario. Esta lista incluye comandos que el servidor define para la interacción general, como Hide y Microsoft Agent Properties, la lista de clientes disponibles (pero no input-active) y los comandos definidos por el cliente activo actual. Los dos primeros conjuntos de comandos son comandos globales; es decir, están disponibles en cualquier momento, independientemente del cliente de entrada-activo. Los comandos definidos por el cliente solo están disponibles cuando ese cliente está activo de entrada.
Recupere una interfaz IAgentCommands consultando la interfaz IAgentCharacter para IAgentCommands. Cada aplicación cliente de Microsoft Agent puede definir una colección de comandos denominada colección Commands . Para agregar un comando a la colección, use el método Add o Insert . Aunque puede especificar las propiedades de un comando mediante métodos IAgentCommand , para obtener un rendimiento óptimo del código, especifique todas las propiedades de un comando en los métodos IAgentCommands::Add o IAgentCommands::Insert al establecer inicialmente las propiedades de un nuevo comando. Puede usar los métodos IAgentCommand para consultar o cambiar la configuración de la propiedad.
Para cada comando de la colección Commands , puede determinar si el comando aparece en el menú emergente del carácter, en la ventana Comandos de voz, en ambos o en ninguno. Por ejemplo, si desea que aparezca un comando en el menú emergente del carácter, establezca las propiedades Caption y Visible del comando. Para mostrar el comando en la ventana Comandos de voz, establezca las propiedades Caption y Voice del comando.
Un usuario puede acceder a los comandos individuales de la colección Commands solo cuando la aplicación cliente está activa de entrada y el carácter está visible. Por lo tanto, normalmente querrá establecer las propiedades Caption, VoiceCaption y Voice para el objeto de colección Commands , así como para los comandos de la colección, ya que esto coloca una entrada para la colección Commands en el menú emergente de un carácter y en la ventana Comandos de voz. Cuando el usuario cambia al cliente eligiendo su entrada Comandos , el servidor activa automáticamente la entrada del cliente, notificando a la aplicación cliente mediante IAgentNotifySink::ActivateInputState y hace que los comandos de su colección estén disponibles. El servidor también notifica al cliente que ya no está activo de entrada con el evento IAgentNotifySink::ActivateInputState . Esto permite que el servidor presente y acepte solo los comandos que se aplican al contexto actual del cliente de entrada-activo. También sirve para evitar colisiones de nombre de comando entre los clientes.
Un cliente también puede solicitar explícitamente que se convierta en el cliente de entrada-activo mediante el método IAgentCharacter::Activate . Este método también admite la configuración de la aplicación para que no sea el cliente de entrada-activo. Es posible que quiera usar este método al compartir un carácter con otra aplicación, estableciendo que la aplicación esté activa cuando la ventana de la aplicación obtiene el foco y no la entrada activa cuando pierde el foco.
Del mismo modo, puede usar IAgentCharacter::Activate para establecer que la aplicación sea (o no sea) el cliente activo del carácter. El cliente activo es el cliente que recibe la entrada cuando su carácter es el carácter superior. Cuando cambia este estado, el servidor notifica a la aplicación el evento IAgentNotifySinkEx::ActiveClientChange .
Cuando se muestra el menú emergente de un carácter, los cambios realizados en las propiedades de una colección Commands o los comandos de su colección no aparecen hasta que el usuario vuelva a reproducir el menú. Sin embargo, cuando se abre, la ventana Comandos de voz muestra los cambios a medida que se producen.
IAgentCommands define una interfaz que permite a las aplicaciones agregar, quitar, establecer y consultar propiedades para una colección Commands . Estas funciones también están disponibles en IAgentCommandsEx.
Una colección Commands puede aparecer como un comando en el menú emergente y en la ventana Comandos de voz para un carácter. Para que aparezca la colección Commands , debe establecer su propiedad Caption . En la tabla siguiente se resume cómo afectan las propiedades de una colección Commands a su presentación.
| Propiedad Caption | Voice-Caption (propiedad) | Voice (propiedad) | Visible (propiedad) | Aparece en el menú emergente del carácter | Aparece en la ventana Comandos de voz |
|---|---|---|---|---|---|
| Sí | Sí | Sí | True | Sí, mediante caption | Sí, mediante VoiceCaption |
| Sí | Sí | No¹ | True | Sí, mediante caption | No |
| Sí | Sí | Sí | False | No | Sí, mediante VoiceCaption |
| Sí | Sí | No¹ | False | No | No |
| No¹ | Sí | Sí | True | No | Sí, mediante VoiceCaption |
| No¹ | Sí | Sí | False | No | Sí, mediante VoiceCaption |
| No¹ | Sí | No¹ | True | No | No |
| No¹ | Sí | No¹ | False | No | No |
| Sí | No¹ | Sí | True | Sí, mediante caption | Sí, mediante caption |
| Sí | No¹ | No¹ | True | Sí | No |
| Sí | No¹ | Sí | False | No | Sí, mediante Caption |
| Sí | No¹ | No¹ | False | No | No |
| No¹ | No¹ | Sí | True | No | No² |
| No¹ | No¹ | Sí | False | No | No² |
| No¹ | No¹ | No¹ | True | No | No |
| No¹ | No¹ | No¹ | False | No | No |
¹Si el valor de la propiedad es null. En algunos lenguajes de programación, es posible que una cadena vacía no se interprete igual que una cadena nula.
²El comando sigue siendo accesible por voz.
Métodos en orden de Vtable
| Métodos IAgentCommands | Descripción |
|---|---|
| GetCommand | Recupera un objeto Command de la colección Commands . |
| GetCount | Devuelve el valor del número de comandos de una colección Commands . |
| SetCaption | Establece el valor de la propiedad Caption de una colección Commands . |
| GetCaption | Devuelve el valor de la propiedad Caption de una colección Commands . |
| SetVoice | Establece el valor de la propiedad Voice para una colección Commands . |
| GetVoice | Devuelve el valor de la propiedad Voice de una colección Commands . |
| SetVisible | Establece el valor de la propiedad Visible para una colección Commands . |
| GetVisible | Devuelve el valor de la propiedad Visible de una colección Commands . |
| Add (Agregar) | Agrega un objeto Command a una colección Commands . |
| Insertar | Inserta un objeto Command en una colección Commands . |
| Remove | Quita un objeto Command de una colección Commands . |
| RemoveAll | Quita todos los objetos Command de una colección Commands . |