DoEvents Function

Yields execution so that the operating system can process other events and messages.

Syntax

DoEvents()

Parameters

None.

Return Value

Returns an Integer representing the number of open forms in stand-alone versions of Visual Basic. Returns 0 in all other applications.

Remarks

The DoEvents function temporarily yields execution to the operating system, allowing it to process other events such as user input, timers, and system messages. This is essential for keeping an application responsive during long-running operations. Important Characteristics: - Yields control to the operating system - Allows message queue processing - Prevents UI from appearing frozen during long operations - Can cause reentrancy issues if not used carefully - Slows down operations slightly due to context switching - Returns number of open forms (VB6 stand-alone only) - In most contexts, return value is ignored - Does not create a new thread or async operation - Processes Windows messages in the queue - Can trigger event handlers and user interactions

When to Use DoEvents

• Long-running loops that process data
• File operations on large files
• Network operations that may take time
• Batch processing operations
• Any operation that could make UI unresponsive

When NOT to Use DoEvents

• In event handlers that could be re-entered
• When reentrancy could cause data corruption
• In critical sections or transaction code
• When better alternatives exist (timers, threading)

Examples

Basic Usage

' Process large dataset while keeping UI responsive
Dim i As Long
For i = 1 To 100000
    ProcessRecord i
    ' Yield every 100 iterations
    If i Mod 100 = 0 Then
        DoEvents
    End If
Next i
' Simple DoEvents call
DoEvents
' Check return value (rarely used)
Dim formCount As Integer
formCount = DoEvents()

Progress Bar Update

Sub ProcessWithProgress()
    Dim i As Long
    Dim total As Long
    total = 10000
    ProgressBar1.Min = 0
    ProgressBar1.Max = total
    For i = 1 To total
        ProcessItem i
        ' Update progress bar
        ProgressBar1.Value = i
        lblStatus.Caption = "Processing " & i & " of " & total
        ' Allow UI to refresh
        DoEvents
    Next i
    MsgBox "Processing complete!"
End Sub

File Processing

Sub ProcessLargeFile(filePath As String)
    Dim fileNum As Integer
    Dim line As String
    Dim lineCount As Long
    fileNum = FreeFile
    Open filePath For Input As #fileNum
    lineCount = 0
    Do Until EOF(fileNum)
        Line Input #fileNum, line
        ProcessLine line
        lineCount = lineCount + 1
        ' Yield every 100 lines
        If lineCount Mod 100 = 0 Then
            DoEvents
        End If
    Loop
    Close #fileNum
End Sub

Common Patterns

Cancellable Long Operation

Private cancelOperation As Boolean
Sub PerformCancellableOperation()
    Dim i As Long
    cancelOperation = False
    cmdCancel.Enabled = True
    For i = 1 To 100000
        If cancelOperation Then
            MsgBox "Operation cancelled"
            Exit For
        End If
        ProcessItem i
        If i Mod 100 = 0 Then
            DoEvents  ' Allows cancel button to be clicked
        End If
    Next i
    cmdCancel.Enabled = False
End Sub
Private Sub cmdCancel_Click()
    cancelOperation = True
End Sub

Batch Import with Status

Sub ImportRecords(records As Variant)
    Dim i As Long
    Dim startTime As Double
    startTime = Timer
    For i = LBound(records) To UBound(records)
        ImportRecord records(i)
        ' Update status every 50 records
        If i Mod 50 = 0 Then
            lblStatus.Caption = "Imported " & i & " records..."
            DoEvents
        End If
    Next i
    lblStatus.Caption = "Import complete: " & UBound(records) - LBound(records) + 1 & _
                        " records in " & Format(Timer - startTime, "0.00") & " seconds"
End Sub

Prevent UI Freeze During Calculation

Function CalculateComplexResult(data As Variant) As Double
    Dim i As Long
    Dim result As Double
    Dim iterations As Long
    iterations = 0
    result = 0
    For i = LBound(data) To UBound(data)
        result = result + PerformComplexCalculation(data(i))
        iterations = iterations + 1
        ' Yield periodically
        If iterations Mod 500 = 0 Then
            DoEvents
        End If
    Next i
    CalculateComplexResult = result
End Function

Database Batch Update

Sub UpdateRecordsBatch(rs As ADODB.Recordset)
    Dim count As Long
    count = 0
    Do Until rs.EOF
        rs("Status") = "Processed"
        rs("ProcessDate") = Date
        rs.Update
        count = count + 1
        If count Mod 25 = 0 Then
            lblProgress.Caption = count & " records updated"
            DoEvents
        End If
        rs.MoveNext
    Loop
