IAgentCommands

[Microsoft Agent tidak digunakan lagi pada Windows 7, dan mungkin tidak tersedia dalam versi Windows berikutnya.]

Server Microsoft Agent mempertahankan daftar perintah yang saat ini tersedia untuk pengguna. Daftar ini mencakup perintah yang ditentukan server untuk interaksi umum, seperti Sembunyikan dan Properti Agen Microsoft, daftar klien yang tersedia (tetapi non-input-aktif), dan perintah yang ditentukan oleh klien aktif saat ini. Dua set perintah pertama adalah perintah global; artinya, mereka tersedia kapan saja, terlepas dari klien input-aktif. Perintah yang ditentukan klien hanya tersedia ketika klien tersebut aktif input.

Ambil antarmuka IAgentCommands dengan mengkueri antarmukaIAgentCharacter untuk IAgentCommands. Setiap aplikasi klien Agen Microsoft dapat menentukan kumpulan perintah yang disebut Perintah koleksi. Untuk menambahkanPerintahke koleksi, gunakan metode Tambahkan atau Sisipkan. Meskipun Anda dapat menentukan properti Perintah menggunakan metodeIAgentCommand, untuk performa kode optimal, tentukan semua properti Commanddi IAgentCommands::Tambahkan atau IAgentCommands::Sisipkan metode saat awalnya mengatur properti untuk Perintah baru. Anda dapat menggunakan metode IAgentCommand untuk mengkueri atau mengubah pengaturan properti.

Untuk setiapPerintahdi koleksiPerintah, Anda dapat menentukan apakah perintah muncul pada menu pop-up karakter, di Jendela Perintah Suara, di keduanya, atau tidak. Misalnya, jika Anda ingin perintah muncul di menu pop-up untuk karakter, atur perintah Keterangan dan properti Terlihat. Untuk menampilkan perintah di Jendela Perintah Suara, atur Keterangan perintah dan propertiSuara.

Pengguna dapat mengakses perintah individual dalam koleksi Perintah Anda hanya saat aplikasi klien Anda aktif input dan karakter terlihat. Oleh karena itu, Anda biasanya ingin mengatur propertiKeterangan, VoiceCaption, , dan Voice untuk objek pengumpulanPerintahserta untuk perintah dalam koleksi, karena ini menempatkan entri untuk Perintah Anda koleksi pada menu pop-up karakter dan di Jendela Perintah Suara. Saat pengguna beralih ke klien Anda dengan memilih entri Perintah, server secara otomatis membuat input klien Anda aktif, memberi tahu aplikasi klien Anda menggunakan IAgentNotifySink::ActivateInputState dan membuat Perintah dalam koleksinya tersedia. Server juga memberi tahu klien yang tidak lagi aktif input dengan peristiwa IAgentNotifySink::ActivateInputState. Ini memungkinkan server untuk menyajikan dan hanya menerima perintah yang berlaku untuk konteks klien input-aktif saat ini. Ini juga berfungsi untuk menghindari Perintah-tabrakan nama antara klien.

Klien juga dapat secara eksplisit meminta untuk menjadikan dirinya klien input-aktif menggunakan metode IAgentCharacter::Activate. Metode ini juga mendukung pengaturan aplikasi Anda agar tidak menjadi klien input-active. Anda mungkin ingin menggunakan metode ini saat berbagi karakter dengan aplikasi lain, mengatur aplikasi Anda menjadi input-aktif ketika jendela aplikasi Anda mendapatkan fokus dan tidak input-aktif ketika kehilangan fokus.

Demikian pula, Anda dapat menggunakan IAgentCharacter::Activate untuk mengatur aplikasi Anda menjadi (atau tidak) klien aktif karakter. Klien aktif adalah klien yang menerima input ketika karakternya adalah karakter paling atas. Ketika status ini berubah, server memberi tahu aplikasi Anda dengan peristiwa IAgentNotifySinkEx::ActiveClientChange.

