SpVoice WaitUntilDone method (SAPI 5.3)

Microsoft Speech API 5.3

Object: SpVoice

WaitUntilDone Method

The WaitUntilDone method blocks the caller until either the voice has finished speaking or the specified time interval has elapsed.

The purpose of this method is to block application execution while a voice is speaking asynchronously. The effect of performing a single WaitUntilDone call following a Speak or SpeakStream call is similar to performing those calls synchronously. But the WaitUntilDone method can be used in conjunction with the DoEvents statement to block an application's forward progress while allowing it to receive events. This is demonstrated in the example below.

  
    SpVoice.WaitUntilDone(
     msTimeout As Long
) As Boolean

Parameters

• msTimeout
  Specifies the timeout in milliseconds. If -1, the time interval is ignored and the method simply waits for the voice to finish speaking.

Return Value

A Boolean variable indicating which case terminated the call. If True, the voice finished speaking; if False, the time interval elapsed.

Example

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

• Three picture controls called Picture1, Picture2, and Picture3
• Three command buttons called Command, Command2, and Command3

Paste this code into the Declarations section of the form.

The three picture controls have MouseMove event procedures which change their background colors when the mouse is moved over them. The Form_MouseMove event procedure resets the picture controls to a white background. Moving the mouse across the pictures will cause each to change color for as long as the mouse is over it.

The three command button procedures are similar. Each procedure disables all the command buttons, causes a text-to-speech (TTS) voice to speak a short phrase, and enables all command buttons when the voice finishes speaking. There is no significance to disabling and enabling the buttons except to show the duration of the speech.

Click the Command1 button to cause the voice to speak synchronously. Moving the mouse over the three picture controls will not cause them to change colors; the MouseMove events are blocked by the synchronous Speak call.

Click the Command2 button to cause the voice to speak asynchronously. The WaitUntilDone call prevents the Command2 procedure from ending before the voice is finished. Moving the mouse over the three picture controls will not cause them to change colors; the MouseMove events are blocked by the WaitUntilDone call.

Click the Command3 button to cause the voice to speak asynchronously. The WaitUntilDone method is called inside a loop which also contains a DoEvents statement. This loop prevents the Command3 procedure from ending before the voice is finished, and also allows MouseMove events to be received by the form. As a result, moving the mouse over the three picture controls causes them to change colors while the voice is speaking.

  Option Explicit

Const INFINITE = -1&                'Tells WaitUntilDone to wait forever

Dim V As SpeechLib.SpVoice

Private Sub Command1_Click()
                                    'Speak synchronously
    Call EnableButtons(False)       'Disable buttons while voice speaks

    V.Speak "Please move the mouse over the picture controls" _
            & " while i speak synchronously."

    Call EnableButtons(True)        'Enable buttons when voice is done

End Sub

Private Sub Command2_Click()
                                    'Speak asynchronously
    Call EnableButtons(False)       'Disable buttons while voice speaks

    V.Speak "Please move the mouse over the picture controls" _
            & " while i speak with a single Wait Until Done", _
            SVSFlagsAsync

    V.WaitUntilDone (INFINITE)
    Call EnableButtons(True)        'Enable buttons when voice is done

End Sub

Private Sub Command3_Click()
                                    'Speak asynchronously

    Call EnableButtons(False)       'Disable buttons while voice speaks

    V.Speak "Please move the mouse over the picture controls" _
            & " while i speak with a smart loop.", _
            SVSFlagsAsync
    Do                              'Smart loop
        DoEvents                    'DoEvents lets events happen
    Loop Until V.WaitUntilDone(10)  'Loop until voice finishes

    Call EnableButtons(True)        'Enable buttons when voice is done

End Sub

Private Sub Form_Load()
    Set V = New SpVoice
    V.Speak "Please move the mouse over the picture controls" _
            & " before clicking the buttons", _
            SVSFlagsAsync
End Sub

Private Sub Form_MouseMove(Button As Integer, Shift As Integer, _
                                                X As Single, Y As Single)
    Picture1.BackColor = vbWhite
    Picture2.BackColor = vbWhite
    Picture3.BackColor = vbWhite
End Sub

Private Sub Picture1_MouseMove(Button As Integer, Shift As Integer, _
                                                X As Single, Y As Single)
    Picture1.BackColor = vbRed
End Sub

Private Sub Picture2_MouseMove(Button As Integer, Shift As Integer, _
                                                X As Single, Y As Single)
    Picture2.BackColor = vbGreen
End Sub

Private Sub Picture3_MouseMove(Button As Integer, Shift As Integer, _
                                                X As Single, Y As Single)
    Picture3.BackColor = vbBlue
End Sub

Private Sub EnableButtons(TrueFalse As Boolean)
    Command1.Enabled = TrueFalse
    Command2.Enabled = TrueFalse
    Command3.Enabled = TrueFalse
End Sub