By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
424,984 Members | 1,040 Online
Bytes IT Community
Submit an Article
Got Smarts?
Share your bits of IT knowledge by writing an article on Bytes.

How To: Use Events In .NET

Frinavale
Expert Mod 5K+
P: 9,731
Background
An Event is a message sent out by an object to notify other objects that an action/trigger/state-change (ie. an event) has taken place. Therefore, you should use an event when an object's state change requires other objects to change as well.

The object that sends an event is known as the event sender.
The object that receives (or listens for) the event is known as the event receiver.

Events implement the "Observer Design Pattern". This pattern contains two key objects: a subject (the event sender), and an observer (the event receiver). The subject may have one or many observers.

Delegates are used in order to communicate between the sender and the receiver objects since the sender does not know what object type may be receiving (or handling) the event. The Delegate connects the Event with it's receiver (or handler).

Recall that, in .NET, Delegates are classes that serve as function pointers. They hold a reference (memory location) to a method. Also remember that Delegates can only hold references to methods that match its signature.

The Delegate identifies the method that provides the response to the event and holds the event data.

Using Generic Events (EventHandler Delegate)

A generic event handler delegate has been made available in the.NET Framework 2.0. It's referred to as EventHandler.

The EventHandler delegate holds a reference to a method that handles events raised which do not contain event data. In other words, it represents the method that will handle a typical event.

The EventHandler delegate's signature is as follows:
Expand|Select|Wrap|Line Numbers
  1. Public Delegate Sub EventHandler(ByVal sender As Object, ByVal e As EventArgs)
Expand|Select|Wrap|Line Numbers
  1. public delegate void EventHandler(Object sender, EventArgs e)
  2.  
  • The "sender" parameter is the object raising the event.
  • The "e" parameter is the event arguments that are passed back to the receiving object and contain data about the event. Since the event doesn't generate event data, this parameter is an instance of EventArgs.
  • If you require the event to generate event data (data that can be used by the receiving object in order to process something), then you cannot use the EventHandler. Instead you must use the EventHandler<T>. This is explained in more detail in the next section.

So if you needed to raise an event that does not generate event data you would declare your event as:
Expand|Select|Wrap|Line Numbers
  1.     Public Event NoDataEventHandler As EventHandler
  2.     'EventHandler is the delegate that holds a reference to a method with the signature: (Object sender, EventArgs e)
  3.     'You do not need to create a delegate called EventHandler as this is now part of the System class
  4.  
Then to raise the event in your sender class would do the following:
Expand|Select|Wrap|Line Numbers
  1. Private Sub OnMyEvent()
  2.    RaiseEvent NoDataEventHandler(Me, New EventArgs())
  3. End Sub
  4.  

Using Events That Return Event Data (EventHandler<T> Delegate)
If, when you raise the event, you need to pass data to the receiving objects, you cannot use the EventHandler delegate. Instead you need to use EventHandler<T>.

Since your event generates event data, you must first create a custom type to hold this data. This custom type has to be derived from EventArgs.
Expand|Select|Wrap|Line Numbers
  1. Public Class MyObjectsEventArgs
  2.      Inherits EventArgs
  3.      Private _theEventData As String
  4.      Public Sub New(ByVal eventData As String)
  5.           _theEventData = eventData
  6. End Sub
  7. Public Property Message() As String
  8.         Get
  9.             Return _theEventData
  10.         End Get
  11.         Set(ByVal value As String)
  12.             _theEventData = value
  13.         End Set
  14.     End Property
  15. End Class
  16.  
Now, because you cannot use the generic EventHandler, you need to create a Delegate using the EventHandler<T> delegate instead:
Expand|Select|Wrap|Line Numbers
  1.      Public Delegate Sub XEventHandler(Of MyObjectsEventArgs)(ByVal sender as Object, ByVal e As MyObjectsEventArgs)
  2.     'Note that MyObjectsEventArgs is the custom type derived from EventArgs used to pass the event data to the receiving class.
  3.  
Remember that you have to declare Delegates out side of your Class that raises the event. Also, note that this is a Public Delegate. It needs to be Public in order for the receiving object to be able to access it.

If you declare you Delegate as:
Expand|Select|Wrap|Line Numbers
  1.      Public Delegate Sub XEventHandler(ByVal sender as Object, ByVal e As MyObjectsEventArgs)
  2.      'Note that MyObjectsEventArgs is the custom type derived from EventArgs used to pass the event data to the receiving class.
  3.  
