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
  }
}