The MenuAttributes class

Using the MenuAttributes class in conjunction with the Call.playAndGetInput() method enables you to allow the caller to make a selection from a number of items in your voice application. It is the equivalent of a menu or set of radio buttons in a graphical user interface. The MenuAttributes class is an extension of InputAttributes. MenuAttributes inherits all the properties of the InputAttributes class, and has additional attributes that define the menu choices. You can use the same MenuAttributes object in more than one invocation of Call.playAndGetInput(). This enables you to create default menus for common menu operations and reuse these within your application.

The caller is presented with a set of choices, and must select one of the items, either by pressing the key or keys associated with the choice or by saying the word or words associated with it. You can enable and disable menu choices as required. A menu choice consists of:
  • A message that will be played to the caller.
  • An identifying label used by the application.
  • The input keys or words the caller will use to select their choice.
Validation of the caller's input is based upon the specified selector keys and words. If the grammar used for speech recognition contains annotations, validation is performed on the annotation rather than the actual word spoken by the caller. When the caller makes a valid choice the label for that choice is set as the value property of the InputResult object returned by the Call.playAndGetInput() method.

The properties contained in this class, additional to those inherited from InputAttributes, are listed below.

Properties for the menu choices
  • message: an array of the messages for the menu items. These messages can be in the form of single MediaType objects, arrays of MediaType objects, or instances of classes that implement the Playable interface.
  • labels: an array of labels for the menu items, in the form of Strings.
  • keys: an array of selector keys for the menu items, in the form of Strings.
  • words: an array of selector words for the menu items, also in the form of Strings.
These properties have get methods only and are set using a constructor method (see below). The properties cannot be set individually because the group of menu items is made up from all the property arrays combined — the second menu item consists of the second message array item, the second labels array item, the second keys array item and the second words array item. The arrays must therefore be the same length. To change the order of the menu items, simply rearrange the arrays. To use only one response mode (for example DTMF keys but not speech recognition), the array for the unused response mode can be replaced with null.
Other properties
  • headerMessage: the message that is played before the the menu items are listed.You could use this message to say, for example, "What kind of entertainment are you interested in...".
  • footerMessage: the message that is played after the menu items have been listed; if the caller reaches the end of the menu without making a selection. You could use this message to say, for example, "Please press the key corresponding to your choice".
These properties have get and set methods. They are not included in any constructor method, so must be set after the MenuAttributes object has been created.
The constructor methods for this class are:
MenuAttributes()
Constructs an empty menu.
MenuAttributes(MediaType[] messages, java.lang.String[] labels, java.lang.String[] selectorKeys, java.lang.String[] selectorWords)
Constructs a MenuAttributes object with the specified messages, labels, selector keys and selector words. Use null for selectorWords if your application does not use speech recognition. Use null for selectorKeys if your application uses speech recognition only.
Note: The validator property inherited from the InputAttributes class cannot be used with MenuAttributes. This is because the MenuAttributes class generates its own InputValidator based on the contents of the menu. This validator cannot be changed, therefore calling this method will throw an exception.
For example:
public class myVoiceApp extends WVRApplication {
  .
  .
  .
  // Create the voice segment objects that will be used for the prompt
  VoiceSegment vs_pizza_sizes = new VoiceSegment("PizzaSegments", "ChooseAPizzaSize");
  VoiceSegment vs_not_enough_digits = new VoiceSegment("PizzaSegments", "NotEnough");
  VoiceSegment vs_invalid = new VoiceSegment("PizzaSegments", "Invalid");
  .
  .
  .
  // Create the message array
  MediaType[] Menu_Prompts = {
    new VoiceSegment("myApp", "Small"),
    new VoiceSegment("myApp", "Medium"),
    new VoiceSegment("myApp", "Large")
  };
  // Define the menu item labels. These are defined outside of an array
  // as the application will need to refer to them later on to see what choice the caller made.
  String Item1_Small	= "Small";
  String Item2_Medium	= "Medium";
  String Item3_Large	= "Large";
  // Create the labels array
  String[] MenuLabels={ Item1_Small, Item2_Medium, Item3_Large };
  // Create the selector keys array
  String[] Menu_Keys = { "1", "2", "3" };
  // Create the selector words array
  String[] Menu_Words = { "Small", "Medium", "Large" };
  // Use the arrays to create the MenuAttributes object
  MenuAttributes myMenuAtts = new MenuAttributes(Menu_Prompts, Menu_Labels, Menu_Keys, Menu_Words);
  // Set any other attributes required
  myMenuAtts.setHeaderMessage(vs_pizza_sizes);
  myMenuAtts.setFooterMessage(vs_not_enough_digits);
  myMenuAtts.setInvalidInputMessage(vs_invalid);
  myMenuAtts.setTimeout(10);
  myMenuAtts.setNumberOfRepeats(2);
  .
  .
  .
  // Get the caller's input
  InputResult pizza_size = call.playAndGetInput(myPlayAtts, myMenuAtts, myDTMFAtts, myRecoAtts);
  String size = input.getValue();	
}