From 5b739c12cb196b31579951d82cc97562bc9fc60f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Sep 2025 18:46:01 +0000 Subject: [PATCH 1/4] Initial plan From 6321efedb0d65e1313f1778dc3e469883655f41e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Sep 2025 18:54:51 +0000 Subject: [PATCH 2/4] Fix event handler documentation terminology and update references Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> --- docs/visual-basic/misc/bc33003.md | 2 +- ...-procedure-that-does-not-return-a-value.md | 2 +- .../how-to-call-an-event-handler.md | 28 ++++++++++++------- .../procedures/sub-procedures.md | 2 +- .../language-features/procedures/toc.yml | 2 +- 5 files changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/visual-basic/misc/bc33003.md b/docs/visual-basic/misc/bc33003.md index f5264583b628d..db297fd4a8b41 100644 --- a/docs/visual-basic/misc/bc33003.md +++ b/docs/visual-basic/misc/bc33003.md @@ -13,7 +13,7 @@ ms.assetid: 8336402c-9393-4e8e-834d-55c2268f24f6 An [Operator Statement](../language-reference/statements/operator-statement.md) specifies the [Handles](../language-reference/statements/handles-clause.md) keyword. - Only a `Sub` procedure can handle events. An `Operator` procedure cannot. For more information on event handlers, see [How to: Call an Event Handler in Visual Basic](../programming-guide/language-features/procedures/how-to-call-an-event-handler.md). + Only a `Sub` procedure can handle events. An `Operator` procedure cannot. For more information on event handlers, see [How to: Subscribe to Events and Handle Them in Visual Basic](../programming-guide/language-features/procedures/how-to-call-an-event-handler.md). An `Operator` procedure requires both the `Public` and `Shared` keywords, and a conversion operator requires either the `Widening` or the `Narrowing` keyword. For more information, see [Operator Procedures](../programming-guide/language-features/procedures/operator-procedures.md). diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-does-not-return-a-value.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-does-not-return-a-value.md index fe9775993c0ea..e23de4b4314d4 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-does-not-return-a-value.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-does-not-return-a-value.md @@ -34,4 +34,4 @@ A `Sub` procedure does not return a value to the calling code. You call it expli - [Sub Statement](../../../language-reference/statements/sub-statement.md) - [How to: Create a Procedure](./how-to-create-a-procedure.md) - [How to: Call a Procedure That Returns a Value](./how-to-call-a-procedure-that-returns-a-value.md) -- [How to: Call an Event Handler in Visual Basic](./how-to-call-an-event-handler.md) +- [How to: Subscribe to Events and Handle Them in Visual Basic](./how-to-call-an-event-handler.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md index c3ee03c3860ea..fad4b295f2d4f 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md @@ -1,27 +1,35 @@ --- -description: "Learn more about: How to call an event handler in Visual Basic" -title: How to call an event handler +description: "Learn more about: How to subscribe to events and handle them in Visual Basic" +title: How to subscribe to events and handle them ms.date: 07/20/2015 helpviewer_keywords: - "Visual Basic code, procedures" - - "event handlers [Visual Basic], calling" + - "event handlers [Visual Basic], subscribing" - "event handlers" - "procedures [Visual Basic], event handlers" - - "procedures [Visual Basic], calling" + - "events [Visual Basic], subscribing" no-loc: [WithEvents] ms.assetid: 72e18ef8-144e-40df-a1f4-066a57271e28 --- -# How to call an event handler in Visual Basic +# How to subscribe to events and handle them in Visual Basic An *event* is an action or occurrence — such as a mouse click or a credit limit exceeded — that is recognized by some program component, and for which you can write code to respond. An *event handler* is the code you write to respond to an event. -An event handler in Visual Basic is a `Sub` procedure. However, you do not normally call it the same way as other `Sub` procedures. Instead, you identify the procedure as a handler for the event. You can do this either with a [`Handles`](../../../language-reference/statements/handles-clause.md) clause and a [`WithEvents`](../../../language-reference/modifiers/withevents.md) variable, or with an [AddHandler Statement](../../../language-reference/statements/addhandler-statement.md). Using a `Handles` clause is the default way to declare an event handler in Visual Basic. This is the way the event handlers are written by the designers when you program in the integrated development environment (IDE). The `AddHandler` statement is suitable for raising events dynamically at run time. +In Visual Basic, there are two sides to working with events: + +1. **Event publishing** — Classes declare events and raise them when something interesting happens using the [RaiseEvent Statement](../../../language-reference/statements/raiseevent-statement.md). This is what actually invokes (calls) the event handlers. + +2. **Event subscription** — You subscribe to events by identifying procedures as handlers for specific events. You can do this either with a [`Handles`](../../../language-reference/statements/handles-clause.md) clause and a [`WithEvents`](../../../language-reference/modifiers/withevents.md) variable, or with an [AddHandler Statement](../../../language-reference/statements/addhandler-statement.md). + +An event handler in Visual Basic is a `Sub` procedure. However, you do not normally call it directly like other `Sub` procedures. Instead, you subscribe the procedure to an event, and Visual Basic automatically calls the event handler when the event is raised. + +Using a `Handles` clause is the default way to subscribe to events in Visual Basic. This is how event handlers are written by the designers when you program in the integrated development environment (IDE). The `AddHandler` statement is suitable for subscribing to events dynamically at run time. When the event occurs, Visual Basic automatically calls the event handler procedure. Any code that has access to the event can cause it to occur by executing a [RaiseEvent Statement](../../../language-reference/statements/raiseevent-statement.md). You can associate more than one event handler with the same event. In some cases you can dissociate a handler from an event. For more information, see [Events](../events/index.md). -## Call an event handler using :::no-loc text="Handles"::: and WithEvents +## Subscribe to an event using :::no-loc text="Handles"::: and WithEvents 1. Make sure the event is declared with an [Event Statement](../../../language-reference/statements/event-statement.md). @@ -29,19 +37,19 @@ You can associate more than one event handler with the same event. In some cases 3. In the declaration of the event-handling `Sub` procedure, add a [`Handles`](../../../language-reference/statements/handles-clause.md) clause that specifies the `WithEvents` variable and the event name. -4. When the event occurs, Visual Basic automatically calls the `Sub` procedure. Your code can use a `RaiseEvent` statement to make the event occur. +4. When the event occurs, Visual Basic automatically calls the `Sub` procedure. Your code can use a `RaiseEvent` statement to raise the event and trigger all subscribed handlers. The following example defines an event and a `WithEvents` variable that refers to the class that raises the event. The event-handling `Sub` procedure uses a `Handles` clause to specify the class and event it handles. :::code language="vb" source="snippets/how-to-call-an-event-handler/SpecialForm.vb" id="4"::: -## Call an event handler using AddHandler +## Subscribe to an event using AddHandler 1. Make sure the event is declared with an `Event` statement. 2. Execute an [AddHandler statement](../../../language-reference/statements/addhandler-statement.md) to dynamically connect the event-handling `Sub` procedure with the event. -3. When the event occurs, Visual Basic automatically calls the `Sub` procedure. Your code can use a `RaiseEvent` statement to make the event occur. +3. When the event occurs, Visual Basic automatically calls the `Sub` procedure. Your code can use a `RaiseEvent` statement to raise the event and trigger all subscribed handlers. The following example uses the [AddHandler statement](../../../language-reference/statements/addhandler-statement.md) in the constructor to associate the `OnTimerElapsed` procedure as an event handler for a custom timer event. diff --git a/docs/visual-basic/programming-guide/language-features/procedures/sub-procedures.md b/docs/visual-basic/programming-guide/language-features/procedures/sub-procedures.md index 4d0f0765ddb8a..d42e0c2cf3c75 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/sub-procedures.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/sub-procedures.md @@ -90,4 +90,4 @@ The following example shows a typical call to `tellOperator`. - [Procedure Parameters and Arguments](./procedure-parameters-and-arguments.md) - [Sub Statement](../../../language-reference/statements/sub-statement.md) - [How to: Call a Procedure that Does Not Return a Value](./how-to-call-a-procedure-that-does-not-return-a-value.md) -- [How to: Call an Event Handler in Visual Basic](./how-to-call-an-event-handler.md) +- [How to: Subscribe to Events and Handle Them in Visual Basic](./how-to-call-an-event-handler.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/toc.yml b/docs/visual-basic/programming-guide/language-features/procedures/toc.yml index fa05a91b1c43b..e7a08fdc89f09 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/toc.yml +++ b/docs/visual-basic/programming-guide/language-features/procedures/toc.yml @@ -8,7 +8,7 @@ items: - name: "How to: Call a Procedure that Does Not Return a Value" href: how-to-call-a-procedure-that-does-not-return-a-value.md - - name: "How to: Call an Event Handler" + - name: "How to: Subscribe to Events and Handle Them" href: how-to-call-an-event-handler.md - name: Function Procedures href: function-procedures.md From e7ea437d93392013eb91519ef8b58beb1bfe34ac Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 10 Sep 2025 10:19:00 -0400 Subject: [PATCH 3/4] Apply suggestions from code review --- .../procedures/how-to-call-an-event-handler.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md index fad4b295f2d4f..6c9e94f236731 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md @@ -21,7 +21,7 @@ In Visual Basic, there are two sides to working with events: 2. **Event subscription** — You subscribe to events by identifying procedures as handlers for specific events. You can do this either with a [`Handles`](../../../language-reference/statements/handles-clause.md) clause and a [`WithEvents`](../../../language-reference/modifiers/withevents.md) variable, or with an [AddHandler Statement](../../../language-reference/statements/addhandler-statement.md). -An event handler in Visual Basic is a `Sub` procedure. However, you do not normally call it directly like other `Sub` procedures. Instead, you subscribe the procedure to an event, and Visual Basic automatically calls the event handler when the event is raised. +An event handler in Visual Basic is a `Sub` procedure. Your code doesn't call it directly like other `Sub` procedures. Instead, event publishers invoke the procedure when the event is raised because the procedure is subscribed to the event. Using a `Handles` clause is the default way to subscribe to events in Visual Basic. This is how event handlers are written by the designers when you program in the integrated development environment (IDE). The `AddHandler` statement is suitable for subscribing to events dynamically at run time. @@ -37,7 +37,7 @@ You can associate more than one event handler with the same event. In some cases 3. In the declaration of the event-handling `Sub` procedure, add a [`Handles`](../../../language-reference/statements/handles-clause.md) clause that specifies the `WithEvents` variable and the event name. -4. When the event occurs, Visual Basic automatically calls the `Sub` procedure. Your code can use a `RaiseEvent` statement to raise the event and trigger all subscribed handlers. +4. When the event occurs, Visual Basic automatically calls the `Sub` procedure. Your code can use a `RaiseEvent` statement to raise the event and invoke all subscribed handlers. The following example defines an event and a `WithEvents` variable that refers to the class that raises the event. The event-handling `Sub` procedure uses a `Handles` clause to specify the class and event it handles. @@ -49,7 +49,7 @@ You can associate more than one event handler with the same event. In some cases 2. Execute an [AddHandler statement](../../../language-reference/statements/addhandler-statement.md) to dynamically connect the event-handling `Sub` procedure with the event. -3. When the event occurs, Visual Basic automatically calls the `Sub` procedure. Your code can use a `RaiseEvent` statement to raise the event and trigger all subscribed handlers. +3. When the event occurs, Visual Basic automatically calls the `Sub` procedure. Your code can use a `RaiseEvent` statement to raise the event and invoke all subscribed handlers. The following example uses the [AddHandler statement](../../../language-reference/statements/addhandler-statement.md) in the constructor to associate the `OnTimerElapsed` procedure as an event handler for a custom timer event. From 34fe062f7098a2afdc77d5f939f0282621e786cb Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 11 Sep 2025 10:17:53 -0400 Subject: [PATCH 4/4] Apply suggestions from code review --- .../procedures/how-to-call-an-event-handler.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md index 6c9e94f236731..4a3e9e1e11f3a 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-an-event-handler.md @@ -17,9 +17,8 @@ An *event* is an action or occurrence — such as a mouse click or a credit limi In Visual Basic, there are two sides to working with events: -1. **Event publishing** — Classes declare events and raise them when something interesting happens using the [RaiseEvent Statement](../../../language-reference/statements/raiseevent-statement.md). This is what actually invokes (calls) the event handlers. - -2. **Event subscription** — You subscribe to events by identifying procedures as handlers for specific events. You can do this either with a [`Handles`](../../../language-reference/statements/handles-clause.md) clause and a [`WithEvents`](../../../language-reference/modifiers/withevents.md) variable, or with an [AddHandler Statement](../../../language-reference/statements/addhandler-statement.md). +- **Event publishing** — Classes declare events and raise them when something interesting happens using the [RaiseEvent Statement](../../../language-reference/statements/raiseevent-statement.md). This is what actually invokes (calls) the event handlers. +- **Event subscription** — You subscribe to events by identifying procedures as handlers for specific events. You can do this either with a [`Handles`](../../../language-reference/statements/handles-clause.md) clause and a [`WithEvents`](../../../language-reference/modifiers/withevents.md) variable, or with an [AddHandler Statement](../../../language-reference/statements/addhandler-statement.md). An event handler in Visual Basic is a `Sub` procedure. Your code doesn't call it directly like other `Sub` procedures. Instead, event publishers invoke the procedure when the event is raised because the procedure is subscribed to the event.