In this section, I walk you through two examples of using a callback — a delegate instance phoning home to the object that created it, like E.T. But first take a look at some common variations on what you can use a callback delegate for:

The SimpleDelegateExample program on the Web site demonstrates a simple delegate:

// SimpleDelegateExample -- Demonstrate a simple delegate callback.
using System;
namespace SimpleDelegateExample
{
  class Program
  {
    delegate int MyDelType(string name);  // Inside class or inside namespace

    static void Main(string[] args)
    {
      // Create a delegate instance pointing to the CallBackMethod below.
      // Note that the callback method is static, so you prefix the name
      // with the class name, Program.
      MyDelType del = new MyDelType(Program.CallBackMethod);
      // Call a method that will invoke the delegate.
      UseTheDel(del, "hello");
      // Wait for user to acknowledge results.
      Console.WriteLine("Press Enter to terminate...");
      Console.Read();
    }
    // UseTheDel -- A "workhorse" method that takes a MyDelType delegate
    //    argument and invokes the delegate. arg is a string I want to pass
    //    to the delegate invocation.
    private static void UseTheDel(MyDelType del, string arg)
    {
      if (del == null) return; // Don't invoke a null delegate!
      // Here's where you invoke the delegate.
      // What's written here? A number representing the length of arg.
     Console.WriteLine("UseTheDel writes {0}", del(arg));
    }
    // CallBackMethod -- A method that conforms to the MyDelType
    //    delegate signature (takes a string, returns an int).
    //    The delegate will call this method.
    public static int CallBackMethod(string stringPassed)
    {
      // Leave tracks to show you were here.
      // What's written here? stringPassed.
      Console.WriteLine("CallBackMethod writes: {0}", stringPassed);
      // Return an int.
      return stringPassed.Length;  // Delegate requires an int return.
    }
  }
}

The delegate-related parts of this example are highlighted in boldface.

First you see the delegate definition. MyDelType defines a signature — you can pass any method with the delegate; such a method must take a string argument and return an int. Second, the CallBackMethod(), defined at the bottom of the listing, matches that signature. Third, Main() creates an instance of the delegate, called del, and then passes the delegate instance to a "workhorse" method, UseTheDel(), along with some string data, "hello", that the delegate requires.

In that setup, here's the sequence of events:

The output looks like this:

CallBackMethod writes: hello
UseTheDel writes 5
Press Enter to terminate...

UseTheDel() phones home and CallBackMethod() answers the call.

