Event Statement

Declares a user-defined event.

[ <attrlist> ] [ accessmodifier ] _
[ Shared ] [ Shadows ] Event eventname[(parameterlist)] _
[ Implements implementslist ]
' -or-
[ <attrlist> ] [ accessmodifier ] _
[ Shared ] [ Shadows ] Event eventname As delegatename _
[ Implements implementslist ]
' -or-
 [ <attrlist> ] [ accessmodifier ] _
[ Shared ] [ Shadows ] Custom Event eventname As delegatename _
[ Implements implementslist ]
   [ <attrlist> ] AddHandler(ByVal value As delegatename)
      [ statements ]
   End AddHandler
   [ <attrlist> ] RemoveHandler(ByVal value As delegatename)
      [ statements ]
   End RemoveHandler
   [ <attrlist> ] RaiseEvent(delegatesignature)
      [ statements ]
   End RaiseEvent
End Event

Parts

Remarks

Once the event has been declared, use the RaiseEvent statement to raise the event. A typical event might be declared and raised as shown in the following fragments:

Public Class EventSource
    ' Declare an event. 
    Public Event LogonCompleted(ByVal UserName As String)
    Sub CauseEvent()
        ' Raise an event on successful logon. 
        RaiseEvent LogonCompleted("AustinSteele")
    End Sub 
End Class

To handle an event, you must associate it with an event handler subroutine using either the Handles or AddHandler statement. The signatures of the subroutine and the event must match. To handle a shared event, you must use the AddHandler statement.

You can use Event only at module level. This means the declaration context for an event must be a class, structure, module, or interface, and cannot be a source file, namespace, procedure, or block. For more information, see Declaration Contexts and Default Access Levels (Visual Basic).

In most circumstances, you can use the first syntax in the Syntax section of this topic for declaring events. However, some scenarios require that you have more control over the detailed behavior of the event. The last syntax in the Syntax section of this topic, which uses the Custom keyword, provides that control by enabling you to define custom events. In a custom event, you specify exactly what occurs when code adds or removes an event handler to or from the event, or when code raises the event. For examples, see How to: Declare Custom Events To Conserve Memory (Visual Basic) and How to: Declare Custom Events To Avoid Blocking (Visual Basic).

Example

The following example uses events to count down seconds from 10 to 0. The code illustrates several of the event-related methods, properties, and statements. This includes the RaiseEvent statement.

The class that raises an event is the event source, and the methods that process the event are the event handlers. An event source can have multiple handlers for the events it generates. When the class raises the event, that event is raised on every class that has elected to handle events for that instance of the object.

The example also uses a form (Form1) with a button (Button1) and a text box (TextBox1). When you click the button, the first text box displays a countdown from 10 to 0 seconds. When the full time (10 seconds) has elapsed, the first text box displays "Done".

The code for Form1 specifies the initial and terminal states of the form. It also contains the code executed when events are raised.

To use this example, open a new Windows Forms project. Then add a button named Button1 and a text box named TextBox1 to the main form, named Form1. Then right-click the form and click View Code to open the code editor.

Add a WithEvents variable to the declarations section of the Form1 class:

Private WithEvents mText As TimerState

Add the following code to the code for Form1. Replace any duplicate procedures that may exist, such as Form_Load or Button_Click.

Private Sub Form1_Load() Handles MyBase.Load
    Button1.Text = "Start"
    mText = New TimerState
End Sub 
Private Sub Button1_Click() Handles Button1.Click
    mText.StartCountdown(10.0, 0.1)
End Sub 

Private Sub mText_ChangeText() Handles mText.Finished
    TextBox1.Text = "Done" 
End Sub 

Private Sub mText_UpdateTime(ByVal Countdown As Double
  ) Handles mText.UpdateTime

    TextBox1.Text = Format(Countdown, "##0.0")
    ' Use DoEvents to allow the display to refresh.
    My.Application.DoEvents()
End Sub 

Class TimerState
    Public Event UpdateTime(ByVal Countdown As Double)
    Public Event Finished()
    Public Sub StartCountdown(ByVal Duration As Double, 
                              ByVal Increment As Double)
        Dim Start As Double = DateAndTime.Timer
        Dim ElapsedTime As Double = 0

        Dim SoFar As Double = 0
        Do While ElapsedTime < Duration
            If ElapsedTime > SoFar + Increment Then
                SoFar += Increment
                RaiseEvent UpdateTime(Duration - SoFar)
            End If
            ElapsedTime = DateAndTime.Timer - Start
        Loop 
        RaiseEvent Finished()
    End Sub 
End Class

Press F5 to run the previous example, and click the button labeled Start. The first text box starts to count down the seconds. When the full time (10 seconds) has elapsed, the first text box displays "Done".

See Also

Tasks

How to: Declare Custom Events To Conserve Memory (Visual Basic)

How to: Declare Custom Events To Avoid Blocking (Visual Basic)

Reference

RaiseEvent Statement

Implements Statement

AddHandler Statement

RemoveHandler Statement

Handles Clause (Visual Basic)

Delegate Statement

Shared (Visual Basic)

Shadows (Visual Basic)

Other Resources

Events (Visual Basic)