C# 2008 Programmer's Reference

To use the AlarmClock class, you first create an instance of the AlarmClock class and then set the time for the alarm by using the AlarmTime property. You then wire the TimesUp event with an event handler so that you can print a message when the set time is up:

class Program {
 static void Main(string[] args) {
  AlarmClock c = new AlarmClock() {
   //---alarm to sound off at 16 May 08, 9.50am---
   AlarmTime = new DateTime(2008, 5, 16, 09, 50, 0, 0),
  };
  c.Start();
  c.TimesUp += new EventHandler(c_TimesUp);
  Console.ReadLine();
 }
 static void c_TimesUp(object sender, EventArgs e) {
  Console.WriteLine('Times up!');
 }
}

Difference between Events and Delegates

Events are implemented using delegates, so what is the difference between an event and a delegate? The difference is that for an event you cannot directly assign a delegate to it using the = operator; you must use the += operator. 

To understand the difference, consider the following class definitions — Class1 and Class2:

namespace DelegatesVsEvents {
 class Program {
  static void Main(string[] args) {}
 }
 class Class1 {
  public delegate void Class1Delegate();
  public Class1Delegate del;
 }
 class Class2 {
  public delegate void Class2Delegate();
  public event Class2Delegate evt;
 }
}

In this code, Class1 exposes a public delegate del, of type Class1Delegate. Class2 is similar to Class1, except that it exposes an event evt, of type Class2Delegate. del and evt each expect a delegate, with the exception that evt is prefixed with the event keyword.

To use Class1, you create an instance of Class1 and then assign a delegate to the del delegate using the '=' operator:

static void Main(string[] args) {
 //---create a delegate---
 Class1.Class1Delegate d1 =
  new Class1.Class1Delegate(DoSomething);
 Class1 c1 = new Class1();
 //---assign a delegate to del of c1---
 c1.del = new Class1.Class1Delegate(d1);
}
static private void DoSomething() {
 //...
}

To use Class2, you create an instance of Class2 and then assign a delegate to the evt event using the += operator:

static void Main(string[] args) {
 //...
 //---create a delegate---
 Class2.Class2Delegate e2 =
  new Class2.Class2Delegate(DoSomething);
 Class2 c2 = new Class2();
 //---assign a delegate to evt of c2---
 c2.evt += new Class2.Class2Delegate(d1);
}

If you try to use the = operator to assign a delegate to the evt event, you will get a compilation error:

c2.evt = new Class2.Class2Delegate(d1); //---error---

This important restriction of event is important because defining a delegate as an event will ensure that if multiple clients are subscribed to an event, another client will not be able to set the delegate to null (or simply set it to another delegate). If the client succeeds in doing so, all the other delegates set by other client will be lost. Hence, a delegate defined as an event can only be set with the += operator.

Passing State Information to an Event Handler

In the preceding program, you simply raise an event in the AlarmClock class; there is no passing of information from the class back to the event handler. To pass information from an event back to an event handler, you need to implement your own class that derives from the EventArgs base class.

In this section, you modify the previous program so that when the set time is up, the event passes a message back to the event handler. The message is set when you instantiate the AlarmClock class.

First, define the AlarmClockEventArgs class that will allow the event to pass back a string to the event handler. This class must derive from the EventArgs base class:

public class AlarmClockEventArgs : EventArgs {
 public AlarmClockEventArgs(string Message) {
  this.Message = Message;
 }
 public string Message { get; set; }
}

Next, define a delegate called AlarmClockEventHandler with the following signature:

public delegate void AlarmClockEventHandler(object sender, AlarmClockEventArgs e);