|
| 1 | +--- |
| 2 | +title: How to add or remove an event handler |
| 3 | +description: Learn how to create an event handler at design-time with the Windows Forms Designer in Visual Studio or at run-time. |
| 4 | +ms.date: 07/16/2021 |
| 5 | +dev_langs: |
| 6 | + - "csharp" |
| 7 | + - "vb" |
| 8 | +helpviewer_keywords: |
| 9 | + - "Windows Forms, event handling" |
| 10 | + - "event handlers [Windows Forms], creating" |
| 11 | + - "run time [Windows Forms], creating event handlers at" |
| 12 | + - "examples [Windows Forms], event handling" |
| 13 | + - "Button control [Windows Forms], event handlers" |
| 14 | + - "events [Windows Forms], connecting multiple to single event handler" |
| 15 | + - "event handlers [Windows Forms], connecting events to" |
| 16 | + - "menus [Windows Forms], event-handling methods for multiple menu items" |
| 17 | + - "Windows Forms controls, events" |
| 18 | + - "menu items [Windows Forms], multicasting event-handling methods" |
| 19 | +--- |
| 20 | + |
| 21 | +# How to handle an event (Windows Forms .NET) |
| 22 | + |
| 23 | +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. |
| 24 | + |
| 25 | +[!INCLUDE [desktop guide under construction](../../includes/desktop-guide-preview-note.md)] |
| 26 | + |
| 27 | +## Handle an event - designer |
| 28 | + |
| 29 | +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. |
| 30 | + |
| 31 | +### Set the handler |
| 32 | + |
| 33 | +Use the **Properties** pane to add or set the handler of an event: |
| 34 | + |
| 35 | +01. Open the Visual Designer of the form containing the control to change. |
| 36 | +01. Select the control. |
| 37 | +01. Change the **Properties** pane mode to **Events** by pressing the events button (:::image type="icon" source="../media/shared/visual-studio-events-button.png" border="false":::). |
| 38 | +01. Find the event you want to add a handler to, for example, the **Click** event: |
| 39 | + |
| 40 | + :::image type="content" source="media/how-to-add-an-event-handler/visual-studio-properties-events-click.png" alt-text="Visual Studio properties pane shown with the events mode enabled and the click event."::: |
| 41 | + |
| 42 | +01. Do one of the following: |
| 43 | + |
| 44 | + - 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. |
| 45 | + |
| 46 | + - Use the selection box (:::image type="icon" source="../media/shared/visual-studio-chevron-button.png" border="false":::) to choose an existing handler. |
| 47 | + |
| 48 | + The selection box will list all methods that have a compatible method signature for the event handler. |
| 49 | + |
| 50 | +### Clear the handler |
| 51 | + |
| 52 | +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: |
| 53 | + |
| 54 | +01. Open the Visual Designer of the form containing the control to change. |
| 55 | +01. Select the control. |
| 56 | +01. Change the **Properties** pane mode to **Events** by pressing the events button (:::image type="icon" source="../media/shared/visual-studio-events-button.png" border="false":::). |
| 57 | +01. Find the event containing the handler you want to remove, for example, the **Click** event: |
| 58 | + |
| 59 | + :::image type="content" source="media/how-to-add-an-event-handler/visual-studio-properties-events-click.png" alt-text="Visual Studio properties pane shown with the events mode enabled and the click event."::: |
| 60 | + |
| 61 | +01. Right-click on the event and choose **Reset**. |
| 62 | + |
| 63 | +## Handle an event - code |
| 64 | + |
| 65 | +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. |
| 66 | + |
| 67 | +### Add a handler |
| 68 | + |
| 69 | +The following example shows how to create a control and add an event handler. This control is created in the [`Button.Click`](xref:System.Windows.Forms.Control.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](#remove-the-handler) section. |
| 70 | + |
| 71 | +:::code language="csharp" source="snippets/how-to-add-an-event-handler/cs/Form1.cs" id="HandlerViaCode" highlight="12"::: |
| 72 | +:::code language="vb" source="snippets/how-to-add-an-event-handler/vb/Form1.vb" id="HandlerViaCode" highlight="8"::: |
| 73 | + |
| 74 | +To run this code, do the following to a form with the Visual Studio Visual Designer: |
| 75 | + |
| 76 | +01. Add a new button to the form and name it **Button1**. |
| 77 | +01. Change the **Properties** pane mode to **Events** by pressing the event button (:::image type="icon" source="../media/shared/visual-studio-events-button.png" border="false":::). |
| 78 | +01. Double-click the **Click** event to generate a handler. This action opens the code window and generates a blank `Button1_Click` method. |
| 79 | +01. Replace the method code with the previous code above. |
| 80 | + |
| 81 | +For more information about C# events, see [Events (C#)](/dotnet/csharp/programming-guide/events/) |
| 82 | +For more information about Visual Basic events, see [Events (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/events/) |
| 83 | + |
| 84 | +### Remove the handler |
| 85 | + |
| 86 | +The [Add a handler](#add-a-handler) section used some code to demonstrate adding a handler. That code also contained a call to remove a handler: |
| 87 | + |
| 88 | +:::code language="csharp" source="snippets/how-to-add-an-event-handler/cs/Form1.cs" id="RemoveHandler"::: |
| 89 | +:::code language="vb" source="snippets/how-to-add-an-event-handler/vb/Form1.vb" id="RemoveHandler"::: |
| 90 | + |
| 91 | +This syntax can be used to remove any event handler from any event. |
| 92 | + |
| 93 | +For more information about C# events, see [Events (C#)](/dotnet/csharp/programming-guide/events/) |
| 94 | +For more information about Visual Basic events, see [Events (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/events/) |
| 95 | + |
| 96 | +## How to use multiple events with the same handler |
| 97 | + |
| 98 | +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](#set-the-handler) section to select an existing handler instead of creating a new one. |
| 99 | + |
| 100 | +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#)](/dotnet/csharp/programming-guide/events/) |
| 101 | + |
| 102 | +### Visual Basic |
| 103 | + |
| 104 | +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)](/dotnet/visual-basic/programming-guide/language-features/events/) |
| 105 | + |
| 106 | +This code demonstrates how the same method can be used as a handler for two different [`Button.Click`](xref:System.Windows.Forms.Control.Click) events: |
| 107 | + |
| 108 | +:::code language="vb" source="snippets/how-to-add-an-event-handler/vb/Form2.vb" id="MultipleHandlers"::: |
| 109 | + |
| 110 | +## See also |
| 111 | + |
| 112 | +- [Control events](events.md) |
| 113 | +- [Events overview](../forms/events.md) |
| 114 | +- [Using mouse events](../input-mouse/events.md) |
| 115 | +- [Using keyboard events](../input-keyboard/events.md) |
| 116 | +- <xref:System.Windows.Forms.Button?displayProperty=fullName> |
0 commit comments