You will receive a warning from the compiler (run using code analysis):
... generates EventHandler delegates for events that use the following pattern: Event MyEvent(ByVal Sender As Object, ByVal e As MyEventArgs). Change the event that defines EventHandler 'EventHandler' to use EventHandler<T> ..."
It is complaining that you are declaring a Delegate that uses the EventHandler's signature except that you are not using EventArgs in the signature.
Now that you have a delegate to use to link the sender and receiver classes, you can declare an event as:
Expand|Select|Wrap|Line Numbers
  1.      Public Event SendMessageEvent As XEventHandler(Of MyObjectsEventArgs)
  2.  
Remember that you declare your event inside of your sender class. It should also be made public for the receiver class to handle.

To raise the event in your sender code you would do the following:
Expand|Select|Wrap|Line Numbers
  1. Private Sub OnMyEvent(ByVal message As String)
  2.      RaiseEvent SendMessageEvent(Me, New MyObjectsEventArgs(message))
  3. End Sub
  4.  
In your Receiving Class you need to create a method that matches the signature of the delegate in order to handle the event:
Expand|Select|Wrap|Line Numbers
  1. Private Sub TestEventSending_theEvent(ByVal sender As Object, ByVal e As MyObjectsEventArgs) Handles TestEventSending.SendMessageEvent 
  2.     'Note that "TestEventSending" is the instance of the Sender Object used in my Receiving Object
  3.     Label_Message = e.Message
  4.     'e is an instance of the MyObjectsEventArgs class we implemented to be able to send event data to the receiving object for it to use
  5.     'Recall that Message is a property of MyObjectsEventArgs that we defined to hold our event data
  6. End Sub
  7.  
References and Resources
EventHandler Generic Delegate
EventHandler(TEventArgs) Generic Delegate
Jan 17 '08 #1
Share this Article
Share on Google+
3 Comments


Plater
Expert 5K+
P: 7,872
I am not sure how this applies in VB.NET, but I know how to handle it in C#.

If you have a custom event in your class called say "MyEvent", if you trigger that event without an event handler attached, an exception is thrown. BUT, you can check for null on the event first to know if it is safe to fire the event.

Example(C#)
Expand|Select|Wrap|Line Numbers
  1. public delegate void NotifyStatusHandler(string Status);
  2.  
  3. public class MyClass
  4. {
  5.    public event NotifyStatusHandler NotifyStatus;
  6.    private void _NotifyStatus(string Status)
  7.    {
  8.       if (NotifyStatus != null)
  9.       {
  10.          NotifyStatus(Status);
  11.       }
  12.    }
  13.    public void TriggerEvent()
  14.    {
  15.       _NotifyStatus("testing");
  16.    }
  17. }
  18.  
Instead of calling the event directly to trigger it, I call a private function that checks to see if there is a delegate attached first or not
Nov 11 '08 #2

vekipeki
Expert 100+
P: 229
Good practice would also be to assign the event handler to a local, temporary variable before checking if it is null. This way you can avoid an exception in case some other thread unsubscribes from the handler just after you have checked it.

Expand|Select|Wrap|Line Numbers
  1.     private void _NotifyStatus(string Status)
  2.     {
  3.         // get a local reference
  4.         NotifyStatusHandler handler = NotifyStatus;
  5.  
  6.         if (handler != null)
  7.         {
  8.             // even if NotifyStatus is null in this moment,
  9.             // we are sure that 'handler' is non-null
  10.             handler (Status);
  11.         }
  12.     }
Feb 17 '09 #3

P: 6
If we call Delegate.Invoke() then the handler will get called synchronously. Means till the handler function is completed the control will not return back.

Expand|Select|Wrap|Line Numbers
  1. delegate void Foo();
  2.  
  3. Foo evtFoo;
  4.  
  5. evtFoo.Invoke(); //This will not return until the associated handler function is completed
In order to call it async, use BeginInvoke(). This function is coupled with EndInvoke(). EndInvoke() will wait till the handler operation is completed. In case you do not want to use EndInvoke() then BeginInvoke() accepts one parameter as function callback. This function will get called once the handler operation is completed.

Expand|Select|Wrap|Line Numbers
  1. evtFoo.BeginInvoke(MyCallback, null);
MyCallback should have a signature like this

Expand|Select|Wrap|Line Numbers
  1. void MyCallback(IAsynResult ar);
Oct 30 '09 #4