IAgentCommands

[Microsoft Agent является нерекомендуемым начиная с Windows 7 и может быть недоступен в последующих версиях Windows.]

Сервер агента Майкрософт поддерживает список команд, которые в настоящее время доступны пользователю. Этот список включает команды, определяемые сервером для общего взаимодействия, такие как Скрыть и Свойства агента Майкрософт, список доступных (но неактивных для ввода) клиентов, а также команды, определенные текущим активным клиентом. Первые два набора команд являются глобальными; то есть они доступны в любое время, независимо от клиента, активного входными данными. Определяемые клиентом команды доступны только в том случае, если клиент активен для ввода.

Получите интерфейс IAgentCommands , запросив интерфейс IAgentCharacter для IAgentCommands. Каждое клиентское приложение Агента Майкрософт может определить коллекцию команд, называемую коллекцией Commands . Чтобы добавить command в коллекцию, используйте метод Add или Insert . Хотя свойства команды можно указать с помощью методов IAgentCommand , для оптимальной производительности кода укажите все свойства command в методах IAgentCommands::Add или IAgentCommands::Insert при первоначальной настройке свойств для новой команды. Для запроса или изменения параметров свойств можно использовать методы IAgentCommand .

Для каждой команды в коллекции Commands можно определить, отображается ли команда во всплывающем меню символа, в окне голосовых команд в обоих элементах или ни в том, ни в другом. Например, если вы хотите, чтобы команда отображалась во всплывающем меню для символа, задайте для команды свойства Caption и Visible . Чтобы отобразить команду в окне Голосовые команды, задайте свойства Caption и Voice команды.

Пользователь может получить доступ к отдельным командам в коллекции Commands, только если ваше клиентское приложение активно для ввода и символ видим. Поэтому обычно требуется задать свойства Caption, VoiceCaption и Voice для объекта коллекции Commands , а также для команд в коллекции , так как это помещает запись для коллекции Commands во всплывающее меню символа и в окне Голосовые команды. Когда пользователь переключается на клиент, выбрав его запись "Команды ", сервер автоматически делает клиент активным для ввода, уведомляя клиентское приложение с помощью IAgentNotifySink::ActivateInputState и делая команды в своей коллекции доступными . Сервер также уведомляет клиента о том, что он больше не активен для ввода с помощью события IAgentNotifySink::ActivateInputState . Это позволяет серверу представлять и принимать только те команды , которые применяются к контексту текущего активного клиента ввода. Это также позволяет избежать конфликтов имен команд между клиентами.

Клиент также может явно запросить, чтобы сделать себя клиентом input-active с помощью метода IAgentCharacter::Activate . Этот метод также поддерживает установку приложения на то, чтобы оно не было клиентом, активным для ввода. Этот метод может потребоваться использовать при совместном использовании символа с другим приложением, чтобы приложение было активным для ввода, когда окно приложения получает фокус, а не активным для ввода при потере фокуса.

Аналогичным образом можно использовать IAgentCharacter::Activate , чтобы задать для приложения значение (или не быть) активным клиентом символа. Активный клиент — это клиент, который получает входные данные, когда его символ является самым верхним символом. При изменении этого состояния сервер уведомляет приложение с помощью события IAgentNotifySinkEx::ActiveClientChange .

При отображении всплывающего меню символа изменения свойств коллекции Commands или команды в ней не отображаются до тех пор, пока пользователь не переиграет меню. Однако при открытии в окне Голосовые команды отображаются изменения по мере их изменения.

IAgentCommands определяет интерфейс, позволяющий приложениям добавлять, удалять, задавать и запрашивать свойства для коллекции Commands . Эти функции также доступны в IAgentCommandsEx.

Коллекция Commands может отображаться как команда во всплывающем меню и окне голосовых команд для символа. Чтобы коллекция Commands отображалась, необходимо задать ее свойство Caption . В следующей таблице показано, как свойства коллекции Commands влияют на ее представление.

Свойство Caption	Свойство Voice-Caption	Свойство voice	Свойство Visible	Отображается во всплывающем меню символа	Отображается в окне "Голосовые команды"
Да	Да	Да	True	Да, использование заголовка	Да, с помощью VoiceCaption
Да	Да	No¹	True	Да, использование заголовка	Нет
Да	Да	Да	Неверно	Нет	Да, с помощью VoiceCaption
Да	Да	No¹	False	Нет	Нет
No¹	Да	Да	True	нет	Да, с помощью VoiceCaption
No¹	Да	Да	Неверно	Нет	Да, с помощью VoiceCaption
No¹	Да	No¹	True	нет	Нет
No¹	Да	No¹	False	Нет	Нет
Да	No¹	Да	True	Да, использование заголовка	Да, использование заголовка
Да	No¹	No¹	True	Да	Нет
Да	No¹	Да	Неверно	Нет	Да, использование заголовка
Да	No¹	No¹	False	Нет	Нет
No¹	No¹	Да	True	нет	No²
No¹	No¹	Да	Неверно	Нет	No²
No¹	No¹	No¹	True	нет	Нет
No¹	No¹	No¹	False	Нет	Нет

 

¹Если свойство имеет значение NULL. В некоторых языках программирования пустая строка может не интерпретироваться так же, как пустая строка.

² Эта команда по-прежнему доступна для голосовых функций.

Методы в порядке таблицы Vtable

Методы IAgentCommands	Описание
GetCommand	Извлекает объект Command из коллекции Commands .
GetCount	Возвращает значение числа команд в коллекции Commands .
SetCaption	Задает значение свойства Caption для коллекции Commands .
GetCaption	Возвращает значение свойства Caption коллекции Commands .
SetVoice	Задает значение свойства Voice для коллекции Commands .
GetVoice	Возвращает значение свойства Voice коллекции Commands .
SetVisible	Задает значение свойства Visible для коллекции Commands .
GetVisible	Возвращает значение свойства Visible коллекции Commands .
Добавить	Добавляет объект Command в коллекцию Commands .
Вставить	Вставляет объект Command в коллекцию Commands .
Удалить	Удаляет объект Command из коллекции Commands .
Removeall	Удаляет все объекты Command из коллекции Commands .