SpObjectTokenCategory EnumerateTokens Method (SAPI 5.3)

Microsoft Speech API 5.3

Object: SpObjectTokenCategory

EnumerateTokens Method

The EnumerateTokens method returns a selection of SpObjectToken objects.

Selection criteria may be applied optionally.

  
    SpObjectTokenCategory.EnumerateTokens(
     [RequiredAttributes As String = ""],
     [OptionalAttributes As String = ""]
) As ISpeechObjectTokens

Parameters

• RequiredAttributes
  [Optional] Specifies the RequiredAttributes. To be returned by EnumerateTokens, the searched tokens must contain all of the specific required attributes. If no profiles match the selection, the selection returned will not contain any elements. By default no attributes are required and so returns all the tokens discovered.
• OptionalAttributes
  [Optional] Specifies the OptionalAttributes. Returned tokens containing the RequiredAttributes are sorted by OptionalAttributes. If OptionalAttributes is specified, the tokens are listed with the OptionalAttributes first. By default no attribute is specified so the list returned is in the order discovered from the speech configuration database.

Return Value

The EnumerateTokens method returns an ISpeechObjectTokens variable.

Example

The following Visual Basic form code demonstrates a simple use of the EnumerateTokens method. To run this code, create a form with the following controls:

• A list box called List1
• Two command buttons called Command1 and Command2

Paste this code into the Declarations section of the form.

The Command1 procedure creates an SpVoice object and uses the voice's GetVoices method to get an ISpeechObjectTokens collection containing an object token for each voice on the computer. A For Each loop lists each voice token's Description property in the list box.

The Command2 procedure creates a new SpObjectTokenCategory object, uses the SetId method to associate it with the category of voices, and the EnumerateTokens method to get an ISpeechObjectTokens collection containing an object token for each voice on the computer. A For Each loop lists each voice token's Description property in the list box.

The list of voices displayed by the two command buttons will be identical.

  
Option Explicit

Dim V As SpeechLib.SpVoice                  'voice object
Dim T As SpeechLib.SpObjectToken            'object token
Dim E As SpeechLib.ISpeechObjectTokens      'an enumeration of object tokens
Dim C As SpeechLib.SpObjectTokenCategory    'a category of object tokens

Private Sub Command1_Click()
    On Error GoTo EH

    List1.Clear
    List1.AddItem "Enumerate voices with SpVoice.GetVoices"
    List1.AddItem ""

    Set V = New SpVoice                 'create new voice
    Set E = V.GetVoices()               'no parameters -- get all voices

    For Each T In E
        List1.AddItem "   " & T.GetDescription
    Next

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub Command2_Click()
    On Error GoTo EH
    List1.Clear
    List1.AddItem "Enumerate voices with SpObjectToken.EnumerateTokens"
    List1.AddItem ""

    Set C = New SpObjectTokenCategory   'create new token category object
    C.SetId SpeechCategoryVoices        'init ID of voices category
    Set E = C.EnumerateTokens()         'no parameters -- get all voices

    For Each T In E
        List1.AddItem "   " & T.GetDescription
    Next

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub ShowErrMsg()

    ' Declare identifiers:
    Dim T As String

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

End Sub