Events and Event Handlers
While you might visualize a Visual Studio project as a series of procedures that execute in a sequence, in reality, most programs are event driven—meaning the flow of execution is determined by external occurrences called events.
An event is a signal that informs an application that something important has occurred. For example, when a user clicks a control on a form, the form can raise a Click event and call a procedure that handles the event. Events also allow separate tasks to communicate. Say, for example, that your application performs a sort task separately from the main application. If a user cancels the sort, your application can send a cancel event instructing the sort process to stop.
Event Terms and Concepts
This section describes the terms and concepts used with events in Visual Basic.
Declaring Events
You declare events within classes, structures, modules, and interfaces using the Event keyword, as in the following example:
Event AnEvent(ByVal EventNumber As Integer)
Event AnEvent(ByVal EventNumber As Integer)
Raising Events
An event is like a message announcing that something important has occurred. The act of broadcasting the message is called raising the event. In Visual Basic, you raise events with the RaiseEvent statement, as in the following example:
RaiseEvent AnEvent(EventNumber)
RaiseEvent AnEvent(EventNumber)
Events must be raised within the scope of the class, module, or structure where they are declared. For example, a derived class cannot raise events inherited from a base class.
Event Senders
Any object capable of raising an event is an event sender, also known as an event source. Forms, controls, and user-defined objects are examples of event senders.
Event Handlers
Event handlers are procedures that are called when a corresponding event occurs. You can use any valid subroutine with a matching signature as an event handler. You cannot use a function as an event handler, however, because it cannot return a value to the event source.
Visual Basic uses a standard naming convention for event handlers that combines the name of the event sender, an underscore, and the name of the event. For example, the Click event of a button named button1 would be named Sub button1_Click.
Note
We recommend that you use this naming convention when defining event handlers for your own events, but it is not required; you can use any valid subroutine name.
Associating Events with Event Handlers
Before an event handler becomes usable, you must first associate it with an event by using either the Handles or AddHandler statement.
The WithEvents statement and Handles clause provide a declarative way of specifying event handlers. Events raised by an object declared with WithEvents can be handled by any subroutine with a Handles clause that names this event. Although the Handles clause is the standard way of associating an event with an event handler, it is limited to associating events with event handlers at compile time.
The AddHandler and RemoveHandler statements are more flexible than the Handles clause. They allow you to dynamically connect and disconnect the events with one or more event handlers at run time, and they do not require you to declare object variables using WithEvents. However, there are some restrictions with using WithEvents. For more information, see WithEvents and the Handles Clause.
In some cases, such as with events associated with forms or controls, Visual Basic automatically stubs out an empty event handler and associates it with an event. For example, when you double-click a command button on a form in design mode, Visual Basic creates an empty event handler and a WithEvents variable for the command button, as in the following code:
Friend WithEvents Button1 As System.Windows.Forms.Button
Protected Sub Button1_Click(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles Button1.Click
End Sub
Friend WithEvents Button1 As System.Windows.Forms.Button
Protected Sub Button1_Click(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles Button1.Click
End Sub
See Also
Tasks
Concepts
WithEvents and the Handles Clause