IAgentCommands

[Microsoft Agent è deprecato a partire da Windows 7 e potrebbe non essere disponibile nelle versioni successive di Windows.]

Il server Microsoft Agent gestisce un elenco di comandi attualmente disponibili per l'utente. Questo elenco include i comandi definiti dal server per l'interazione generale, ad esempio Nascondi e Proprietà di Microsoft Agent, l'elenco dei client disponibili (ma non attivi dall'input) e i comandi definiti dal client attivo corrente. I primi due set di comandi sono comandi globali; ovvero sono disponibili in qualsiasi momento, indipendentemente dal client attivo di input. I comandi definiti dal client sono disponibili solo quando il client è attivo per l'input.

Recuperare un'interfaccia IAgentCommands eseguendo una query sull'interfaccia IAgentCharacter per IAgentCommands. Ogni applicazione client di Microsoft Agent può definire una raccolta di comandi denominata raccolta Commands . Per aggiungere un oggetto Command alla raccolta, utilizzare il metodo Add o Insert . Sebbene sia possibile specificare le proprietà di un comando usando i metodi IAgentCommand , per ottenere prestazioni ottimali del codice, specificare tutte le proprietà di un comando nei metodi IAgentCommands::Add o IAgentCommands::Insert quando si impostano inizialmente le proprietà per un nuovo comando. È possibile utilizzare i metodi IAgentCommand per eseguire query o modificare le impostazioni della proprietà.

Per ogni comando nell'insieme Commands , è possibile determinare se il comando viene visualizzato nel menu a comparsa del carattere, nella finestra Comandi vocali, in entrambi o in nessuno dei due. Ad esempio, se si vuole che un comando venga visualizzato nel menu a comparsa per il carattere, impostare le proprietà Caption e Visible del comando. Per visualizzare il comando nella finestra Comandi vocali, impostare le proprietà Caption e Voice del comando.

Un utente può accedere ai singoli comandi nella raccolta Commands solo quando l'applicazione client è attiva dall'input e il carattere è visibile. Di conseguenza, in genere si desidera impostare le proprietà Caption, VoiceCaption e Voice per l'oggetto insieme Commands , nonché per i comandi nell'insieme, perché inserisce una voce per l'insieme Commands nel menu a comparsa di un carattere e nella finestra Comandi vocali. Quando l'utente passa al client scegliendo la voce Comandi , il server rende automaticamente attivo l'input client, notificando all'applicazione client l'uso di IAgentNotifySink::ActivateInputState e rende disponibili i comandi nella raccolta. Il server notifica inoltre al client che non è più attivo per l'input con l'evento IAgentNotifySink::ActivateInputState . In questo modo il server può presentare e accettare solo i comandi applicabili al contesto del client attivo di input corrente. Consente inoltre di evitare conflitti tra i nomi dei comandi tra i client.

Un client può anche richiedere in modo esplicito di effettuare se stesso il client attivo tramite il metodo IAgentCharacter::Activate . Questo metodo supporta anche l'impostazione dell'applicazione in modo che non sia il client attivo per l'input. È possibile usare questo metodo quando si condivide un carattere con un'altra applicazione, impostando l'applicazione come input-attivo quando la finestra dell'applicazione ottiene lo stato attivo e non attiva l'input quando perde lo stato attivo.

Analogamente, è possibile usare IAgentCharacter::Activate per impostare l'applicazione su (o meno) sul client attivo del carattere. Il client attivo è il client che riceve l'input quando il carattere è il carattere più alto. Quando questo stato cambia, il server invia una notifica all'applicazione con l'evento IAgentNotifySinkEx::ActiveClientChange .

Quando viene visualizzato il menu a comparsa di un carattere, le modifiche apportate alle proprietà di un insieme Commands o ai comandi nella raccolta non vengono visualizzati finché l'utente non riproduce il menu. Tuttavia, quando si apre, la finestra Comandi vocali visualizza le modifiche apportate.

IAgentCommands definisce un'interfaccia che consente alle applicazioni di aggiungere, rimuovere, impostare ed eseguire query sulle proprietà di una raccolta Commands . Queste funzioni sono disponibili anche da IAgentCommandsEx.

Un insieme Commands può essere visualizzato come comando sia nel menu a comparsa che nella finestra Comandi vocali per un carattere. Per visualizzare l'insieme Commands , è necessario impostarne la proprietà Caption . Nella tabella seguente viene riepilogato il modo in cui le proprietà di un insieme Commands influiscono sulla relativa presentazione.

Proprietà Caption	Voice-Caption, proprietà	Voice, proprietà	Visible, proprietà	Viene visualizzato nel menu a comparsa del carattere	Viene visualizzato nella finestra Comandi vocali
Sì	Sì	Sì	True	Sì, usando Didascalia	Sì, usando VoiceCaption
Sì	Sì	No¹	Vero	Sì, usando Didascalia	No
Sì	Sì	Sì	False	No	Sì, usando VoiceCaption
Sì	Sì	No¹	False	No	No
No¹	Sì	Sì	True	No	Sì, usando VoiceCaption
No¹	Sì	Sì	False	No	Sì, usando VoiceCaption
No¹	Sì	No¹	True	No	No
No¹	Sì	No¹	False	No	No
Sì	No¹	Sì	True	Sì, usando Didascalia	Sì, usando Didascalia
Sì	No¹	No¹	True	Sì	No
Sì	No¹	Sì	False	No	Sì, usando didascalia
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

 

¹If l'impostazione della proprietà è Null. In alcuni linguaggi di programmazione, una stringa vuota potrebbe non essere interpretata come una stringa Null.

² Il comando è ancora accessibile dalla voce.

Metodi nell'ordine Vtable

Metodi IAgentCommands	Descrizione
GetCommand	Recupera un oggetto Command dall'insieme Commands .
GetCount	Restituisce il valore del numero di Comandi in un insieme Commands .
SetCaption	Imposta il valore della proprietà Caption per un insieme Commands .
GetCaption	Restituisce il valore della proprietà Caption di un insieme Commands .
SetVoice	Imposta il valore della proprietà Voice per un insieme Commands .
GetVoice	Restituisce il valore della proprietà Voice di un insieme Commands .
SetVisible	Imposta il valore della proprietà Visible per un insieme Commands .
GetVisible	Restituisce il valore della proprietà Visible di un insieme Commands .
Add	Aggiunge un oggetto Command a un insieme Commands .
Inserire	Inserisce un oggetto Command in un insieme Commands .
Rimuovi	Rimuove un oggetto Command in un insieme Commands .
RemoveAll	Rimuove tutti gli oggetti Command da un insieme Commands .