Visual Basic Language Reference  

Event Statement

Declares a user-defined event.

[ <attrlist> ] [ Public | Private | Protected | Friend | Protected Friend ] _
[ Shadows ] Event eventname[(arglist)] _
[ Implements interfacename.interfaceeventname ]

Parts

attrlist
Optional. List of attributes that apply to this event. Multiple attributes are separated by commas.
Public
Optional. Entities declared with the Public modifier have public access. There are no restrictions on the use of public entities. Events that do not specify an access modifier are declared as Public by default.
Private
Optional. Entities declared with the Private modifier have private access. A private entity is accessible only within its declaration context, including any nested entities.
Protected
Optional. Entities declared with the Protected keyword have protected access. They are accessible only from within their own class or from a derived class. Protected access can be specified only on members of classes. It is not a superset of friend access.
Friend
Optional. Entities declared with the Friend modifier have friend access. An entity with friend access is accessible only within the program that contains the entity declaration.
Protected Friend
Optional. Entities declared with the Protected Friend modifiers have the union of protected and friend accessibility.
Shadows
Optional. Indicates that this event shadows an identically named programming element in a base class. You can shadow any kind of declared element with any other kind. A shadowed element is unavailable in the derived class that shadows it
eventname
Required. Name of the event; follows standard variable naming conventions.
Implements
Optional. Indicates that this event implements an event of an interface.
interfacename
The name of an interface.
interfaceeventname
The name of the event being implemented.

Each attribute in the attrlist part has the following syntax and parts:

attrname [({ attrargs | attrinit })]

attrlist Parts

attrname
Required. Name of the attribute. Must be a valid Visual Basic identifier.
attrargs
Optional. List of positional arguments for this attribute. Multiple arguments are separated by commas.
attrinit
Optional. List of field or property initializers for this attribute. Multiple initializers are separated by commas.

The arglist argument has the following syntax and parts:

[ <attrlist> ] [ ByVal | ByRef ] varname[ ( ) ] [ As type ]

arglist Parts

attrlist
Optional. List of attributes that apply to this argument. Multiple attributes are separated by commas.
ByVal
Optional. Indicates that the argument is passed by value. ByVal is the default in Visual Basic.
ByRef
Optional. Indicates that the argument is passed by reference.
varname
Required. Name of the variable representing the argument being passed to the procedure; follows standard variable naming conventions.
type
Optional. Data type of the argument passed to the procedure; may be Byte, Boolean, Char, Short, Integer, Long, Single, Double, Decimal, Date, String (variable length only), Object, a user-defined type, or an object type.

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
Note   You can declare event arguments just as you do arguments of procedures, with the following exceptions: events cannot have named arguments, or Optional arguments. Events do not have return values.

Example

The following example uses events to count off seconds during a demonstration of the fastest 100 meter race. The code illustrates all of the event-related methods, properties, and statements, including 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 (Command1), a label (Label1), and two text boxes (Text1 and Text2). When you click the button, the first text box displays "From Now" and the second starts to count seconds. When the full time (9.84 seconds) has elapsed, the first text box displays "Until Now" and the second displays "9.84"

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, add a button named Button1, a label named Label1 and two text boxes, named TextBox1 and TextBox2, to the main form, named form1. Then right click the form and click View Code to open the code editor.

To simplify access to the Timer property, add an Imports statement as the first line of code above the Class Form1 statement.

Imports Microsoft.VisualBasic.DateAndTime

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(ByVal sender As Object, _
                       ByVal e As System.EventArgs) _
                       Handles MyBase.Load
   Button1.Text = "Click to Start Timer"
   TextBox1.Text = ""
   TextBox2.Text = ""
   Label1.Text = "The fastest 100 meters ever run took this long:"
   mText = New TimerState()
End Sub
Private Sub Button1_Click(ByVal sender As System.Object, _
                          ByVal e As System.EventArgs) _
                          Handles Button1.Click
   TextBox1.Text = "From Now"
   TextBox1.Refresh()
   TextBox2.Text = "0"
   TextBox2.Refresh()
   mText.TimerTask(9.84)
End Sub

Private Sub mText_ChangeText() Handles mText.ChangeText
   TextBox1.Text = "Until Now"
   TextBox2.Text = "9.84"
End Sub

Private Sub mText_UpdateTime(ByVal Jump As Double) _
      Handles mText.UpdateTime
   TextBox2.Text = Format(Jump, "##0.00")
   Application.DoEvents()
End Sub

Class TimerState
   Public Event UpdateTime(ByVal Jump As Double)
   Public Event ChangeText()
   Public Sub TimerTask(ByVal Duration As Double)
      Dim Start As Double
      Dim Second As Double
      Dim SoFar As Double
      Start = Timer
      SoFar = Start
      Do While Timer < Start + Duration
         If Timer - SoFar >= 0.1 Then
            SoFar = SoFar + 0.1
            RaiseEvent UpdateTime(Timer - Start)
         End If
      Loop
      RaiseEvent ChangeText()
   End Sub
End Class

Press F5 To run this example, and click the button labeled Click to start timer. The first text box displays "From Now" and the second starts to count seconds. When the full time (9.84 seconds) has elapsed, the first text box displays "Until Now" and the second displays "9.84".

See Also

RaiseEvent Statement | Implements Statement | Adding Events to a Class | Events and Delegates