Visual Basic Language: Events

	Events

Introduction

In a typical application, every class is mostly meant to interact with others, either to request values and methods of the other classes or to provide other classes with some values or a behavior they need. When a class A requests a value or service from another class B, class A is referred to as a client of class B.

This relationship is important not simply because it establishes a relationship between both classes but also because class B should be ready to provide the value or behavior that a client needs at a certain time.

While a class B is asked to provide some values to, or perform some assignment(s) for, another class A, many things would happen. In fact, there is an order that the actions should follow. For example, during the lifetime of a program, that is, while a program is running, a class may be holding a value it can provide to its client but at another time, that value may not be available anymore, for any reason; nothing strange, this is just the ways it happens. Because different things can happen to a class B while a program is running, and because only class B would be aware of these, it must be able to signal to the other classes when there is a change. This is the basis of events: An event is an action that occurs on an object and affects it in a way that its clients must be made aware of.

Event Creation

An event is declared like a pseudo-procedure. To actually declare an event, you use the Event keyword with the following formula:

[modifier] Event Name(Argument)

The modifier can be Public, Private, Protected, or Friend. The Event keyword is required. It is followed by a name for the event. If the event has arguments, enter them in its parentheses.

Here is an example that declares an event:

Module Exercise

    Private Event Evidence()

End Module

Raising an Event

To use an event, the object that causes it must initiate it. When this happens, the object is said to raise the event. To assist you with this, the Visual Basic language provides the RaiseEvent operator. To use it, the formula to follow is:

RaiseEvent EventName(Argument(s))

You start with the RaiseEvent keyword followed by the name of the event you would have declared previously. The name of the event is followed by parentheses. Here is an example:

Module Exercise
    Private Event Evidence()

    Public Function Main() As Integer
        RaiseEvent Evidence()

        Return 0
    End Function

End Module

Events and Delegates

In reality, an event is something that happens to an object in response to a change in behavior. To possible, an event uses a behavior implemented by a delegate. This means that you must first create the delegate. Once the delegate and the event have been declared, you can hook up the delegate to the event. Then when the appropriate action occurs, the event fires. At that time, the procedure that implements the delegate runs.

Before using an event, you must specify the procedure that will carry the event. This procedure is referred to as a handler. To implement this behavior, the event must return a value, and that value must be the delegate that implements the desired behavior. Obviously you must first have created a procedure. Here is an example:

Module Exercise

    Private Sub ShowMessage()
        MsgBox("Get the necessary message")
    End Sub

End Module

To add a handler to the program, you use the AddHandler operator with the following formula:

AddHandler EventName, AddressOf Procedure

The AddHandler and the AddressOf operators are required. The EventName placeholder is used to specify the name of the event that is being dealt with. The Procedure factor is the name of the procedure that will implement the event. Here is an example:

Module Exercise
    Delegate Sub Messenger()
    Private Event Evidence As Messenger

    Private Sub ShowMessage()
        MsgBox("Get the necessary message")
    End Sub

    Public Function Main() As Integer
        AddHandler Evidence, AddressOf ShowMessage

        Return 0
    End Function

End Module

Raising an Event

After adding a handler to the event, it is ready but you must launch its action. To do this, you can use the RaiseEvent operator with the following formula:

RaiseEvent EventName()

The RaiseEvent operator is required. The EventName placeholder is used to specify the name of the event, and it must be followed by parentheses. Here is an example:

Module Exercise
    Delegate Sub Messenger()
    Private Event Evidence As Messenger

    Private Sub ShowMessage()
        MsgBox("Get the necessary message")
    End Sub

    Public Function Main() As Integer
        AddHandler Evidence, AddressOf ShowMessage

        RaiseEvent Evidence()
        Return 0
    End Function

End Module

A Parameterized Event

The event we used in the previous sections did not take any argument. Just like a delegate, an event can take an argument. The primary rule to follow is that both its delegate and the procedure associated with it must take the same type of event. The second rule is that, when raising the event, you must pass an appropriate event to it. Here is an example:

Module Exercise
    Delegate Sub Messenger(ByVal Msg As String)
    Private Event Evidence As Messenger

    Private Sub ShowMessage(ByVal ToShow As String)
        MsgBox(ToShow)
    End Sub

    Public Function Main() As Integer
        AddHandler Evidence, AddressOf ShowMessage

        RaiseEvent Evidence("Is this the last thing to do?")
        Return 0
    End Function

End Module

Just like an event can take an argument, it can also take more than one argument. The primary rules are the same as those for a single parameter. You just have to remember that you are dealing with more than one argument. Here is an example:

Module Exercise
    Delegate Sub Messenger(ByVal Originator As String, ByVal Msg As String)
    Private Event Evidence As Messenger

    Private Sub ShowMessage(ByVal Sender As String, ByVal ToShow As String)
        MsgBox(Sender & ": " & ToShow)
    End Sub

    Public Function Main() As Integer
        AddHandler Evidence, AddressOf ShowMessage

        RaiseEvent Evidence("Message form the Accounting Department", _
                            "Remember to do your time sheet")
        Return 0
    End Function

End Module

Instead of a parameter of a primitive type, you can create an event that takes a class as argument.