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();
}