The SimpleProgress example on the Web site demonstrates the Windows Forms ProgressBar control that I discuss at the top of this chapter. (By the way, this example of Windows graphical programming is the only one in this book — even if it's simple-minded — so I step through it carefully. I urge you to complete the steps as I provide them.)

The example displays a small dialog-box-style window with two buttons and a progress bar (refer to Figure 9-1). When you load the solution example into Visual Studio and then build it, run it, and click the upper button, marked Click to Start, the progress bar runs for a few seconds. You see it gradually fill up, one-tenth of its length at a time. When it's completely full, you can click the Close button to end the program or click Click to Start again.

To create the sample app on your own, rather than just load it from the Web site example — and experience a bit of Windows graphical programming — follow these steps, working first in design mode, where you're just laying out the appearance of your app.

First create the project and position the necessary controls on your "window":

Next, set properties for these controls: Choose View

Now, still in design mode, add a handler method for each button:

I walk you through the remaining code, all of it on the form class, in the next section. Later in the chapter, I show you other variations on the delegate that's passed.

The remaining bits of code tucked into the Form1 class consist of the parts of the delegate life cycle, covered earlier in this chapter. I show you the class and then show you where the parts are. The boldfaced lines are new code that you add beyond the items you added in the previous section:

using System;
using System.Windows.Forms;
namespace SimpleProgress
{
  public partial class Form1 : Form
  {
    // Declare the delegate. This one is void.
    delegate void UpdateProgressCallback();

    public Form1()
    {
      InitializeComponent();
    }
    // DoSomethingLengthy -- My workhorse method takes a delegate.
    private void DoSomethingLengthy(UpdateProgressCallback updateProgress)
    {
      int duration = 2000;
      int updateInterval = duration / 10;
      for (int i = 0; i < duration; i++)
      {
        Console.WriteLine("Something or other");
        // Update every tenth of the duration.
        if ((i % updateInterval) == 0 && updateProgress != null)
        {
          updateProgress();  // Invoke the delegate.
        }
      }
    }
    // DoUpdate -- The callback method
    private void DoUpdate()
    {
      progressBar1.PerformStep();
    }
    private void button1_Click(object sender, EventArgs e)
    {
      // Instantiate the delegate, telling it what method to call.
      UpdateProgressCallback callback = new UpdateProgressCallback(this.
     DoUpdate);
      // Do something that needs periodic progress reports.
      // This passes a delegate instance that knows how to update the bar.
      DoSomethingLengthy(callback);
        // Clear the bar so that it can be used again.
        progressBar1.Value = 0;
    }
    private void button2_Click(object sender, EventArgs e)
    {
      this.Close();
    }
  }
}

public partial class Form1 : Form

The partial keyword indicates that this line is only part of the full class. The rest can be found in the Form1.Designer.cs file listed in Solution Explorer. (Take a look at it.) Later in this chapter, I revisit that file to show you a couple of things about "events." Partial classes, which were introduced in C# 2.0, let you split a class between two or more files. The compiler generates the Form1.Designer.cs file, so don't modify its code directly. You can modify it indirectly, however, by changing elements on the form. Form1.cs is your part.

Look at the example through the parts of the delegate life cycle:

Write a custom delegate when you need to define a type for delegate-type parameters so that you can implement a callback. Use predefined delegates for events and the collection classes' Find() and ForEach() methods.

It's extremely common in programming for various objects in the running program — those anxious relatives I mentioned — to be "interested in" events that occur on other objects. For example, when the user clicks a button, the form that contains the button "wants" to know about it. Events provide the standard mechanism in C# and .NET for notifying any interested parties of important actions.

The Observer pattern consists of an Observable object — the object with interesting events (sometimes called the Subject, though that confuses me) — and any number of Observer objects: those interested in a particular event. The observers register themselves with the Observable in some way and, when events of interest occur, the Observable notifies all registered observers. You can implement this pattern in numerous ways without events (such as callbacks and interfaces), but the C# way is to use events.

One analogy for events is your local newspaper. You and many other people contact the paper to subscribe, and then the paper delivers current newspapers to you, typically soaked in a rain puddle. The newspaper company is the Publisher, and its customers are Subscribers, so this variation of Observer is often called Publish/Subscribe. That's the analogy I stick to in this chapter, but keep in mind that the Observer pattern is the Publish/Subscribe pattern with different terminology. Observers are subscribers, and the Observable object that they observe is a publisher.

In C#, when you have a class on which interesting events arise, you advertise the availability of notifications to any classes that may have an interest in knowing about such events by providing an event object (usually public).

public class PublisherOfInterestingEvents
{
  // A delegate type on which to base the event.
  // Should be declared 'internal' if all subscribers are in the same assembly.
  public delegate void NewEditionEventHandler(object sender,
                                              NewEditionEventArgs e);
  // The event:
  public event NewEditionEventHandler NewEdition;
  // ... other code.
}

The delegate and event definitions announce to the world: "Subscribers welcome!" You can think of the NewEdition event as similar to a variable of the NewEditionEventHandler delegate type. (So far, no events have been sent. This is just the infrastructure for them.)

event _dispCommandBarControlEvents_ClickEventHandler Click;

where the second, lo-o-ong item is a delegate defined somewhere in .NET.

event EventHandler<NewEditonEventArgs> NewEdition;

To receive a particular event, subscribers sign up something like this:

publisher.EventName +=
  new EventHandler<some EventArgs type here >(some method name here);

where publisher is an instance of the publisher class, EventName is the event name, and EventHandler<TEventArgs> is the delegate underneath the event. More specifically, the code in the previous example might be:

myPublisher.NewEdition += new EventHandler<NewEditionEventArgs>(MyPubHandler);

Because an event object is a delegate under its little hood, the += syntax is adding a method to the list of methods that the delegate will call when you invoke it.

When the publisher decides that something worthy of publishing to all subscribers has occurred, it raises (sends) the event. This situation is analogous to a real newspaper putting out the Sunday edition.

To publish the event, the publisher would have code like this in one of its methods (but see the later section "A recommended way to raise your events"):

NewEditionEventArgs e = new NewEditionEventArgs(<args to constructor here>);
NewEdition(this, e);  // Raise the event -- 'this' is the publisher object.

Or for the Button example, though this is hidden in class Button:

EventArgs e = new EventArgs();  // See next section for more on this topic.
Click(this, e);                 // Raise the event.

In each of these examples, you set up the necessary arguments — which differ from event to event; some events need to pass along a lot of info. Then you raise the event by "calling" its name (like invoking a delegate!):

eventName(<argumentlist>); // Raising an event (distributing the newspaper)
NewEdition(this, e);

Passing along a reference to the event's sender (the object that raises the event) is useful if the event-handling method needs to get more information from it. Thus a particular Button object, button1, can pass a reference to the Form class the button is a part of. The button's Click event handler resides in a Form class, so the sender is the form: You would pass this.

The e parameter to an event handler method is a custom subclass of the System.EventArgs class. You can write your own NewEditionEventArgs class to carry whatever information you need to convey:

public class NewEditionEventArgs : EventArgs
{
  public NewEditionEventArgs(DateTime date, string majorHeadline)
  { PubDate = date; Head = majorHeadline; }
  public DateTime PubDate { get; private set; }  // Compiler creates details.
  public string Head { get; private set; }  //
}

You should implement this class's members as properties, as shown in the previous code example. The constructor uses the private setter clauses on the properties.

Often, your event doesn't require any extra arguments and you can just fall back on the EventArgs base class, as shown in the next section.

NewEdition(this, EventArgs.Empty);  // Raise the event.

The earlier section "How to publish an event" shows the bare bones of raising an event. However, I recommend that you always define a special "event raiser" method, like this:

protected virtual void OnNewEdition(NewEditionEventArgs e)
{
  EventHandler<NewEditionEventArgs> temp = NewEdition;
  if(temp != null)
  {
    temp(this, e);
  }
}

Providing this method ensures that you always remember to complete two steps:

Making the method protected and virtual allows subclasses to override it. That's optional.

After you have that method, which always takes the same form (making it easy to write quickly), you call the method when you need to raise the event:

void SomeMethod()
{
  // Do stuff here and then:
  NewEditionEventArgs e =
    new NewEditionEventArgs(DateTime.Today, "Peace Breaks Out!");
  OnNewEdition(e);
}

The subscribing object specifies the name of a handler method when it subscribes — it's the argument to the constructor (boldfaced):

button1.Click += new EventHandler<EventArgs>(button1_Click);

This line sort of says, "Send my paper to this address, please." Here's a handler for the NewEdition event:

myPublisher.NewEdition += new EventHandler<NewEditionEventArgs>(NewEdHandler);
...
void NewEdHandler(object sender, NewEditionEventArgs e)
{
  // Do something in response to the event.
}

For example, a BankAccount class can raise a custom TransactionAlert event when anything occurs in a BankAccount object, such as a deposit, withdrawal, or transfer or even an error. A Logger observer object can subscribe and log these events to a file or a database as an audit trail.

In your subscriber's handler method, you do whatever is supposed to happen when your class learns of this kind of event. To help you write that code, you can cast the sender parameter to the type you know it to be:

Button theButton = (Button)sender;

and then call methods and properties of that object as needed. Because you have a reference to the sending object, you can ask the subscriber questions and carry out operations on it if you need to — like the person who delivers your newspaper knocking on your door to collect the monthly subscription fees. And, you can extract information from the e parameter by getting at its properties in the same way:

Console.WriteLine(e.HatSize);

You don't always need to use the parameters, but they can be handy.