SpVoice WaitUntilDone method

Microsoft Speech SDK

Intelligent Interface Technologies Home Page Microsoft Speech SDK

Speech Automation 5.1

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