Visual Basic Concepts
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.
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.