End Sub

Search Operation with Live Results

Sub SearchFiles(rootPath As String, searchTerm As String)
    Dim fileName As String
    Dim matchCount As Long
    matchCount = 0
    lstResults.Clear
    fileName = Dir(rootPath & "\*.*")
    Do While fileName <> ""
        If InStr(1, fileName, searchTerm, vbTextCompare) > 0 Then
            lstResults.AddItem fileName
            matchCount = matchCount + 1
        End If
        fileName = Dir
        DoEvents  ' Keep UI responsive, allow viewing results
    Loop
    lblStatus.Caption = matchCount & " matches found"
End Sub

Report Generation

Sub GenerateReport(data As Collection)
    Dim item As Variant
    Dim lineNum As Long
    lineNum = 0
    For Each item In data
        WriteReportLine item
        lineNum = lineNum + 1
        If lineNum Mod 20 = 0 Then
            lblProgress.Caption = "Generated " & lineNum & " lines..."
            DoEvents
        End If
    Next item
End Sub

Animation or Visual Feedback

Sub ShowProcessingAnimation()
    Dim i As Integer
    For i = 1 To 100
        ' Update visual indicator
        shpIndicator.Left = i * 50
        DoEvents
        ' Simulate work
        Sleep 10
    Next i
End Sub

Multi-Step Process

Sub MultiStepProcess()
    lblStatus.Caption = "Step 1: Loading data..."
    DoEvents
    LoadData
    lblStatus.Caption = "Step 2: Processing data..."
    DoEvents
    ProcessData
    lblStatus.Caption = "Step 3: Saving results..."
    DoEvents
    SaveResults
    lblStatus.Caption = "Complete!"
    DoEvents
End Sub

Advanced Usage

Prevent Reentrancy

Private isProcessing As Boolean
Sub SafeProcessWithDoEvents()
    ' Prevent re-entry
    If isProcessing Then
        MsgBox "Already processing"
        Exit Sub
    End If
    isProcessing = True
    Dim i As Long
    For i = 1 To 10000
        ProcessItem i
        If i Mod 100 = 0 Then
            DoEvents
        End If
    Next i
    isProcessing = False
End Sub

Throttled DoEvents

Sub ProcessWithThrottledDoEvents()
    Dim i As Long
    Dim lastDoEvents As Double
    Dim doEventsInterval As Double
    doEventsInterval = 0.1  ' 100ms
    lastDoEvents = Timer
    For i = 1 To 100000
        ProcessItem i
        ' DoEvents based on time, not iteration count
        If Timer - lastDoEvents > doEventsInterval Then
            DoEvents
            lastDoEvents = Timer
        End If
    Next i
End Sub

Disable Controls During Processing

Sub ProcessWithDisabledControls()
    ' Disable controls to prevent reentrancy
    DisableControls
    Dim i As Long
    For i = 1 To 10000
        ProcessItem i
        If i Mod 100 = 0 Then
            UpdateProgress i
            DoEvents  ' Safe because controls are disabled
        End If
    Next i
    EnableControls
End Sub
Sub DisableControls()
    Dim ctrl As Control
    For Each ctrl In Me.Controls
        If TypeOf ctrl Is CommandButton Then
            ctrl.Enabled = False
        End If
    Next ctrl
End Sub
Sub EnableControls()
    Dim ctrl As Control
    For Each ctrl In Me.Controls
        If TypeOf ctrl Is CommandButton Then
            ctrl.Enabled = True
        End If
    Next ctrl
End Sub

Background Processing Simulation

' Simulates background processing using DoEvents
Private processingComplete As Boolean
Sub StartBackgroundTask()
    processingComplete = False
    ' Start the "background" task
    ProcessInBackground
    ' Show modal dialog that waits
    Do Until processingComplete
        DoEvents
        Sleep 10  ' Small delay to reduce CPU usage
    Loop
    MsgBox "Background task complete"
End Sub
Sub ProcessInBackground()
    Dim i As Long
    For i = 1 To 10000
        ProcessItem i
        If i Mod 100 = 0 Then
            DoEvents
        End If
    Next i
    processingComplete = True
End Sub

Smart DoEvents with CPU Management

Sub ProcessWithCPUManagement()
    Dim i As Long
    Dim processingTime As Double
    Dim doEventsTime As Double
    For i = 1 To 100000
        processingTime = Timer
        ProcessItem i
        processingTime = Timer - processingTime
        ' DoEvents if processing takes significant time
        If processingTime > 0.05 Then  ' More than 50ms
            doEventsTime = Timer
            DoEvents
            doEventsTime = Timer - doEventsTime
            ' Adjust strategy if DoEvents takes too long
            If doEventsTime > processingTime * 0.1 Then
                ' DoEvents overhead is too high, reduce frequency
                ' (implementation-specific logic here)
            End If
        End If
    Next i
