Click here to Skip to main content
Click here to Skip to main content

Step by Step: Event handling in C#

By , 22 Sep 2003
Rate this:
Please Sign up or sign in to vote.

Introduction

In this step by step article, we look at implementing event handling in C#.

Implementing events

Step 1 - Create an EventArgs class

If you need to pass arguments to the event handler, a specific EventArgs class has to be made. Eventually, a suitable EventArgs class might already be available, but in most cases, you will have to create one to tailor your specific arguments.

If you do not need to pass arguments to the event handler (except the 'sender'), then no subclass of EventArgs is needed. However, note that you should still define the event method with an argument of type System.EventArgs, and then pass System.EventArgs.Empty.

Create the EventArgs subclass as follows:

    public class StartEventArgs : System.EventArgs {
        // Provide one or more constructors, as well as fields and
        // accessors for the arguments.
    }

Note: all EventArgs classes should have a name ending on 'EventArgs'.

Step 2 - Create a delegate

For each EventArgs subclass you have created, a matching delegate should be created. Best practice is to declare the EventArgs subclass and the delegate in the same scope (inside the same namespace or inside the same class). A delegate declaration looks pretty much like a method declaration, but in fact, when declaring a delegate, you create a new class, so placing a delegate declaration directly in a namespace is no problem.

When you use the default System.EventArgs class instead of a subclass of it, there is no need to declare a delegate, you can use the System.EventHandler delegate.

You might also decide to create a specific EventArgs subclass, but no delegate for it. In that case, the event will be delcared of type System.EventHandler (or any superclass of your specific EventArgs subclass for which a delegate is available) and casting of the EventArgs argument in the eventhandler method will be needed.

Declare a delegate as follows:

    public delegate void StartEventHandler(object sender, StartEventArgs e);

Note: all delegate classes used for event handling should have a name ending on 'EventHandler' and should be of type void. (Delegates that are not of type void are not suitable for multicasting and therefore not suitable for event handling.)

Step 3 - Create Events

For each kind of event, an Event is created in the sending class. The event is declared as of type it's delegate. Multiple events can use the same delegate (think of the delegate as a class, and an event as an instance of it):

    public class Sender {

        public event StartEventHandler BeforeStart;
        public event StartEventHandler AfterStart;

        //...
    
    }

Step 4 - Create OnEvent methods

Although not required, it is a good convention to create protected virtual OnEvent methods for your events:

    protected virtual void OnBeforeStart(StartEventArgs e) {
        if (BeforeStart != null) BeforeStart(this, e);
    }

    protected virtual void OnAfterStart(StartEventArgs e) {
        if (AfterStart != null) AfterStart(this, e);
    }

You can now call this method whenever you want to send the Start event. I.e:

    OnBeforeStart(new StartEventArgs());

Step 5 - Make the event default

