Raising Events, Event Handlers, and the Use of Delegates

// Instantiates the event source.

AlarmClock clock = new AlarmClock();

// Wires the AlarmRang method to the Alarm event.

clock.Alarm += new AlarmEventHandler(w.AlarmRang);

clock.Start();

}

}

}

We compile this code, eventsample.cs, with a reference to System.dll:



So, What is a Delegate?

A delegate is a class (that uses the delegate keyword) that can hold a reference to a method. Unlike other classes, a delegate class has a signature, and can hold references to methods that match its signature. A delegate is thus equivalent to a type-safe function pointer or a callback. While delegates have many other uses, this section will focus on the event-handling functionality of delegates. A delegate declaration is sufficient to define a delegate class. The declaration supplies the signature of the delegate, and the CLR provides the implementation. The following example shows an event delegate declaration:

public delegate void AlarmEventHandler(object sender, EventArgs e);

The standard signature of an event handler delegate defines a method that does not return a value, whose first parameter is of type Object and refers to the instance that raises the event, and whose second parameter is derived from type EventArgs and holds the event data. So, a delegate in C# is similar to a function pointer in C or C++. Using a delegate allows us to encapsulate a reference to a method inside a delegate object. The delegate object can then be passed to code that can call the referenced method (provided the parameters match), without having to know at compile time which method will be invoked. Unlike function pointers in C or C++, delegates are object-oriented, type-safe, and secure. Just as the CLR does not even need to know which .NET language has been compiled, the CLR knows that managed code emits metadata and IL code. The metadata tables are examined to perform type-safe checking to ensure that proper data is being passed to the proper method, since the IL code is JIT compiled. In short, a delegate declaration defines a type that encapsulates a method with a specific set of arguments and a return type. For static methods, a delegate object encapsulates the method to be called. For instance methods, a delegate object encapsulates both an instance and a method on the methods. Recall that the difference between static and instance methods is that one operates on the type itself and the other operates on an instance of the type. If you have a delegate object and an appropriate set of arguments then you can invoke the delegate with the arguments.

Examine the following code:

using System;

// A set of classes for handling a bookstore:

namespace Bookstore

{

using System.Collections;

// Describes a book in the book list:

public struct Book

{

public string Title; // Title of the book.

public string Author; // Author of the book.

public decimal Price; // Price of the book.

public bool Paperback; // Is it paperback?

public Book(string title, string author, decimal price, bool paperBack)

{

Title = title;

Author = author;

Price = price;

Paperback = paperBack;

}

}

// Declare a delegate type for processing a book:

public delegate void ProcessBookDelegate(Book book);

// Maintains a book database.

public class BookDB

{

// List of all books in the database:

ArrayList list = new ArrayList();

// Add a book to the database:

public void AddBook(string title, string author, decimal price, bool paperBack)

{

list.Add(new Book(title, author, price, paperBack));

}

// Call a passed-in delegate on each paperback book to process it:

public void ProcessPaperbackBooks(ProcessBookDelegate processBook)

{

foreach (Book b in list)

{

if (b.Paperback)

// Calling the delegate:

processBook(b);

}

}

}

}

// Using the Bookstore classes:

namespace BookTestClient

{

using Bookstore;

// Class to total and average prices of books:

class PriceTotaller

{

int countBooks = 0;

decimal priceBooks = 0.0m;

internal void AddBookToTotal(Book book)

{

countBooks += 1;

priceBooks += book.Price;

}

internal decimal AveragePrice()

{

return priceBooks / countBooks;

}

}

// Class to test the book database:

class Test

{

// Print the title of the book.

static void PrintTitle(Book b)

{

Console.WriteLine(" {0}", b.Title);

}

// Execution starts here.

static void Main()

{

BookDB bookDB = new BookDB();

// Initialize the database with some books:

AddBooks(bookDB);

// Print all the titles of paperbacks:

Console.WriteLine("Paperback Book Titles:");

// Create a new delegate object associated with the static

// method Test.PrintTitle:

bookDB.ProcessPaperbackBooks(new ProcessBookDelegate(PrintTitle));

// Get the average price of a paperback by using

// a PriceTotaller object:

PriceTotaller totaller = new PriceTotaller();

// Create a new delegate object associated with the nonstatic

// method AddBookToTotal on the object totaller:

bookDB.ProcessPaperbackBooks(new ProcessBookDelegate(totaller.AddBookToTotal));

Console.WriteLine("Average Paperback Book Price: ${0:#.##}",

totaller.AveragePrice());

}

// Initialize the book database with some test books:

static void AddBooks(BookDB bookDB)

{

bookDB.AddBook("The C Programming Language",

"Brian W. Kernighan and Dennis M. Ritchie", 19.95m, true);

bookDB.AddBook("The Unicode Standard 2.0",

"The Unicode Consortium", 39.95m, true);

bookDB.AddBook("The MS-DOS Encyclopedia",

"Ray Duncan", 129.95m, false);

bookDB.AddBook("Dogbert's Clues for the Clueless",

"Scott Adams", 12.00m, true);

}

}

}

Now, examine the output:

Paperback Book Titles:

The C Programming Language

The Unicode Standard 2.0

Dogbert's Clues for the Clueless

Average Paperback Book Price: $23.97

We instantiated the delegate because once the delegate has been declared, a delegate object must be created and associated with a specific method. Like all other objects, a new delegate object is created with a new expression. Herein lies one principle difference between the object-oriented and the procedural C language: in C, when we declare a variable, we are informing the compiler with the type of data that will function as a variable that will have an assigned value. The compiler then allocates the storage needed for that specific data type. When creating a delegate, however, the argument passed to the new expression is special; it is written like a method call, but without the arguments to the method, as shown in the following statement:

