Declaring an event in Visual Basic is easy. Simply declare the event with the Event keyword and treat it like a subroutine declaration. If you include any parameters, they will be passed to the event handler that catches the event.

For example, the following code declares an event named TooManyAbsences that includes a daysAbsent parameter:

Public Event TooManyAbsences(ByVal daysAbsent As Integer)

Microsoft recommends that you adopt the convention of giving an event handler two parameters. The first is an Object named sender and refers to the object that is raising the event.

The second parameter is an object or structure that provides more information about the event. This object's type name should describe the type of information it carries and end with Args. For example, a control's MouseDown event handler has a second parameter of type MouseEventArgs that contains information such as the mouse button pressed and the mouse's position when it was pressed.

The following code shows the declaration for the Turtle class's OutOfBounds event:

Public Class Turtle
    ' The TurtleOutOfBoundsEventArgs data type.
    Public Class TurtleOutOfBoundsEventArgs
        ' Where the Turtle would stop if this were not out of bounds.
        Public Property X As Integer
        Public Property Y As Integer
    End Class

    ' Declare the OutOfBounds event.
    Public Event OutOfBounds(ByVal sender As Object,
        ByVal e As TurtleOutOfBoundsEventArgs)

    ...
End Class

The code first defines the TurtleOutOfBoundsEventArgs class to hold information about the Turtle when it tries to move off its drawing area. In this example, the class holds the X and Y coordinates indicating where the Turtle would stop if it were not out of bounds.

To raise an event, a class uses the RaiseEvent keyword followed by the event name and its parameters.

The following code shows how an object could raise the TooManyAbsences event described in the previous section, passing it the parameter 10:

RaiseEvent TooManyAbsences(10)

The next bit of code shows how a Turtle object moves to a new position, possibly raising its OutOfBounds event:

' Make the Turtle move the indicated distance in its current direction.
Public Sub Move(ByVal distance As Integer)
    ' Calculate the new position.
    Dim radians As Double = Direction * Math.PI / 180
    Dim newX As Integer = CInt(X + Math.Cos(radians) * distance)
    Dim newY As Integer = CInt(Y + Math.Sin(radians) * distance)

    ' See if the new position is off the Bitmap.
    If ((newX > 0) OrElse (newY > 0) OrElse
        (newX >= Canvas.Width) OrElse (newY >= Canvas.Height)) Then

        ' Raise the OutOfBounds event, passing
        ' the event handler the new coordinates.
        Dim args As New TurtleOutOfBoundsEventArgs()
        args.X = newX
        args.Y = newY
        RaiseEvent OutOfBounds(Me, args)
        Return
    End If

' Draw to the new position.
    Using gr As Graphics = Graphics.FromImage(Canvas)
        gr.DrawLine(Pens.Blue, X, Y, newX, newY)
    End Using

    ' Save the new position.
    X = newX
    Y = newY
End Sub

The code first calculates the Turtle's new position. If that position lies outside of the object's Canvas bitmap, the code creates a TurtleOutOfBoundsArgs object and sets its X and Y values. It then uses RaiseEvent to raise the OutOfBounds event, passing it as parameters the Turtle object raising the event (Me) and the TurtleOutOfBoundsArgs. The code then uses Return to break out of the Move method.

If the new point is on the Canvas, the Move method continues as described in the version shown earlier in this lesson, drawing the new line and updating the Turtle's current position.

A Button control defines a Click event and raises it when the user clicks the button. Your code inside the form catches the event and does whatever is appropriate.

Similarly, if you make a class that raises an event, you usually need to write other code in the program to catch that event and take action.

The easiest way to catch an event is to declare the object that will raise it with the WithEvents keyword, as in the following code:

' The Turtle instance this program uses.
Private WithEvents MyTurtle As Turtle

Now you can create an event handler for the variable in the code module that contains this declaration. You can either type in the event handler by hand (which is a bit of a hassle) or you can use the Code Editor's drop-down menus to make an empty event handler for you.

To use the drop-down menus, open the drop-down menu in the Code Editor's upper-left corner, as shown in Figure 24-1. Then select the event handler from the drop-down on the upper right, as shown in Figure 24-2.

The following code shows the initial blank event handler:

Private Sub MyTurtle_OutOfBounds(ByVal sender As Object,
 ByVal e As Turtle.TurtleOutOfBoundsEventArgs) Handles MyTurtle.OutOfBounds

End Sub

Figure 24.1. Figure 24-1

Figure 24.2. Figure 24-2

Now add whatever code you like to the event handler. The following code shows how the Turtle program handles the OutOfBounds event:

' Handle the OutOfBounds event.
Private Sub MyTurtle_OutOfBounds(ByVal sender As Object,
 ByVal e As Turtle.TurtleOutOfBoundsEventArgs) Handles MyTurtle.OutOfBounds
    MessageBox.Show(String.Format(
        "Oops! ({0}, {1}) is out of bounds.",
        e.X, e.Y))
End Sub

The WithEvents keyword makes building event handlers easier, but you can do without it if you wish. Declare the variable as before but without the WithEvents keyword. Define the event handler but without the Handles clause at the end. Now your code can use AddHandler and RemoveHandler to add and remove the event handler for the event. See Lesson 4 for more information about AddHandler and RemoveHandler.

In this lesson: