How to handle a control event (Windows Forms .NET)

Article
07/30/2021

Events for controls (and for forms) are generally set through the Visual Studio Visual Designer for Windows Forms. Setting an event through the Visual Designer is known as handling an event at design-time. You can also handle events dynamically in code, known as handling events at run-time. An event created at run-time allows you to connect event handlers dynamically based on what your app is currently doing.

Important

The Desktop Guide documentation for .NET 7 and .NET 6 is under construction.

Handle an event - designer

In Visual Studio, use the Visual Designer to manage handlers for control events. The Visual Designer will generate the handler code and add it to the event for you.

Set the handler

Use the Properties pane to add or set the handler of an event:

Open the Visual Designer of the form containing the control to change.
Select the control.
Change the Properties pane mode to Events by pressing the events button ( ).
Find the event you want to add a handler to, for example, the Click event:
Do one of the following:
- Double-click the event to generate a new handler, it's blank if no handler is assigned. If it's not blank, this action opens the code for the form and navigates to the existing handler.
- Use the selection box ( ) to choose an existing handler.
  
  The selection box will list all methods that have a compatible method signature for the event handler.

Clear the handler

To remove an event handler, you can't just delete handler code that is in the form's code-behind file, it's still referenced by the event. Use the Properties pane to remove the handler of an event:

Open the Visual Designer of the form containing the control to change.
Select the control.
Change the Properties pane mode to Events by pressing the events button ( ).
Find the event containing the handler you want to remove, for example, the Click event:
Right-click on the event and choose Reset.

Handle an event - code

You typically add event handlers to controls at design-time through the Visual Designer. You can, though, create controls at run-time, which requires you to add event handlers in code. Adding handlers in code also gives you the chance to add multiple handlers to the same event.

Add a handler

The following example shows how to create a control and add an event handler. This control is created in the Button.Click event handler a different button. When Button1 is pressed. The code moves and sizes a new button. The new button's Click event is handled by the MyNewButton_Click method. To get the new button to appear, it's added to the form's Controls collection. There's also code to remove the Button1.Click event's handler, this is discussed in the Remove the handler section.

private void button1_Click(object sender, EventArgs e)
{
    // Create and add the button
    Button myNewButton = new()
    {
        Location = new Point(10, 10),
        Size = new Size(120, 25),
        Text = "Do work"
    };

    // Handle the Click event for the new button
    myNewButton.Click += MyNewButton_Click;
    this.Controls.Add(myNewButton);

    // Remove this button handler so the user cannot do this twice
    button1.Click -= button1_Click;
}

private void MyNewButton_Click(object sender, EventArgs e)
{
    
}

Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
    'Create and add the button
    Dim myNewButton As New Button() With {.Location = New Point(10, 10),
                                          .Size = New Size(120, 25),
                                          .Text = "Do work"}

    'Handle the Click event for the new button
    AddHandler myNewButton.Click, AddressOf MyNewButton_Click
    Me.Controls.Add(myNewButton)

    'Remove this button handler so the user cannot do this twice
    RemoveHandler Button1.Click, AddressOf Button1_Click
End Sub

Private Sub MyNewButton_Click(sender As Object, e As EventArgs)

End Sub

To run this code, do the following to a form with the Visual Studio Visual Designer:

Add a new button to the form and name it Button1.
Change the Properties pane mode to Events by pressing the event button ( ).
Double-click the Click event to generate a handler. This action opens the code window and generates a blank Button1_Click method.
Replace the method code with the previous code above.

For more information about C# events, see Events (C#) For more information about Visual Basic events, see Events (Visual Basic)

Remove the handler

The Add a handler section used some code to demonstrate adding a handler. That code also contained a call to remove a handler:

button1.Click -= button1_Click;

RemoveHandler Button1.Click, AddressOf Button1_Click

This syntax can be used to remove any event handler from any event.

For more information about C# events, see Events (C#) For more information about Visual Basic events, see Events (Visual Basic)

How to use multiple events with the same handler

With the Visual Studio Visual Designer's Properties pane, you can select the same handler already in use by a different event. Follow the directions in the Set the handler section to select an existing handler instead of creating a new one.

In C#, the handler is attached to a control's event in the form's designer code, which changed through the Visual Designer. For more information about C# events, see Events (C#)

Visual Basic

In Visual Basic, the handler is attached to a control's event in the form's code-behind file, where the event handler code is declared. Multiple Handles keywords can be added to the event handler code to use it with multiple events. The Visual Designer will generate the Handles keyword for you and add it to the event handler. However, you can easily do this yourself to any control's event and event handler, as long as the signature of the handler method matches the event. For more information about Visual Basic events, see Events (Visual Basic)

This code demonstrates how the same method can be used as a handler for two different Button.Click events:

Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click, Button2.Click
    'Do some work to handle the events
End Sub