Creating Events

You can design and support your own events using OOP in Visual Basic, using the Event statement:

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

Here are the parts of this statement:

attrlist—Optional. List of attributes that apply to this event. Separate multiple attributes by commas.
Public—Optional. Events declared Public have public access, which means there are no restrictions on their use.
Private—Optional. Events declared Private have private access, which means they are accessible only within their declaration context.
Protected—Optional. Events declared Protected have protected access, which means they are accessible only from within their own class or from a derived class.
Friend—Optional. Events declared Friend have friend access, which means they are accessible only within the program that contains the its declaration.
Protected Friend—Optional. Events declared Protected Friend have both protected and friend accessibility.
Shadows—Optional. Indicates that this event shadows an identically named programming element in a base class.
eventname—Required. Name of the event.
interfacename—The name of an interface.
interfaceeventname—The name of the event being implemented.

Each attribute in the attrlist part has the following syntax:

<attrname [({ attrargs | attrinit })]> Attrlist

Here are the parts of attrlist:

attrname—Required. Name of the attribute.
attrargs—Optional. List of arguments for this attribute. Separate multiple arguments by commas.
attrinit—Optional. List of field or property initializers for this attribute. Separate multiple initializers by commas.

The arglist argument has the following syntax:

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

Here are the parts of arglist:

attrlist—Optional. List of attributes for this argument. Separate multiple attributes by commas.
ByVal—Optional. Specifies that the argument is passed by value. (ByVal is the default.)
ByRef—Optional. Specifies that the argument is passed by reference.
varname—Required. Name of the variable representing the argument being passed to the procedure.
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.

Let's see an example; this one is named Events on the CD-ROM. In this case, I'll create a custom event that occurs when you click a button three times, called ThreeClick. To keep track of how many times the button has been clicked, I'll use an object called tracker, of a class I'll call ClickTrack:

    Public Class ClickTrack
        ⋮
    End Class

To implement the ThreeClick event, I use the Event statement, indicating that the event handler for this event should be passed one argument, a string holding a message (which will just indicate that the event occurred):

    Public Class ClickTrack
        Public Event ThreeClick(ByVal Message As String)
        ⋮
    End Class

How can we make this event actually occur? You just use the RaiseEvent method. In this case, you must pass RaiseEvent a message you want to associate with this event (if you had given ThreeClick two arguments, you'd have to pass RaiseEvent two arguments, and so on). I can keep track of the number of button clicks with a Sub procedure named Click and raise the ThreeClick event when three clicks have occurred, passing that event's handler the string "You clicked three times":

    Public Class ClickTrack
        Public Event ThreeClick(ByVal Message As String)
        Public Sub Click()
            Static ClickCount As Integer = 0
            ClickCount += 1
            If ClickCount >= 3 Then
                ClickCount = 0
                RaiseEvent ThreeClick("You clicked three times")
            End If
        End Sub
    End Class

That's how you make a custom event occur—with RaiseEvent. I'll need an object of this new ClickTrack class, and I'll call that object tracker. Note that I declare it using the keyword WithEvents to indicate this new object can handle events:

Dim WithEvents tracker As New ClickTrack()

Now that we've created a new event, you also can write an event handler for it, just make sure you accept the right number of type of arguments and use a Handles clause to indicate what event you're handling (which is tracker.ThreeClick in this case); when the event occurs, I'll display the message we've associated with the event in a text box:

    Private Sub tracker_ThreeClick(ByVal Message As String) Handles _
        tracker.ThreeClick
        TextBox1.Text = Message
    End Sub

All that's left is to keep calling the tracker object'sClick method until the ThreeClick event occurs, and I can do that with a button this way:

    Private Sub Button1_Click(ByVal sender As System.Object, _
        ByVal e As System.EventArgs) Handles Button1.Click
        tracker.Click()
    End Sub

You can see the result in Figure 11.2. Now you're creating and handling custom events.

Figure 11.2: Using custom events.