SemanticResultValue Class

Definition

Namespace:

System.Speech.Recognition

Assembly:

System.Speech.dll

Package:

System.Speech v9.0.0-rc.2.24473.5

Source:

SemanticResultValue.cs

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

public ref class SemanticResultValue

public class SemanticResultValue

type SemanticResultValue = class

Public Class SemanticResultValue

Inheritance

Object

SemanticResultValue

Examples

The following example returns a Grammar that recognizes the command "Set/Change/Alter Foreground/Background … [color list]". SemanticResultValue and SemanticResultKey instances (in conjunction 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 the 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);

  // Define the arguments for the command to select foreground or background
  // and to change their color as semantic 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)))
  {

    // Use implicit conversion of SemanticResultValue to GrammarBuilder.
    colorChoice.Add(
        (GrammarBuilder) (new SemanticResultValue(colorName, (Color.FromName(colorName)).Name)));
  }

  // Create a GrammarBuilder for CmdArgs to be appended to CmdIntro 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;
}

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 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.

The typical use of a SemanticResultValue instance associates the instance with a recognizable component of a Grammar, such as a phrase, a rule, or a Choices object. If the associated component is used as part of a 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 (specified by an instance of Object) is used to construct a SemanticResultValue object, the SemanticResultValue 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).

• If a string value phrase or specific GrammarBuilder instance is used, together with a Object that specifies a SemanticResultValue value, that value is automatically associated with the string value phrase or the 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 following example illustrates this, and is functionally equivalent to the preceding example, which used explicit calls to Append 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 SemanticValue 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.

After a 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.

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

Constructors

SemanticResultValue(GrammarBuilder, Object)	Initializes a new instance of the SemanticResultValue class and associates a semantic value with a GrammarBuilder object.
SemanticResultValue(Object)	Initializes a new instance of the SemanticResultValue class and specifies a semantic value.
SemanticResultValue(String, Object)	Initializes a new instance of the SemanticResultValue class and associates a semantic value with a String object.

Methods

Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToGrammarBuilder()	Returns an instance of GrammarBuilder constructed from the current SemanticResultValue instance.
ToString()	Returns a string that represents the current object. (Inherited from Object)

See also

• Using a SemanticResultKey to Extract a SemanticResultValue