End Sub

Export with User Interaction

Sub ExportDataWithOptions()
    Dim i As Long
    Dim exportCount As Long
    exportCount = 0
    For i = 1 To RecordCount
        If chkIncludeDeleted.Value = vbChecked Or Not IsDeleted(i) Then
            ExportRecord i
            exportCount = exportCount + 1
        End If
        ' Update UI and allow user to change options
        If i Mod 50 = 0 Then
            lblProgress.Caption = exportCount & " records exported"
            DoEvents
            ' User can check/uncheck options, affecting subsequent exports
        End If
    Next i
End Sub

Error Handling

Sub ProcessWithErrorHandling()
    On Error GoTo ErrorHandler
    Dim i As Long
    For i = 1 To 10000
        ProcessItem i
        If i Mod 100 = 0 Then
            DoEvents
        End If
    Next i
    Exit Sub
ErrorHandler:
    ' DoEvents can trigger errors if event handlers fail
    MsgBox "Error during processing: " & Err.Description
    Resume Next
End Sub

Common Errors

• Error 11 (Division by zero): Can occur if DoEvents allows user to clear data
• Error 91 (Object variable not set): If DoEvents allows object to be destroyed
• Reentrancy errors: If DoEvents allows same code to be called recursively

Performance Considerations

• DoEvents has overhead (context switching, message processing)
• Call too frequently: significant performance impact
• Call too infrequently: UI appears frozen
• Typical guideline: every 50-100 iterations or every 100ms
• For very fast loops, use time-based checking instead of iteration-based
• Consider alternatives for truly asynchronous operations
• Sleep() between DoEvents can reduce CPU usage in wait loops

Best Practices

Call Periodically, Not Every Iteration

' Good - DoEvents every 100 iterations
For i = 1 To 100000
    ProcessItem i
    If i Mod 100 = 0 Then DoEvents
Next i
' Bad - DoEvents every iteration (slow)
For i = 1 To 100000
    ProcessItem i
    DoEvents  ' Too frequent!
Next i

Protect Against Reentrancy

' Good - Use flag to prevent reentrancy
Private isProcessing As Boolean
Sub Process()
    If isProcessing Then Exit Sub
    isProcessing = True
    ' ... processing with DoEvents ...
    isProcessing = False
End Sub
' Bad - No protection
Sub Process()
    ' ... processing with DoEvents ...
    ' Can be called again through DoEvents
End Sub

Disable User Input When Needed

' Good - Disable controls that could cause problems
cmdProcess.Enabled = False
For i = 1 To 10000
    ProcessItem i
    If i Mod 100 = 0 Then DoEvents
Next i
cmdProcess.Enabled = True

Consider Alternatives

' For very long operations, consider:
' 1. Timer control for asynchronous processing
' 2. Threading (in modern applications)
' 3. Breaking into smaller chunks with callbacks
' 4. Progress forms with asynchronous updates

Comparison with Other Approaches

DoEvents vs Timer Control

' DoEvents - Synchronous, blocks until complete
For i = 1 To 10000
    ProcessItem i
    If i Mod 100 = 0 Then DoEvents
Next i
' Timer - Asynchronous, processes in chunks
Private currentIndex As Long
Private Sub Timer1_Timer()
    Dim i As Long
    For i = currentIndex To currentIndex + 99
        If i > 10000 Then
            Timer1.Enabled = False
            Exit Sub
        End If
        ProcessItem i
    Next i
    currentIndex = i
End Sub

DoEvents vs Application.Wait (Excel VBA)

' DoEvents - Yields immediately
DoEvents
' Application.Wait - Yields for specific duration
Application.Wait Now + TimeValue("00:00:01")

Limitations

• Does not create true multithreading
• Can cause reentrancy issues
• Performance overhead from context switching
• Return value rarely useful in modern applications
• No control over which events are processed
• Can make debugging more difficult
• Not available in all VBA hosts (e.g., some Office apps)
• Cannot cancel or prioritize specific events

Related Functions

• Sleep: Pauses execution for specified milliseconds (Windows API)
• Timer: Returns seconds since midnight (for timing operations)
• Now: Returns current date and time
• Wait: Application-specific wait method (Excel VBA)
• Timer Control: Asynchronous event-based processing
• Threading APIs: True multithreading (advanced)