Define application commands (Android)

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:

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 on the personalization & help screen.

Description of my test command set - a human-readable description; displayed on the personalization & help screen.
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 receives 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 that's said to initiate the application command; displayed on the personalization & help screen if no display string is set.

THIS IS A TEST - the application command display string; displayed on the personalization & help screen. 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 on the personalization & help screen.
Obtain a reference to the VuiController object in your activity 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.
Call the synchronize() method on the VuiController to apply changes:
```
theVuiController.synchronize();
```

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.

Important

If you use a display string, the placeholder in the display string and in the phrase must be the same (see: Recommendations for phrases).

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:

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.
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 on the personalization & help screen.
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

The value of a placeholder can be changed. The new value will become active after the next synchronize() call.

Obtain a reference to the VuiController object in your activity and associate the placeholder with it:

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

Call the synchronize() method on the VuiController to apply changes:
```
theVuiController.synchronize();
```

Recognizing application commands

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

Your speech-enabled activity must implement the VuiControllerEventListener interface. The VuiController instance automatically detects if this is the case and calls the appropriate callbacks, including onCommandRecognized. See also: VuiController events.
```
public class MyActivity extends Activity implements VuiControllerEventListener {
```
Implement the onCommandRecognized method of the VuiControllerEventListener interface. This method is called back when an application command is recognized.
```
public void onCommandRecognized(String id, String spokenPhrase, String content, HashMap<String, String> placeholderValues) {
```
In the callback method, check for the ID of the recognized application command.
```
if (id.equals("myShowPatientCommand")) {
```

Process the recognized placeholder values:

if (placeholderValues.containsKey("patient")) {
    String patientName = placeholderValues.get("patient");
    // Perform the processing in response to the recognized application command

Note

The procedure above also applies for commands with standard placeholders. Standard placeholders delivered with Dragon Medical SpeechKit have predefined keys, for more information, see: Standard placeholders.

Considerations when implementing 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.
To enable/disable a command set, call the setEnabled() method. To query the enabled/disabled state of a command set, call the getEnabled() method.
To enable/disable individual commands in a command set, call the enableCommand() method with the corresponding command ID.
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.
Best practice is to make all changes to application commands, command sets and placeholders together and call the synchronize() method only once.

Feedback

Was this page helpful?

Last updated on 2025-03-07