SemanticResultValue Class

Represents a semantic value and optionally associates the value with a component of a speech recognition grammar.

Inheritance Hierarchy

System.Object
Microsoft.Speech.Recognition.SemanticResultValue

Namespace: Microsoft.Speech.Recognition
Assembly: Microsoft.Speech (in Microsoft.Speech.dll)

Syntax

'Declaration
Public Class SemanticResultValue
'Usage
Dim instance As SemanticResultValue

public class SemanticResultValue

Remarks

You can use SemanticResultValue and SemanticResultKey objects, in conjunction with GrammarBuilder and Choices objects, to define the semantic structure for a speech recognition grammar. To access the semantic information in a recognition result, obtain a SemanticValue instance through the Semantics property on RecognizedPhrase.

Note

Values managed by SemanticResultValue objects are defined by Object instances passed to their constructors. The underlying type of this Object must be bool, int, float, or string. Any other type will prevent construction of a Grammar instance with the SemanticResultValue.

Typical use associates the semantic value specified by a SemanticResultValue instance with a recognizable component of a Grammar object, such as a phrase, a rule, or a Choices object. If the associated grammar component is used in a recognition operation, the value specified by SemanticResultValue is assigned to the Semantics property of the RecognizedPhrase.

You can associate a SemanticResultValue instance with a grammar component in one of two ways, depending on the constructor used to create the SemanticResultValue.

Construct a SemanticResultValue and specify only a value. Incorporate the SemanticResultValue in a GrammarBuilder object. The value is associated with the grammar component that 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.
```
GrammarBuilder backgroundGB=new GrammarBuilder("background");
backgroundGB.Append(new SemanticResultValue(true));
```
For more information, see the description of SemanticResultValue(Object).
Construct a SemanticResultValue and specify a grammar component as well as a value. The value will be associated with the specified grammar component. If the grammar component is used during speech recognition, the value specified by SemanticResultValue will be assigned to the Semantics property of the RecognizedPhrase object.

The code fragment below illustrates this, and is functionally equivalent to the fragment above, which used explicit calls to Append(SemanticResultValue) and SemanticResultValue(Object). If the recognition logic uses the word "background", the value true will be added to the recognized semantics.
```
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 SemanticResultValue objects used by that Grammar. This is done by associating a semantic key with the SemanticResultValue.

Semantic keys can be explicitly attached to a SemanticResultValue using a 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 SemanticResultValue, that value must not be modified or an exception will occur during recognition operations.

The following example will cause an exception because it sets and then modifies the root Value of a Grammar.

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

On the other hand, the code in the following example is permitted. Although it defines multiple instances of SemanticResultValue, they are included in a Choices object, and only one will ever be used to set the value of the key BgOrFgText.

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

Examples

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 semantics that can be parsed on recognition. The parsed semantics will determine which color was requested 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;
}

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Share via

SemanticResultValue Class

Inheritance Hierarchy

Syntax

Remarks

Examples

Thread Safety

See Also

Reference

Additional resources