SemanticResultValue Class

Use of SemanticResultValue and SemanticResultKey objects, in conjunction with GrammarBuilder and Choices is the easiest way to design a semantic structure for a Grammar. Semantic information for a phrase is accessed by obtaining and instance of SemanticValue, through the Semantics property on RecognizedPhrase.

Note:
Value managed by SemanticResultValue objects are defined by System.Object instances passed to their constructors. This System.Object can only have an underlying type only of bool, int, float, or string. Any other type will prevent construction of a Grammar instance with the [T:System.Speech.Recognition.SemanticResultValue.]

Typical use of SemanticResultValue instances associates the instance with a recognizable Grammar grammar element, such as a phrase, rule, or Choices. If the associated element is used as part of the recognition operation, the SemanticResultValue is used to define a value in the semantics of the returned phrase.

There are two basic methods for associating a SemanticResultValue instance with a grammar element, depending on the constructor used to create the SemanticResultValue.

• If only the value, as specified by an instance of Object, is used in constructing a SemanticResultValue object, the SemanticResultValue is be associated with the grammar element which preceded it in addition to a GrammarBuilder object.

  For instance, in the code fragment below, if a Grammar constructed using this GrammarBuilder instance recognizes the word "background", a value of true is set in the recognized phrase semantics.

  Copy

  GrammarBuilder backgroundGB=new GrammarBuilder("background");
  backgroundGB.Append(new SemanticResultValue(true));
  

  For more information, see the description of. SemanticResultValue(Object)

• If given string value phrase or specific GrammarBuilder instance is used, along with aSystem.Object that specifies a SemanticResultValue value, that value is automatically associated with that string value phrase or GrammarBuilder instance: if the phrase or GrammarBuilder object is used in the process of recognition, the value will be assigned to the semantics of the recognized phrase.

  The code fragment below illustrates this, and is functionally equivalent to the fragment above, which used the explicit calls to [M:System.Speech.Recognition.GrammarBuilder.Append(System.Speech.Recognition.SemanticResultValue][)] and SemanticResultValue(Object): if the recognition logic using the word "background", the value true will be added to the recognized semantics.

  Copy

  fgOrbgChoice.Add((GrammarBuilder)new SemanticResultValue("background", true));
  

  For more information, see the description of SemanticResultValue(GrammarBuilder, Object) and SemanticResultValue(String, Object).

To be used by a Grammar in recognition, all SemanticResultValue instances must be associated with one of the SemanticValue objects used by that Grammar. This is done by associating a semantic key with the SemanticResultValue.

Semantic keys can explicitly attached to a SemanticResultValue, using an SemanticResultKey object. SemanticResultValue instances not explicitly attached to a key, are attached to the root key of the default SemanticValue

Once an SemanticResultValue has been used to set the Value, whether it is tagged with the default root key or by any particular SemanticResultKey, that value must not be modified or an exception will occur during recognition operations.

For example:

GrammarBuilder gb=new GrammarBuilder();
gb.Append(new SemanticResultValue("One"));
gb.Append(new SemanticResultValue("Two"));

would cause an exception as it sets and then modified the root Value of a Grammar.

On the other hand:

Choices fgOrbgChoice = new Choices();
fgOrbgChoice.Add((GrammarBuilder)new SemanticResultValue("background"));
fgOrbgChoice.Add((GrammarBuilder)new SemanticResultValue("foreground"));
SemanticResultKey fgOrbgChoiceKey = new SemanticResultKey("BgOrFgText", fgOrbgChoice);

Is permitted, because although multiple instances of SemanticResultValue are defined, they are included in a Choices object, and only one will ever be used to set the value of the key BgOrFgText.

The example below returns a Grammar for recognizing the command "Set/Change/Alter Foreground/Background … [color list]". SemanticResultValue, and SemanticResultKey instances (along with Choices and GrammarBuilder objects) are used to define a semantics that can be parsed on recognition to determine what color was request, and whether the foreground or background is to be modified.

private Grammar FgBgColorGrammar() {
    Grammar grammar = null;
    //Allow command to begin with set, alter, change.
    Choices introChoices = new Choices();
    foreach (string introString in new string[] { "Change", "Set", "Alter" }) {
        GrammarBuilder introGB = new GrammarBuilder(introString);
        introChoices.Add(new SemanticResultValue(introGB,
                            String.Format("Command: {0}", introString)));
    }         
    GrammarBuilder cmdIntro = new GrammarBuilder(introChoices);
    //Now define the arguments to the command for Foreground or background and color as sementic Values
    Choices fgOrbgChoice = new Choices();
    GrammarBuilder backgroundGB=new GrammarBuilder("background");
    backgroundGB.Append(new SemanticResultValue(true));
    fgOrbgChoice.Add(backgroundGB);
    fgOrbgChoice.Add((GrammarBuilder)new SemanticResultValue("foreground", false));
    SemanticResultKey fgOrbgChoiceKey = new SemanticResultKey("BgOrFgBool", fgOrbgChoice);
    Choices colorChoice = new Choices();
    foreach (string colorName in System.Enum.GetNames(typeof(KnownColor))) {
        colorChoice.Add((GrammarBuilder)
                                        (new SemanticResultValue(colorName, (Color.FromName(colorName)).Name)));
        //Uses implicit conversion of SemanticResultValue to GrammarBuilder    
    }

    //Create GrammarBuilder for CmdArgs to be appended to CmdInto using Semantic keys.
    GrammarBuilder cmdArgs = new GrammarBuilder();
    cmdArgs.Append(new SemanticResultKey("BgOrFgBool", fgOrbgChoice));
    cmdArgs.AppendWildcard();
    cmdArgs.Append(new SemanticResultKey("colorStringList", colorChoice));

    GrammarBuilder cmds = GrammarBuilder.Add(cmdIntro,
                                             new GrammarBuilder(new SemanticResultKey("Cmd Args", cmdArgs)));
    grammar = new Grammar(cmds);
    grammar.Name = "Tree [Set,change,alter] [foreground,background] * color";
    return grammar;
}

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003

.NET Framework

Reference