bookDB.ProcessPaperbackBooks(new ProcessBookDelegate(PrintTitle));

When creating a delegate, however, the argument passed to the new expression is special; it is written like a method call, but without the arguments to the method.

bookDB.ProcessPaperbackBooks(new ProcessBookDelegate(PrintTitle));

That statement creates a new delegate object associated with the static method Test.PrintTitle. The following statement:

bookDB.ProcessPaperbackBooks(new ProcessBookDelegate(totaller.AddBookToTotal));

creates a new delegate object associated with the non-static method AddBookToTotal on the object totaller. In both cases, this new delegate object is immediately passed to the ProcessPaperbackBooks method. Note that once a delegate is created, the method it is associated with never changes; delegate objects are immutable.

Responding to an Event

The downloadable file, SystemTimer, is a Windows Forms application that contains a progress bar control. The idea is to control this progress bar control by responding to timer events. Timer objects can be used to throw events after a specified number of milliseconds. You simply create a Windows Forms project, drag and drop a progress bar control onto the form's surface, and then declare a Timer object. Download the code into a folder named TimerEvents in the Projects folder of your edition of Visual Studio. Do not try to run the solution file from the Zip archive. When these files are extracted to this new subfolder of the Projects folder, double-click the solution file to see how the progress bar reacts after a certain number of milliseconds pass.
The following is referenced code from Jeffrey Richter's Book "CLR via C#". This code is exemplary, and a student of .NET development should refer to this code continually in order to demystify delegates:

using System;

using System.Windows.Forms;

using System.IO;

// Declare a delegate type; instances refer to a method that

// takes an Int32 parameter and returns void.

internal delegate void Feedback(Int32 value);

public sealed class Program {

public static void Main() {

StaticDelegateDemo();

InstanceDelegateDemo();

ChainDelegateDemo1(new Program());

ChainDelegateDemo2(new Program());

}

private static void StaticDelegateDemo() {

Console.WriteLine("----- Static Delegate Demo -----");

Counter(1, 3, null);

Counter(1, 3, new Feedback(Program.FeedbackToConsole));

Counter(1, 3, new Feedback(FeedbackToMsgBox)); // "Program." is optional

Console.WriteLine();

}

private static void InstanceDelegateDemo() {

Console.WriteLine("----- Instance Delegate Demo -----");

Program p = new Program();

Counter(1, 3, new Feedback(p.FeedbackToFile));

Console.WriteLine();

}

private static void ChainDelegateDemo1(Program p) {

Console.WriteLine("----- Chain Delegate Demo 1 -----");

Feedback fb1 = new Feedback(FeedbackToConsole);

Feedback fb2 = new Feedback(FeedbackToMsgBox);

Feedback fb3 = new Feedback(p.FeedbackToFile);

Feedback fbChain = null;

fbChain = (Feedback) Delegate.Combine(fbChain, fb1);

fbChain = (Feedback) Delegate.Combine(fbChain, fb2);

fbChain = (Feedback) Delegate.Combine(fbChain, fb3);

Counter(1, 2, fbChain);

Console.WriteLine();

fbChain = (Feedback) Delegate.Remove(fbChain,

new Feedback(FeedbackToMsgBox));

Counter(1, 2, fbChain);

}

private static void ChainDelegateDemo2(Program p) {

Console.WriteLine("----- Chain Delegate Demo 2 -----");

Feedback fb1 = new Feedback(FeedbackToConsole);

Feedback fb2 = new Feedback(FeedbackToMsgBox);

Feedback fb3 = new Feedback(p.FeedbackToFile);

Feedback fbChain = null;

fbChain += fb1;

fbChain += fb2;

fbChain += fb3;

Counter(1, 2, fbChain);

Console.WriteLine();

fbChain -= new Feedback(FeedbackToMsgBox);

Counter(1, 2, fbChain);

}

private static void Counter(Int32 from, Int32 to, Feedback fb) {

for (Int32 val = from; val <= to; val++) {

// If any callbacks are specified, call them

if (fb != null)

fb(val);

}

}

private static void FeedbackToConsole(Int32 value) {

Console.WriteLine("Item=" + value);

}

private static void FeedbackToMsgBox(Int32 value) {

MessageBox.Show("Item=" + value);

}

private void FeedbackToFile(Int32 value) {

StreamWriter sw = new StreamWriter("Status", true);

sw.WriteLine("Item=" + value);

sw.Close();

}

}

When you compile and execute this code, notice the command line display lines that correspond with the Windows Forms buttons. Now, recall that a delegate indicates the signature of a callback method. The code starts with the declaration of the internal delegate, Feedback. Feedback identifies a method that takes a parameter (an Int32) and returns a void. Now, the Program class defines a private static method named Counter. This method counts integers from the from argument to the to argument. The Counter also takes an fb, which is a reference to a Feedback delegate object. Recall or understand that the CLR requires that any object must be created by calling the new operator. For instance, a Patient object will be created like so:

Patient p = new Patient();

The new operator performs a series of underlying operations, not to mention using the variable (in this case, p) as a reference where the constructor's parameters are stored. The Counter loops through all of the integers, and for each integer, if the fb variable is not null, the callback method (specified by the fb variable) is called. This callback method is passed the value of the item being processed, the item number. The callback method can be designed and implemented to process each item in any manner deemed appropriate.