This documentation is archived and is not being maintained.

Events (C# vs. Java)

An event is a way for a class to notify the users of an object when something of interest happens to this object, such as, clicking a control in a graphical user interface. This notification is called raising an event. An object raising an event is referred to as the source or sender of the event.

Unlike event handling in Java, which is performed by implementing custom listener classes, C# developers can use delegates for event handling. A delegate is a type that references a method. Once a delegate is assigned a method, it behaves exactly like that method. It is similar to a C++ function pointer, but it is type-safe.

The delegate method can be used like any other method, with parameters and a return value, such as this example:

public delegate int ReturnResult(int x, int y);

For more information on delegates, see Delegates (C# Programming Guide).

Events, like methods, have a signature that includes a name and a parameter list. This signature is defined by a delegate type, for example:

public delegate void MyEventHandler(object sender, System.EventArgs e);

It is common to have the first parameter as the object referring to the source of the event, and the second parameter as the object carrying data related to the event. However, this design is not required or enforced by the C# language; an event signature can be the same as any valid delegate signature, as long as it returns void.

An event can be declared by using the event keyword like this example:

public event MyEventHandler TriggerIt;

To trigger the event, define the method to be invoked when the event is raised like this example:

public void Trigger()
{
    TriggerIt();
}

To raise an event, call the delegate, and pass the parameters related to the event. The delegate then calls all the handlers that have been added to the event. Each event can have more than one handler assigned to receive the event. In this case, the event calls each receiver automatically. Raising an event requires only one call to the event regardless of the number of receivers.

If you want a class to receive an event, subscribe to that event by adding the delegate to the event using the += operator, for example:

myEvent.TriggerIt += new MyEventHandler(myEvent.MyMethod);

To unsubscribe from an event, remove the delegate from the event by using the -= operator, for example:

myEvent.TriggerIt -= new MyEventHandler(myEvent.MyMethod);

For more information on events, see Events (C# Programming Guide).

NoteNote

In C# 2.0, delegates can encapsulate both named methods and anonymous methods. For more information on anonymous methods, see Anonymous Methods (C# Programming Guide).

Example

The following example defines an event with three methods associated with it. When the event is triggered the methods are executed. One method is then removed from the event and the event is triggered again.

// Declare the delegate handler for the event:
public delegate void MyEventHandler();

class TestEvent
{
    // Declare the event implemented by MyEventHandler.
    public event MyEventHandler TriggerIt;

    // Declare a method that triggers the event:
    public void Trigger()
    {
        TriggerIt();
    }
    // Declare the methods that will be associated with the TriggerIt event.
    public void MyMethod1()
    {
        System.Console.WriteLine("Hello!");
    }
    public void MyMethod2()
    {
        System.Console.WriteLine("Hello again!");
    }
    public void MyMethod3()
    {
        System.Console.WriteLine("Good-bye!");
    }

    static void Main()
    {
        // Create an instance of the TestEvent class.
        TestEvent myEvent = new TestEvent();

        // Subscribe to the event by associating the handlers with the events:
        myEvent.TriggerIt += new MyEventHandler(myEvent.MyMethod1);
        myEvent.TriggerIt += new MyEventHandler(myEvent.MyMethod2);
        myEvent.TriggerIt += new MyEventHandler(myEvent.MyMethod3);
        // Trigger the event:
        myEvent.Trigger();

        // Unsuscribe from the the event by removing the handler from the event:
        myEvent.TriggerIt -= new MyEventHandler(myEvent.MyMethod2);
        System.Console.WriteLine("\"Hello again!\" unsubscribed from the event."); 

        // Trigger the new event:
        myEvent.Trigger();
    }
}

Output

 
Hello!
Hello again!
Good-bye!
"Hello again!" unsubscribed from the event.
Hello!
Good-bye!

See Also

Show: