Visual Basic Concepts

Using DoEvents

See Also

Although Timer events are the best tool for background processing, particularly for very long tasks, the DoEvents function provides a convenient way to allow a task to be canceled. For example, the following code shows a "Process" button that changes to a "Cancel" button when it is clicked. Clicking it again interrupts the task it is performing.

' The original caption for this button is "Process".
Private Sub Command1_Click()
   ' Static variables are shared by all instances 
   ' of a procedure.
   Static blnProcessing As Boolean
   Dim lngCt As Long
   Dim intYieldCt As Integer
   Dim dblDummy As Double
   ' When the button is clicked, test whether it's 
    'already processing.
   If blnProcessing Then
      ' If processing is in progress, cancel it.
      blnProcessing = False
   Else
      Command1.Caption = "Cancel"
      blnProcessing = True
      lngCt = 0
      ' Perform a million floating-point 
      ' multiplications. After every
      ' thousand, check for cancellation.
      Do While blnProcessing And (lngCt < 1000000)
         For intYieldCt = 1 To 1000
            lngCt = lngCt + 1
            dblDummy = lngCt * 3.14159
         Next intYieldCt
         ' The DoEvents statement allows other 
         ' events to occur, including pressing this 
         ' button a second time.
         DoEvents
      Loop
      blnProcessing = False
      Command1.Caption = "Process"
      MsgBox lngCt & " multiplications were performed"
   End If
End Sub

DoEvents switches control to the operating-environment kernel. Control returns to your application as soon as all other applications in the environment have had a chance to respond to pending events. This doesn't cause the current application to give up the focus, but it does enable background events to be processed.

The results of this yielding may not always be what you expect. For example, the following Click-event code waits until ten seconds after the button was clicked and then displays a message. If the button is clicked while it is already waiting, the clicks will be finished in reverse order.

Private Sub Command2_Click()
   Static intClick As Integer
   Dim intClickNumber As Integer
   Dim dblEndTime As Double
      ' Each time the button is clicked, 
      ' give it a unique number.
   intClick = intClick + 1
   intClickNumber = intClick
      ' Wait for ten seconds.
   dblEndTime = Timer + 10#
   Do While dblEndTime > Timer
      ' Do nothing but allow other 
      ' applications to process
      ' their events.
      DoEvents
   Loop
   MsgBox "Click " & intClickNumber & " is finished"
End Sub

You may want to prevent an event procedure that gives up control with DoEvents from being called again before DoEvents returns. Otherwise, the procedure might end up being called endlessly, until system resources are exhausted. You can prevent this from happening either by temporarily disabling the control or by setting a static "flag" variable, as in the earlier example.

Avoiding DoEvents When Using Global Data

It may be perfectly safe for a function to be called again while it has yielded control with DoEvents. For example, this procedure tests for prime numbers and uses DoEvents to periodically enable other applications to process events:

Function PrimeStatus (TestVal As Long) As Integer
   Dim Lim As Integer
   PrimeStatus = True
   Lim = Sqr(TestVal)
   For I = 2 To Lim
      If TestVal Mod I = 0 Then
         PrimeStatus = False
         Exit For
      End If
      If I Mod 200 = 0 Then DoEvents
   Next I
End Function

This code calls the DoEvents statement once every 200 iterations. This allows the PrimeStatus procedure to continue calculations as long as needed while the rest of the environment responds to events.

Consider what happens during a DoEvents call. Execution of application code is suspended while other forms and applications process events. One of these events might be a button click that launches the PrimeStatus procedure again.

This causes PrimeStatus to be re-entered, but since each occurrence of the function has space on the stack for its parameters and local variables, there is no conflict. Of course, if PrimeStatus gets called too many times, an Out of Stack Space error could occur.

The situation would be very different if PrimeStatus used or changed module-level variables or global data. In that case, executing another instance of PrimeStatus before DoEvents could return might result in the values of the module data or global data being different than they were before DoEvents was called. The results of PrimeStatus would then be unpredictable.

For More Information   See "DoEvents Function" and "Refresh Method" in the Language Reference.