15.2 What are C events?

15.2 What are C# events?

Having reviewed the generic event model, I shall introduce C# events, and map C#'s implementation to the generic model.

A delegate instance encapsulates one or more (static or non-static) methods with the same return type and parameters, so that when the delegate instance is invoked all the methods in its invocation list are invoked in order with the same set of parameter values.

A C# event is a special type of delegate. It too encapsulates one or more methods “ in this case, event handlers “ so that when the event occurs, all these event handlers are invoked.

Event handlers usually take in two parameters, though this is not mandatory:

• one object type which references the event source; and

• one event object of type System.EventArgs , or a subclass of it.

Before you can do anything with events, you need to declare an event instance. But even before doing that, you must have a delegate type which matches the event handlers of your event consumers.

The statement below declares a delegate type which returns nothing, and takes in two parameters “ a reference to the event source of type object , and the event object of type EventArgs .

Since it is unlikely that your event consumer's event handlers will return any other thing besides void , you would want to declare your delegate type to return void too. Remember that the return type and the method parameters of your event handlers must match those of the delegate type.

Once you have the delegate type declared, you are ready to roll.

15.2.1 Event source class

The event source has to do two things.

• Declare the event object.

  You use the event keyword to do this. The following statement declares an event instance called SomethingHappened of type MyEventHandler :

  Note that the event's type must be a delegate type. ^[1]

  ^[1] That's why I said that an event is some kind of delegate. There is no separate event type “ all event instances are of a delegate type.

  

• Invoke the event when the event occurs.

  When the event occurs in the source, the source can fire the event by invoking it. Invoking an event is similar to invoking a delegate “ just pass in the correct parameters like this:

   SomethingHappened (this, new EventArgs()); 

  This statement will cause all the event handler methods in SomethingHappened 's invocation list to be invoked with the parameters this and a new EventArgs object. For the object parameter, this is passed in so that the consumer can have a reference to the source object. For the EventArgs parameter, a new event object is created and sent over.

15.2.2 Event consumer class

The event consumer also has do to two things:

• Provide an event handler.

  Here is an event handler called TellMe , coded in the consumer class:

   public void TellMe (object sender, EventArgs e){   Console.WriteLine("***** i am being notified! *****"); } 

  The return type and method parameters of TellMe must match those of the delegate type MyEventHandler . What this event handler does is simply print out a message to indicate that it is running.

• Register the event handler with the event source's event.

  You have got to tell the SomethingHappened event (of the event source) that you want to be notified when the event fires. This is done by using the += operator.

  Assuming that the event source class's name is EventSource , and the EventSource class has a public event instance called SomethingHappened , the following statements perform the registration:

   EventSource source = new EventSource(); source.SomethingHappened += new MyEventHandler(TellMe); 

  An event instance (in this case source.SomethingHappened ) can be used as the left-hand operand of the += and - = operators. You can register as many methods as you like with each event instance in the same manner using +=.

  This 'hooking up' of the event source to the event consumer can be done anywhere in your code as long as you have a reference to both the source object and the consumer object, though this registration of interest usually occurs in the event consumer. In this case, the consumer object has to either create an instance of the source, or obtain a reference to it in some way or other.

15.2.3 Event object class

System.EventArgs is the base class for predefined event objects in the BCL. You can subclass it to add in event-specific fields and accessor methods, but it is not mandatory that all event objects be subclasses of EventArgs .

In the first example below, I will simply use EventArgs as the event object class instead of writing a new subclass.