C# Tutorial – 28 – Events
Events enable an object to notify other objects when something of interest occurs. The object that raises the event is called the publisher and the objects that handle the event are called subscribers.
Publisher
To demonstrate the use of events the publisher will be created first. This will be a class that inherits from ArrayList
, but this version will raise an event whenever an item is added to the list. Before the event can be created a delegate is needed that will hold the subscribers. This could be any kind of delegate, but the standard design pattern is to use a void delegate that accepts two parameters. The first parameter specifies the source object of the event, and the second parameter is a type that either is or inherits from the System.EventArgs
class. This parameter usually contains the details of the event, but in this example there is no need to pass any event data and so the base EventArgs
class will be used as the parameter’s type.
public delegate void EventHandlerDelegate(object sender, System.EventArgs e); class Publisher : System.Collections.ArrayList { // … }
Event keyword
With the delegate defined, the event can be created in the Publisher
class using the event
keyword followed by the delegate and the name of the event. The event
keyword creates a special kind of delegate that can only be invoked from within the class where it is declared. Its access level is public so that other classes are allowed to subscribe to this event. The delegate that follows the event keyword is called the event delegate. The name of the event is commonly a verb. In this case the event will be raised after the item has been added so the past-tense of the verb “Add” is used, which is “Added”. If a pre-event was created instead, which is raised before the actual event, then the –ing form of the verb would be used, in this case “Adding”.
public event EventHandlerDelegate Added;
Alternatively, in place of this custom event delegate the predefined System.EventHandler
delegate could have been used. This delegate is identical to the one defined previously, and is used in the .NET class libraries for creating events that have no event data.
Event caller
To invoke the event an event caller can be created. The naming convention for this method is to precede the event’s name with the word “On”, which in this case becomes “OnAdded”. The method has the protected access level to prevent it from being called from an unrelated class, and it is marked as virtual to allow deriving classes to override it. It takes the event arguments as its one parameter, which in this case is of the EventArgs
type. The method will only raise the event if it is not null, meaning only when the event has any registered subscribers. To raise the event the this
instance reference is passed as the sender, and the EventArgs
object is the object that was passed to the method.
protected virtual void OnAdded(System.EventArgs e) { if (Added != null) Added(this, e); }
Raising events
Now that the class has an event and a method for calling it, the final step is to override the ArrayList
‘s Add
method to make it raise the event. In this overridden version of the method the base class’s Add
method is first called, and the result is stored. The event is then raised with the OnAdded
method, by passing to it the Empty
field in the System.EventArgs
class, which represents an event with no data. Finally, the result is returned to the caller.
public override int Add(object value) { int i = base.Add(value); OnAdded(System.EventArgs.Empty); return i; }
The complete publisher class now has the following appearance.
class Publisher : System.Collections.ArrayList { public delegate void EventHandlerDelegate(object sender, System.EventArgs e); public event EventHandlerDelegate Added; protected virtual void OnAdded(System.EventArgs e) { if (Added != null) Added(this, e); } public override int Add(object value) { int i = base.Add(value); OnAdded(System.EventArgs.Empty); return i; } }
Subscriber
To make use of the publisher class another class will be created that will subscribe to the event.
class Subscriber { // … }
Event handler
This class contains an event handler, which is a method that has the same signature as the event delegate and is used to handle an event. The name of the handler is commonly the same as the name of the event followed by the “EventHandler” suffix.
class Subscriber { public void AddedEventHandler(object sender, System.EventArgs e) { System.Console.WriteLine("AddEvent occurred"); } }
Subscribing to events
The publisher and subscriber classes are now complete. To demonstrate their use, a Main method is added where objects of the Publisher
and Subscriber
classes are created. In order to register the handler in the Subscriber
object to the event in the Publisher
object, the event handler is added to the event as if it was a delegate. Unlike a delegate, however, the event may not be called directly from outside its containing class. Instead, the event can only be raised by the Publisher
class, which in this case occurs when an item is added to that object.
class MyApp { static void Main() { Subscriber s = new Subscriber(); Publisher p = new Publisher(); p.Added += s.AddedEventHandler; p.Add(10); // AddEvent occurred } }