Saat menu pop-up karakter ditampilkan, perubahan pada properti Perintah koleksi atau perintah dalam koleksinya tidak muncul sampai pengguna memutar ulang menu. Namun, saat dibuka, Jendela Perintah Suara memang menampilkan perubahan saat terjadi.

IAgentCommands menentukan antarmuka yang memungkinkan aplikasi menambahkan, menghapus, mengatur, dan mengkueri properti untuk Commands collection. Fungsi-fungsi ini juga tersedia dari IAgentCommandsEx.

KoleksiPerintahdapat muncul sebagai perintah di menu pop-up dan Jendela Perintah Suara untuk karakter. Untuk membuat kumpulan Perintah muncul, Anda harus mengatur propertiKeterangan. Tabel berikut ini meringkas bagaimana properti kumpulan Perintah memengaruhi presentasinya.

Properti Keterangan	Properti Voice-Caption	Properti Suara	Properti Terlihat	Muncul di Menu Pop-up Karakter	Muncul di Jendela Perintah Suara
Ya	Ya	Ya	Benar	Ya, menggunakanKeterangan	Ya, menggunakanVoiceCaption
Ya	Ya	Tidak¹	Benar	Ya, menggunakanKeterangan	Tidak
Ya	Ya	Ya	Palsu	Tidak	Ya, menggunakanVoiceCaption
Ya	Ya	Tidak¹	Palsu	Tidak	Tidak
Tidak¹	Ya	Ya	Benar	Tidak	Ya, menggunakanVoiceCaption
Tidak¹	Ya	Ya	Palsu	Tidak	Ya, menggunakanVoiceCaption
Tidak¹	Ya	Tidak¹	Benar	Tidak	Tidak
Tidak¹	Ya	Tidak¹	Palsu	Tidak	Tidak
Ya	Tidak¹	Ya	Benar	Ya, menggunakanKeterangan	Ya, menggunakanKeterangan
Ya	Tidak¹	Tidak¹	Benar	Ya	Tidak
Ya	Tidak¹	Ya	Palsu	Tidak	Ya, menggunakanKeterangan
Ya	Tidak¹	Tidak¹	Palsu	Tidak	Tidak
Tidak¹	Tidak¹	Ya	Benar	Tidak	Tidak²
Tidak¹	Tidak¹	Ya	Palsu	Tidak	Tidak²
Tidak¹	Tidak¹	Tidak¹	Benar	Tidak	Tidak
Tidak¹	Tidak¹	Tidak¹	Palsu	Tidak	Tidak

 

¹Jika pengaturan properti null. Dalam beberapa bahasa pemrograman, string kosong mungkin tidak ditafsirkan sama dengan string null.

² Perintah masih dapat diakses suara.

Metode dalam Urutan Vtable

Metode IAgentCommands	Deskripsi
GetCommand	Mengambil objekPerintahdari kumpulanPerintah.
GetCount	Mengembalikan nilai jumlahPerintahdalam kumpulanPerintah.
SetCaption	Mengatur nilai propertiKeteranganuntuk kumpulanPerintah.
GetCaption	Mengembalikan nilai propertiKeterangandari kumpulanPerintah.
SetVoice	Mengatur nilai properti Voice untuk koleksiPerintah.
GetVoice	Mengembalikan nilai propertiSuaradari kumpulanPerintah.
SetVisible	Mengatur nilai propertiTerlihat untuk kumpulanPerintah.
GetVisible	Mengembalikan nilai propertiTerlihat dari kumpulanPerintah.
Tambahkan	Menambahkan objekPerintahke kumpulanPerintah.
Sisipkan	Menyisipkan objekPerintahdalam kumpulanPerintah.
Hapus	Menghapus objekPerintahdalam kumpulanPerintah.
HapusSemua	Menghapus semua objekPerintahdari kumpulanPerintah.