SemanticResultValue Class

Article
10/07/2009

Sets values to SemanticValue objects created in a Grammar using GrammarBuilder instances.

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

Syntax

'Declaration
<DebuggerDisplayAttribute("{_tag.DebugSummary}")> _
Public Class SemanticResultValue

[DebuggerDisplayAttribute("{_tag.DebugSummary}")] 
public class SemanticResultValue

[DebuggerDisplayAttribute(L"{_tag.DebugSummary}")] 
public ref class SemanticResultValue

/** @attribute DebuggerDisplayAttribute("{_tag.DebugSummary}") */ 
public class SemanticResultValue

DebuggerDisplayAttribute("{_tag.DebugSummary}") 
public class SemanticResultValue

Remarks

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 an instance of SemanticValue, through the Semantics property on RecognizedPhrase.

Note

Values 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 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.
```
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 a System.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 Append(SemanticResultValue) and SemanticResultValue(Object): if the recognition logic using 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 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 SemanticResultValue, 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.

Inheritance Hierarchy

System.Object
Microsoft.Speech.Recognition.SemanticResultValue

Example

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

Thread Safety

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

Platforms

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2003, Windows Vista Ultimate Edition, Windows Vista Business Edition, Windows Vista Enterprise Edition

SemanticResultValue Class

Syntax

Remarks

Inheritance Hierarchy

Example

Thread Safety

Platforms

Development Platforms

Target Platforms

See Also

Reference

Additional resources