When you class represents a component, it is good practice to make the most commonly used event the default event. Add a DefaultEvent attribute in front of your sender class:

    [System.ComponentModel.DefaultEvent("BeforeStart")]
    public class Sender : System.ComponentModel.Component {
        //...

Handling events

A add a handler to an event, use the (overloaded) += assignment operator, as in:

    sender.BeforeStart += new StartEventHandler(this.sender_BeforeStart);

To remove the handler, use the (overloaded) -= assignement operator:

    sender.BeforeStart -= new StartEventHandler(this.sender_BeforeStart);

It might look strange to remove a newly created object. In reality, when you remove a handler, the .NET framework will look for a handler using the same handler method, and remove that handler. The newly created object is then garbage collected.

Here, sender_BeforeStart is the method that will handle the event. It looks like:

    private void sender_BeforeStart(object sender, StartEventArgs e) {
        //...
    }

VS.NET generates the handler methodnames by using the fieldname of the sender object (the name of the variable sending events), and concatenate's to it an underscore followed by the name of the event. It is good practice to follow this convention whenever you are handling events of objects that are declared as fields on your class. In other situations, you are free to choose any arbitrary methodname, however avoid names starting by 'On' (to avoid confusion with event sending methods); when in lack of inspiration, we suggest methods starting with 'Handle' (i.e. HandleBeforeStart).

Code sample

public delegate void StartEventHandler(object sender, StartEventArgs e);

public class StartEventArgs : System.EventArgs {
    // Provide one or more constructors, as well as fields and
    // accessors for the arguments.
}

public class Sender {

    public event StartEventHandler BeforeStart;
    public event StartEventHandler AfterStart;

    protected virtual void OnBeforeStart(StartEventArgs e) {
        if (BeforeStart != null) BeforeStart(this, e);
    }

    protected virtual void OnAfterStart(StartEventArgs e) {
        if (AfterStart != null) AfterStart(this, e);
    }

    void DoStart() {
        OnBeforeStart(new StartEventArgs());
        //...
        OnAfterStart(new StartEventArgs());
    }

    //...

}

public class Receiver {
    
    Sender sender;

    public Receiver() {
        sender = new Sender();
    }

    void Connect() {
        sender.BeforeStart += new StartEventHandler(this.sender_BeforeStart);
    }

    private void sender_BeforeStart(object sender, StartEventArgs e) {
        //...
    }

    //...

}

License

This article, along with any associated source code and files, is licensed under A Public Domain dedication

About the Author

Rudi Breedenraedt
Architect Wolters Kluwer Belgium
Belgium Belgium
Rudi is a Software Architect at Wolters Kluwer Belgium.

Comments and Discussions

 
QuestionMessage Automatically Removed PinprofessionalRavi.Kumar02121-Jul-13 23:09 
GeneralMy vote of 5 Pinmemberbabatudor4-Jul-13 23:13 
GeneralMy vote of 5 PinmemberAayushi Jain2-Jun-13 1:52 
GeneralMy vote of 5 PinmemberSaumitra Kumar Paul3-Dec-12 4:52 
very strait forward, simple and cool article.
GeneralMy vote of 5 Pinmemberqiubo22-Oct-12 18:45 
GeneralMy vote of 5 PinmemberMrJamesTK2-Aug-12 7:13 
GeneralMy vote of 5 Pinmemberhyperlinx27-Sep-11 22:51 
GeneralMy vote of 5 Pinmembersconnor1-Jul-11 10:16 
GeneralClear and concise Pinmemberla0116-Jun-10 12:11 
GeneralRe: Clear and concise PinmemberRudi Breedenraedt16-Jun-10 12:20 
Questionplz reply PinmemberNazneen.Insignia26-Aug-08 0:32 
GeneralJust to be sure! PinmemberIngenious00119-Jun-08 1:53 
GeneralRe: Just to be sure! PinmemberIngenious00119-Jun-08 3:18 
GeneralRe: Just to be sure! PinmemberRudi Breedenraedt19-Jun-08 7:46 
QuestionSet EventArgs PinmemberkhTee6-May-08 22:37 
Generalsystem wide Pinmemberstyloverte11615-Apr-08 17:04 
GeneralRe: system wide PinmemberRudi Breedenraedt20-Apr-08 0:13 
Generalbetter question Pinmemberlew2627-Sep-07 9:32 
GeneralRe: better question PinmemberRudi Breedenraedt27-Sep-07 19:52 
GeneralQuestion about sender class Pinmemberlew2627-Sep-07 7:43 
GeneralRe: Question about sender class PinmemberRudi Breedenraedt27-Sep-07 20:03 
GeneralRe: Question about sender class PinmemberMember 823782325-Aug-13 0:50 
GeneralThanks! Pinmembersnached16-Oct-06 15:57 
GeneralGoooood! Pinmemberksysiu21-Jul-05 22:17 
Generali like things in simple & straight means PinmemberUnruled Boy1-Jun-05 17:37 
GeneralError + suggestion Pinmemberdog_spawn23-Sep-03 13:21 
GeneralRe: Error + suggestion PinmemberRudi Breedenraedt25-Sep-03 5:34 
GeneralRe: Error + suggestion Pinmemberdog_spawn25-Sep-03 6:56 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.140415.2 | Last Updated 23 Sep 2003
Article Copyright 2003 by Rudi Breedenraedt
Everything else Copyright © CodeProject, 1999-2014
Terms of Use
Layout: fixed | fluid