How to add an event to a UserControl in C#?

Question

First, you need to declare the event within your class (alongside your methods and constructors):

public event EventHandler LabelsTextChanged;

Then you need to create a method to handle the individual labels’ TextChanged events.

private void HandleLabelTextChanged(object sender, EventArgs e)
{
    // we'll explain this in a minute
    this.OnLabelsTextChanged(EventArgs.Empty);
}

Somewhere, probably in your control’s constructor, you need to subscribe to the label’s TextChanged events.

myLabel1.TextChanged += this.HandleLabelTextChanged;
myLabel2.TextChanged += this.HandleLabelTextChanged;
myLabel3.TextChanged += this.HandleLabelTextChanged;

Now for the HandleLabelsTextChanged method. We could raise LabelsTextChanged directly; however, the .NET framework design guidelines say that is it a best practice to create an OnEventName protected virtual method to raise the event for us. That way, inheriting classes can “handle” the event by overriding the OnEventName method, which turns out to have a little better performance than subscribing to the event. Even if you think you will never override the OnEventName method, it is a good idea to get in the habit of doing it anyway, as it simplifies the event raising process.

Here’s our OnLabelsTextChanged:

protected virtual void OnLabelsTextChanged(EventArgs e)
{
    EventHandler handler = this.LabelsTextChanged;
    if (handler != null)
    {
        handler(this, e);
    }
}

We have to check for null because an event without subscribers is null. If we attempted to raise a null event, we would get a NullReferenceException. Note that we copy the event’s EventHandler to a local variable before checking it for null and raising the event. If we had instead done it like this:

if (this.LabelsTextChanged != null)
{
    this.LabelsTextChanged(this, e);
}

We would have a race condition between the nullity check and the event raising. If it just so happened that the subscribers to the event unsubscribed themselves just before we raised the event but after we checked for null, an exception would be thrown. You won’t normally encounter this issue, but it is best to get in the habit of writing it the safe way.

Edit: Here is how the public event EventHandler LabelsTextChanged; line should be placed:

namespace YourNamespace
{
    class MyUserControl : UserControl
    {
        // it needs to be here:
        public event EventHandler LabelsTextChanged;

        ...
    }
}

Here are the framework design guidelines on event design for further reading.

Leave a Comment Cancel reply