ISpeechPhraseProperty Children Property (SAPI 5.3)

Speech API 5.3
Microsoft Speech API 5.3

Interface: ISpeechPhraseProperty

Children Property

The Children property returns a collection of the property's child objects.

A child is a rule within a rule. That is, within a command and control grammar, rules are explicitly defined with the Rule tag. To allow greater flexibility, it is possible to allow another rule to be used within one by declaring it with the RuleRef tag. In this case, the second rule referenced by the RuleRef tag could be a child. Child rules are defined with the RULE tag, and referenced with the RULEREF tag. Properties can be added to rulerefs and phrases within the rule with the PROPNAME attribute If a child rule is present, the original rule containing the child is the parent. In this way, a rule can contain several levels of children and child rules can have several levels of parents.

An example of this is sol.xml for the card game solitaire. A user may play a card such as "move the red five on the black seven." Examine sol.xml; the rule is set up so that both the color of the card as well as the rank are referenced within the MoveCard rule. In this case, a successful recognition would have two top parent nodes: From and To. In turn, each parent node would have two children: color and rank. This way, an application could sort through the rules and know exactly which card moves (the From node) and which card receives it (the To node). The rule name would still be MoveCard.

In contrast, the more simple command "play the red ace," has only two nodes (color and rank). Neither node is considered to be either parent or child since the rule PlayCard has no PROPNAME tag. The nodes are peers of each other.


Set: (This property is read-only)
Get: ISpeechPhraseProperties = ISpeechPhraseProperty.Children


The owning object.
Set: (This property is read-only)
Get: An ISpeechPhraseProperties object returning the value of the property.


The following code demonstrates the Children property from a command and control recognition.

To run this code, create a form with the following controls:

  • Two labels called Label1 and Label2

Paste this code into the Declarations section of the form.

The Form_Load procedure creates and activates a command and control grammar. The grammar file sol.xml is the solitaire grammar provided with the SDK. The path listed is for a standard SDK install and may be changed as needed.

The display indicates that the rules match. If any are child rules, then the child name is also displayed. For instance, if "move the red five on the black six," has been recognized, the application displays the recognized text in Label1. Label2 displays the rule name and any associated children under it. If the rule has no children, Label2 displays "No Children."`

Option Explicit
Public WithEvents RC As SpSharedRecoContext
Public myGrammar As ISpeechRecoGrammar

Private Sub Form_Load()
    On Error GoTo EH

    Set RC = New SpSharedRecoContext

    Set myGrammar = RC.CreateGrammar
    myGrammar.CmdLoadFromFile "C:\Program Files\Microsoft Speech SDK 5.3\Samples\Common\sol.xml", SLODynamic
    myGrammar.CmdSetRuleIdState 0, SGDSActive

    If Err.Number Then ShowErrMsg
End Sub

Private Sub RC_FalseRecognition _
   (ByVal StreamNumber As Long, _
    ByVal StreamPosition As Variant, _
    ByVal Result As SpeechLib.ISpeechRecoResult)

    Label1.Caption = "(no recognition)"
    Label2.Caption = ""

End Sub

Private Sub RC_Recognition _
   (ByVal StreamNumber As Long, _
    ByVal StreamPosition As Variant, _
    ByVal RecognitionType As SpeechLib.SpeechRecognitionType, _
    ByVal Result As SpeechLib.ISpeechRecoResult)

    Dim i, j, theFirstElement, theNumberOfElements As Long
    Dim theString As String

    On Error GoTo EH

    Label1.Caption = Result.PhraseInfo.GetText & vbCrLf

    Label2.Caption = "Rule Properties Found : " & Result.PhraseInfo.Properties.Count & vbCrLf
    For i = 0 To Result.PhraseInfo.Properties.Count - 1

        'Property name used
        Label2.Caption = Label2.Caption & _
            "Rule " & i & ": " & Result.PhraseInfo.Properties.Item(i).Name & vbCrLf

        If Not Result.PhraseInfo.Properties.Item(i).Children Is Nothing Then
            Label2.Caption = Label2.Caption & _
                "   Children = " & Result.PhraseInfo.Properties.Item(i).Children.Count & vbCrLf

            For j = 0 To Result.PhraseInfo.Properties.Item(i).Children.Count - 1
                Label2.Caption = Label2.Caption & _
                    "      Rule = " & Result.PhraseInfo.Properties.Item(i).Children.Item(j).Name & vbCrLf
            Label2.Caption = Label2.Caption & "   No Children" & vbCrLf
        End If


    If Err.Number Then ShowErrMsg
End Sub

Private Sub ShowErrMsg()

    ' Declare identifiers:
    Const NL = vbNewLine
    Dim T As String

    T = "Desc: " & Err.Description & NL
    T = T & "Err #: " & Err.Number
    MsgBox T, vbExclamation, "Run-Time Error"

End Sub