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
Part |
Description |
||||||
|---|---|---|---|---|---|---|---|
attrlist |
Optional. List of attributes that apply to this event. Multiple attributes are separated by commas. You must enclose the Attribute List in angle brackets ("<" and ">"). |
||||||
accessmodifier |
Optional. Specifies what code can access the event. Can be one of the following:
You can specify Protected Friend to enable access from code in the event's class, a derived class, or the same assembly. |
||||||
Shared |
Optional. Specifies that this event is not associated with a specific instance of a class or structure. |
||||||
Shadows |
Optional. Indicates that this event redeclares and hides an identically named programming element, or set of overloaded elements, in a base class. You can shadow any kind of declared element with any other kind. A shadowed element is unavailable from within the derived class that shadows it, except from where the shadowing element is inaccessible. For example, if a Private element shadows a base-class element, code that does not have permission to access the Private element accesses the base-class element instead. |
||||||
eventname |
Required. Name of the event; follows standard variable naming conventions. |
||||||
parameterlist |
Optional. List of local variables that represent the parameters of this event. You must enclose the Parameter List in parentheses. |
||||||
Implements |
Optional. Indicates that this event implements an event of an interface. |
||||||
implementslist |
Required if Implements is supplied. List of Sub procedures being implemented. Multiple procedures are separated by commas: implementedprocedure [ , implementedprocedure ... ] Each implementedprocedure has the following syntax and parts: interface.definedname
|
||||||
Custom |
Required. Events declared as Custom must define custom AddHandler, RemoveHandler, and RaiseEvent accessors. |
||||||
delegatename |
Optional. The name of a delegate that specifies the event-handler signature. |
||||||
AddHandler |
Required. Declares an AddHandler accessor, which specifies the statements to execute when an event handler is added, either explicitly by using the AddHandler statement or implicitly by using the Handles clause. |
||||||
End AddHandler |
Required. Terminates the AddHandler block. |
||||||
value |
Required. Parameter name. |
||||||
RemoveHandler |
Required. Declares a RemoveHandler accessor, which specifies the statements to execute when an event handler is removed using the RemoveHandler statement. |
||||||
End RemoveHandler |
Required. Terminates the RemoveHandler block. |
||||||
RaiseEvent |
Required. Declares a RaiseEvent accessor, which specifies the statements to execute when the event is raised using the RaiseEvent statement. Typically, this invokes a list of delegates maintained by the AddHandler and RemoveHandler accessors. |
||||||
End RaiseEvent |
Required. Terminates the RaiseEvent block. |
||||||
delegatesignature |
Required. List of parameters that matches the parameters required by the delegatename delegate. You must enclose the Parameter List in parentheses. |
||||||
statements |
Optional. Statements that contain the bodies of the AddHandler, RemoveHandler, and RaiseEvent methods. |
||||||
End Event |
Required. Terminates the Event block. |
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
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
Note
You can declare event arguments just as you do arguments of procedures, with the following exceptions: events cannot have named arguments, ParamArray arguments, or Optional arguments. Events do not have return values.
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.
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 Events That Conserve Memory Use and How to: Declare Events That Avoid Blocking.
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
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(ByVal sender As Object, _
ByVal e As System.EventArgs) _
Handles MyBase.Load
Button1.Text = "Start"
mText = New TimerState
End Sub
Private Sub Button1_Click(ByVal sender As System.Object, _
ByVal e As System.EventArgs) _
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
Private Sub Form1_Load(ByVal sender As Object, _
ByVal e As System.EventArgs) _
Handles MyBase.Load
Button1.Text = "Start"
mText = New TimerState
End Sub
Private Sub Button1_Click(ByVal sender As System.Object, _
ByVal e As System.EventArgs) _
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".
Note
The My.Application.DoEvents method does not process events in the same way the form does. To enable the form to handle the events directly, you can use multithreading. For more information, see Multithreading in Visual Basic.
See Also
Tasks
How to: Declare Events That Conserve Memory Use
How to: Declare Events That Avoid Blocking