Define application commands (.NET)

Each application command is associated with one command set. A command set is associated with one or more VUI forms. A VUI form can have more than one command set associated with it.

Prerequisites

You've speech-enabled your app.

Procedure

To define application commands, do the following:

1. Create a command set by instantiating the CommandSet class:

   CommandSet testCommandSet = new CommandSet("My Test CommandSet", "Description of my test command set");
   

   My Test CommandSet - a human-readable title for your command set; displayed in the personalization & help window.

   Description of my test command set - a human-readable description; displayed in the personalization & help window.

2. Create application commands in the command set:

   testCommandSet.CreateCommand("myTestCommand", "this is a test", "THIS IS A TEST", "My test command description.");
   

   myTestCommand - the unique identifier of the application command; this is the identifier that your app will receive in the application command event callback when it's recognized.

   Important

   Make sure the application command ID doesn't contain spaces and doesn't start with a number.

   this is a test - the application command phrase; displayed in the personalization & help window if no display string is set.

   THIS IS A TEST - the application command display string; displayed in the personalization & help window. If you don't want to set a display string, pass a null value or empty string.

   My test command description - a human-readable description; displayed in the personalization & help window.

3. Obtain a reference to the VuiController object and associate the command set with it:

   theVuiController.AssignCommandSets(new CommandSet[] { testCommandSet});
   

   Important

    AssignCommandSets() replaces your application commands; it doesn't append commands to an existing set or append additional sets. Define all your application commands and command sets and then call AssignCommandSets() only once.

Standard placeholders

Standard placeholders are delivered with Dragon Medical SpeechKit. To add a standard placeholder to an application command, add its identifier to the phrase of the command:

testCommandSet.CreateCommand("myScrollCommand", "scroll down <standard:cardinal0-100> pages", "scroll down <standard:cardinal0-100> pages","Scrolls down the specified number of pages.");

For a list of standard placeholders, see: Standard placeholders.

App-defined placeholders

When designing the VUI for your app, you can provide one or more commands. For example, you can define voice commands that refer to a patient name: show allergies for mister Pink or create new note for mister Orange. To do this, you can create an app-defined placeholder and add it to application commands as needed. Proceed as follows:

1. Create an application command with a placeholder defined in angled brackets for the phrase parameter:

   testCommandSet.CreateCommand("myShowPatientCommand", "show me <patient>", "show me <patient>", "Shows data for the corresponding patient.");
   

   <patient> is the unique identifier of the placeholder.

   Tip

   The same placeholder can be used in different commands.

2. Create the placeholder by creating an instance of the CommandPlaceholder class:

   CommandPlaceholder patientCommandPlaceholder = new CommandPlaceholder("patient", "Name of the patient");
   

   patient - the unique identifier of the placeholder that's used in application command phrases; must not contain spaces and/or numbers.

   Name of the patient - a human-readable description; displayed in the personalization & help window.

3. Set its phrases and values:

   patientCommandPlaceholder.SetValues(new String[] { "PTN.48389488", "PTN.48323466"}, new String[] { "Mr. Pink", "Mr. Orange"});
   

   "PTN.48389488", "PTN.48323466" - an array of strings containing the values of the placeholder.

   "Mr. Pink", "Mr. Orange" - an array of strings containing the corresponding spoken forms.

   The number of elements in the two arrays must be the same. In this example, the "patient" placeholder can have two values, PTN.48389488 if the user says mister Pink or PTN.48323466 if the user says mister Orange.

   Note

   If you use a display string, the placeholder in the display string and in the phrase must be the same. The value of a placeholder can be changed. The new value will become active after the next synchronize() call.

4. Obtain a reference to the VuiController object and associate the placeholder with it:

   theVuiController.AssignCommandPlaceholders(new CommandPlaceholder[] { patientCommandPlaceholder});
   

Recognizing application commands

Dragon Medical SpeechKit notifies your app about recognized application commands; the OnCommandRecognized event is fired. For your app to receive this event, do the following:

1. Add an event handler to the CommandRecognized IVuiController event. For more information, see: VuiController events.

   vuiController.CommandRecognized += new CommandRecognized(vuiController_CommandRecognized);
   

   The vuiController_CommandRecognized method will be called back when an application command is recognized.

2. In the callback method, check for the ID of the recognized application command.

   void vuiController_CommandRecognized(string id, string spokenPhrase, string content, Dictionary<string, string> placeholderValues)
   {
       if (id == " myShowPatientCommand ")
       {
   
   

3. Process the recognized placeholder values.

           if (placeholderValues.ContainsKey("patient"))
           {
               string patientName = placeholderValues["patient "];
               // Perform the processing in response to the recognized application command…
           }
   

Considerations when defining application commands

• Commands can have multiple phrases; call the CreateCommand method multiple times for the same ID, passing the phrases you want defined for the application command.

• Your app is notified when an application command is recognized via a VuiController event callback.

• To enable/disable or to query the enabled/disabled state of a command set, use the Enabled property of the corresponding command set object.

• To enable/disable individual commands in a command set, call the EnableCommand method with the corresponding command ID.

• If your app wants to modify attributes of application commands or command sets (for example, add new application commands, enable/disable application commands or change placeholder values after the end user has already used speech recognition), your app must apply the changes to the attributes by calling the Synchronize() method on the VuiController. It's best practice to do all changes before applying them via Synchronize().

• You can speech-enable your app UI even if no speech-enabled controls are active.

• To change the placeholder in an application command, use the clearValues method. Once the placeholder is empty, you can add new phrases and values to the placeholder.

• Application commands are also available in custom views (enabled using the CustomVuiController from Nuance.SpeechAnywhere.Custom namespace). To use application commands with the CustomVuiController, the same steps must be followed as for the VuiController.

See also

Voice commands

Application commands