Mike asked me what event properties are, but before I can really talk about them, you need to understand how events work in VB and .NET. Rather than write up a whole new, long entry, I think I’m just going to reprint an email that I sent to the dotnet@discuss.develop.com alias nearly four years ago. (Wow, has it really been that long?) Then tomorrow or so, I’ll talk about what we’re doing new in VB 2005. So, the following is what I wrote, with some minor clarifications and corrections:
Since the method of doing events is different in .NET than it is in COM2, I wrote up an internal memo about how events work and specifically how they work in VB (since VB has a few extra shortcuts that languages like C# don’t). I though I would forward it along if anyone is interested. This presupposes a little knowledge of .NET and VB, but not much. This is also very VB-specific. Details may be different for other languages such as C#, but keep in mind that events in all .NET languages are built on the same foundation and are totally interoperable.
Step 1: Delegates
The foundation of events in the .NET Framework is delegates, which can be thought of as type-safe function pointers. A delegate is defined by a subroutine or function signature. Using the AddressOf operator, you can capture the address of a subroutine or function that matches that signature in a variable whose type is the delegate type. Once you’ve captured the address of a method in a delegate, you can pass the delegate around as you can any object. You can also use a delegate variable as if it was a subroutine or function to invoke the method pointed at by the delegate. For example:
Delegate Function D1(ByVal intvar As Integer) As Integer
Module M1
Function F1(ByVal intvar As Integer) As Integer
F1 = intvar
End Function
Sub Main()
Dim d As D1 = AddressOf F1
Dim intval As Integer = d(10)
Console.WriteLine(intval) ' Will print out "10"
End Sub
End Module
Delegates have two special properties. First, delegates allow you to take the address not only of shared methods but also of instance methods. In the case of an instance function, both the function address and object instance are stored, allowing for correct invocation of virtual functions. The second special property is that delegates are combinable. When you combine two delegates (which must be of the same delegate type), invoking the resulting delegate will call both delegates in order of combination. This is necessary for events to work, as we’ll see below. Combining delegates that have return types is possible, but the return value of the delegate invocation will be the return value of the last function invoked.
Interoperation Note: VB allows syntactic shortcuts when creating delegates. From the .NET perspective, creating a delegate involves invoking a constructor on the delegate class that takes an object instance (possibly Nothing for shared methods) and the address of a method. So in C#, creating a delegate looks something like “new deltype(objvar, method)”. This syntax is usable in VB, except we require that taking the address of a method be done explicitly and don’t require the object instance (inferring it instead from the reference to the method) – i.e. “new deltype(AddressOf objvar.method)”. In most cases, however, you can just say “AddressOf objvar.method” and VB will infer what delegate type to instantiate based on the target type of the expression. In the case where the target type is ambiguous – “Dim o As Object : o = AddressOf method” – a compile-time error will be given. [Ed note: I believe C# is adding this feature in C# 2005, but I could be wrong about that.]
Step 2: Events (.NET style)
Once we have delegates, events become possible. An event raised by a class is defined by three things: a delegate type, an add listener method and a remove listener method. The delegate type defines the signature of the event handler – in other words, the delegates define the arguments that will be passed to a method that gets called when the event occurs. The add and remove listener methods allow other objects to start and stop listening to the event. The add listener method takes a parameter of the event delegate type and combines it with any other delegates that may be listening to the event. The remove listener method takes a parameter of the event delegate type and removes it from the list of delegates listening to the event. When the object wants to fire the event, it just invokes the delegate. For example:
Class EventRaiser
' The event delegate
Public Delegate Sub ClickEventHandler(ByVal x As Integer, ByVal y As Integer)
' The list of objects listening to the event
Private ClickEventHandlers As ClickEventHandler
' The add and remove methods
Public Sub add_Click(ByVal handler As ClickEventHandler)
System.Delegate.Combine(ClickEventHandlers, handler)
End Sub
Public Sub remove_Click(ByVal handler As ClickEventHandler)
System.Delegate.Remove(ClickEventHandlers, handler)
End Sub
' Some method that fires the event
Public Sub OnClick(ByVal x As Integer, ByVal y As Integer)
ClickEventHandlers(x, y)
End Sub
End Class
Class EventListener
Public e As EventRaiser
Private Sub HandleClick(ByVal x As Integer, ByVal y As Integer)
...
End Sub
Sub New()
e = New EventRaiser
' Hook up to the event
e.add_Click(AddressOf Me.HandleClick)
End Sub
End Class
Step 3: Defining Events (VB.NET style)
The above example, although it shows how events work, does not actually define an event in VB. Events are defined by specific metadata and not just a design pattern. To define an event in VB, there are two syntaxes you can use:
Event Click(ByVal x As Integer, ByVal y As Integer)
This event syntax does the most for you. It implicitly defines all of the code you see in EventRaiser except for the method that raises the event.
Event Click As ClickHandlerDelegate
This event syntax allows you to reuse an existing delegate type as the type of the event. This is useful if you have a number of events that all take the same set of parameters. This still defines the field, the add method and the remove method.
VB does not have a syntax for defining events that allows you to specify the field, the add method or the remove method. Those are always implicitly generated. [Ed note: For those of you who are thinking ahead, this is what we’re changing in VB 2005.]
Step 4: Handling Events (VB style)
Although it is legal to call the add handler method when you want to handle an event raised by an object, as in the example above, VB provides a cleaner syntax to do so. The AddHandler and RemoveHandler statements will take care of calling the add and remove methods with the proper values. For example:
Class EventListener
Public e As EventRaiser
Private Sub HandleClick(ByVal x As Integer, ByVal y As Integer)
...
End Sub
Sub New()
e = New EventRaiser
' Hook up to the event.
AddHandler e.Click, AddressOf Me.HandleClick
End Sub
End Class
In other languages, this is the extent of their support for handling events – the developer has to explicitly hook up to and unhook from events. VB provides another way to hook up to events – declarative event handling – that is in many ways more convenient.
Declaratively handling events is a two step process in VB. First, the object that is going to rais
e the events must be stored in a field with the WithEvents modifier, which indicates the field’s availability for declarative event hookup. Then, methods can state that they handle a particular event raised by the field by specifying a Handles clause and giving the field and event handled. For example:
Class EventListener
Public WithEvents e As EventRaiser
Private Sub HandleClick(ByVal x As Integer, ByVal y As Integer) Handles e.Click
...
End Sub
Sub New()
e = New EventRaiser
End Sub
End Class
It is important to step back for a moment and discuss what happens behind the scenes with the above syntax. When a field is declared as a WithEvents field, the field is changed into a property at compile time. This allows the event hookup to be performed whenever the field is assigned to. The Get part of the property just returns the value of the field. The Set property first unhooks any declarative event handlers from the current instance in the field (if any), assigns to the field, and then re-hooks up any declarative event handlers to the new instance. This is what the above code is transformed to under the covers:
Class EventListener
Private _e As EventRaiser
Public Property e As EventRaiser
Get
Return _e
End Get
Set
If Not _e Is Nothing Then
RemoveHandler _e.Click, AddressOf Me.HandleClick
End If
_e = Value
If Not _e Is Nothing Then
AddHandler _e.Click, AddressOf Me.HandleClick
End If
End Set
End Property
Private Sub HandleClick(ByVal x As Integer, ByVal y As Integer)
...
End Sub
Sub New()
e = New EventRaiser
End Sub
End Class
Note that while declarative event hookup can be very convenient, it does have limitations. First, you can’t declaratively handle events raised by objects not stored in a WithEvents field. Second, you can’t declaratively handle shared events, since they are not tied to an instance that can be assigned to a WithEvents field. And third, you can’t control when the event is hooked up to or unhooked from. For all of those cases, you must use dynamic event handling.
