Events Using Your Own Code in VB.NET
When Visual Basic first emerged onto the programming scene ... (we're talking "age of dinosaurs" now) ... it was called event oriented programming and you still see that description used sometimes. That's a testament to how important events are to every part of programming as it's done today. I think it's as important as John Von Neuman's "stored program concept" back in 1945. (That's before the dinosaurs!)
About Visual Basic has a number of articles that cover different parts of event-oriented programming ...
-> Handling Events in VB.NET
-> Program and Handle Your Own Unique Event
-> Creating Your Own Event Code
-> Using Delegates for Runtime Flexibility
-> Shared Events in VB.NET
Taken together, these cover most of the subject. But you have to put the pieces together yourself to get the whole picture. And they generally use Framework objects - like Button and Timer - to illustrate the use of events. This is the first of a two article series that builds the whole thing in one place and uses a class that is coded inside the example program so you can be sure that nothing is hidden. Part Two, Using the Custom Event Keyword, builds on this same theme by explaining how really custom events work.
The example program used in this article is inspired by a problem brought to an "in person" programming class I taught at a college recently. "Ralph" helped manage a table tennis tournament and wanted to upgrade some VB programs he used.
So this program keeps score for one match in the tournament. The "event" that is coded happens when a player wins the match.
In addition to a complete, custom coded event, you might also be interested in this article as an example of ...
-> The use of an XML file to persist data
-> LINQ to XML to read and write the XML file
-> And, of course, the use of a custom class, which is simply another way of describing custom event code
Because a lot of people will just want to get to example code without wading through a lot of text, here's the complete program, followed by the XML file. Explanation will follow.
The example only has one form, shown below:
--------
Click Here to display the illustration
--------
The example starts with two players who will face off in a table tennis match. In a more practical application, these two players will also be in a data file (possibly an XML file to match the scores maintained in this file). In this example, string values for the two players ("George" and "Arthur") are simply hard coded.
The next statement ...
... is a requirement for setting up a custom event. "theMatch" is coded later as an instance of the custom class, "TableTennisMatch". The keyword "WithEvents" tells the compiler to add code to the instance of a class that is created ...
... later in the code. This is why WithEvents variables must be coded at the class level. This code added by the compiler will insert messages into the Windows "message pump" so another piece of code can be automatically called when the event occurs. The code that is called is identified by the Handles keyword ...
This is the custom event code that is the topic item of this article. The article Creating Your Own Event Code goes into more detail about this.
As an added example, the code also shows how easy it is to load, read, and update an XML file using the very SQL-like syntax of LINQ to XML introduced in Framework 3.5.
The event that signals when a match is won or lost is raised in the instantiated class TableTennisMatch. This class keeps track of the score in properties and whenever the score is changed, it checks to see if the game is over. If it is, the MatchWon() event is raised with a type Integer parameter that tells the code handling the event (Record_WinLoss) which player won the match. This code updates the XML file, announces the win, and disables the buttons.
The following illustration shows the event related code and how statements in the two classes tie together ... in this version.
--------
Click Here to display the illustration
--------
An alternative way to code this solution would be to explicitly code a delegate. I decided to put it completely outside the existing classes. That way, the scope would include those classes. I also coded the instantiation of the class, TableTennisMatch, as part of the TTMatchControl class rather than the form where it's used.
To wireup the event handler to the event, I used an AddHandler statement instead of the Handles clause on the event handler subroutine itself.
Then the Event itself refers to the delegate - MatchWon As MatchWonHandler - rather than specifying a hardcoded parameter - MatchWon(whoWon As Integer).
The use of a delegate and the AddHandler statement gives you extra flexibility. Although this example is a little 'forced' to match the table tennis metaphor I'm using, you could add two event handlers now, one for the players and another to signal that the table is available for another match. Since the first parameter will signal which player won, I added another parameter for the table.
Then both handlers have to be added, not just one. The AddHandler statement is a little bit unusual in the way it works here. A linked list of all handlers that have been added is maintained by VB.NET and executed one at a time. In some cases, this can be a problem because later handlers won't run until earlier ones finish and this can be a blocking problem. I'll cover this a bit more in the second part of this series.
The RaiseEvent statement has to be modified.
Finally, another event processing subroutine has to be present. In this case, I just added text to a label, but a complete system to update a "table" database and possibly raise another event could be coded here.
--------
Click Here to display the illustration
--------
VB.NET actually handles all events in pretty much the same way, but with most options, much of the code that makes it work is added by the compiler and isn't shown. You can add your own code to replace this automatic code, but understanding how it ties together isn't obvious ... and (Surprise!) Microsoft's documentation doesn't help a lot. Part Two of this series covers some of these mysteries and explains how the "Custom" keywork in declaring your event changes things.
To continue this series: Using the Custom Event Keyword
About Visual Basic has a number of articles that cover different parts of event-oriented programming ...
-> Handling Events in VB.NET
-> Program and Handle Your Own Unique Event
-> Creating Your Own Event Code
-> Using Delegates for Runtime Flexibility
-> Shared Events in VB.NET
Taken together, these cover most of the subject. But you have to put the pieces together yourself to get the whole picture. And they generally use Framework objects - like Button and Timer - to illustrate the use of events. This is the first of a two article series that builds the whole thing in one place and uses a class that is coded inside the example program so you can be sure that nothing is hidden. Part Two, Using the Custom Event Keyword, builds on this same theme by explaining how really custom events work.
The example program used in this article is inspired by a problem brought to an "in person" programming class I taught at a college recently. "Ralph" helped manage a table tennis tournament and wanted to upgrade some VB programs he used.
So this program keeps score for one match in the tournament. The "event" that is coded happens when a player wins the match.
In addition to a complete, custom coded event, you might also be interested in this article as an example of ...
-> The use of an XML file to persist data
-> LINQ to XML to read and write the XML file
-> And, of course, the use of a custom class, which is simply another way of describing custom event code
Because a lot of people will just want to get to example code without wading through a lot of text, here's the complete program, followed by the XML file. Explanation will follow.
Public Class TTMatchControlDim PlayerA As String = "George"Dim PlayerB As String = "Arthur"Private WithEvents theMatch As TableTennisMatchPrivate Sub Form1_Load(sender As System.Object,e As System.EventArgs) Handles MyBase.LoadtheMatch = New TableTennisMatchlblPlayerA.Text = PlayerAlblPlayerB.Text = PlayerBDim PStats = XElement.Load("..\..\PlayerStats.xml")Dim pStat =From p In PStats.<PStat>Select pWhere p.<PID>.Value = PlayerAlblPlayerAWins.Text = pStat.<Won>.ValuepStat =From p In PStats.<PStat>Select pWhere p.<PID>.Value = PlayerBlblPlayerBWins.Text = pStat.<Won>.ValueEnd SubPrivate Sub btnAddPointA_Click(sender As System.Object,e As System.EventArgs) Handles btnAddPointA.ClicktheMatch.UpdateScore(0)lblPlayerAScore.Text =CStr(theMatch.PlayerAScore)End SubPrivate Sub btnAddPointB_Click(sender As System.Object,e As System.EventArgs) Handles btnAddPointB.ClicktheMatch.UpdateScore(1)lblPlayerBScore.Text =CStr(theMatch.PlayerBScore)End SubPublic Sub Record_WinLoss(ByVal ww As Integer) Handles theMatch.MatchWonDim PStats =XElement.Load("..\..\PlayerStats.xml")Dim pStatA =From p In PStats.<PStat>Select pWhere p.<PID>.Value = PlayerADim pStatB =From p In PStats.<PStat>Select pWhere p.<PID>.Value = PlayerBIf ww = 0 ThenpStatA.<Won>.Value += 1pStatB.<Lost>.Value += 1lblPlayerWon.Text = PlayerA & " Wins!"ElsepStatB.<Won>.Value += 1pStatA.<Lost>.Value += 1lblPlayerWon.Text = PlayerB & " Wins!"End IfPStats.Save("..\..\PlayerStats.xml")lblPlayerBWins.Text = pStatB.<Won>.ValuelblPlayerAWins.Text = pStatA.<Won>.ValuebtnAddPointA.Enabled = FalsebtnAddPointB.Enabled = FalseEnd SubEnd ClassPublic Class TableTennisMatchEvent MatchWon(whoWon As Integer)Property PlayerAScore As IntegerProperty PlayerBScore As IntegerPublic Sub UpdateScore(ByVal pNum As Integer)If pNum = 0 ThenPlayerAScore += 1ElsePlayerBScore += 1End IfIf PlayerAScore > 20 ThenIf PlayerAScore >PlayerBScore + 1 ThenRaiseEvent MatchWon(0)End IfEnd IfIf PlayerBScore > 20 ThenIf PlayerBScore >PlayerAScore + 1 ThenRaiseEvent MatchWon(1)End IfEnd IfEnd SubEnd ClassThe XML file ... (PlayerStats.xml)<?xml version="1.0" encoding="utf-8"?><PStats><PStat><PID>George</PID><Won>17</Won><Lost>8</Lost></PStat><PStat><PID>Arthur</PID><Won>9</Won><Lost>20</Lost></PStat></PStats>The example only has one form, shown below:
--------
Click Here to display the illustration
--------
The example starts with two players who will face off in a table tennis match. In a more practical application, these two players will also be in a data file (possibly an XML file to match the scores maintained in this file). In this example, string values for the two players ("George" and "Arthur") are simply hard coded.
The next statement ...
Private WithEvents theMatch As TableTennisMatch... is a requirement for setting up a custom event. "theMatch" is coded later as an instance of the custom class, "TableTennisMatch". The keyword "WithEvents" tells the compiler to add code to the instance of a class that is created ...
theMatch = New TableTennisMatch... later in the code. This is why WithEvents variables must be coded at the class level. This code added by the compiler will insert messages into the Windows "message pump" so another piece of code can be automatically called when the event occurs. The code that is called is identified by the Handles keyword ...
Public Sub Record_WinLoss(ByVal ww As Integer) Handles theMatch.MatchWonThis is the custom event code that is the topic item of this article. The article Creating Your Own Event Code goes into more detail about this.
As an added example, the code also shows how easy it is to load, read, and update an XML file using the very SQL-like syntax of LINQ to XML introduced in Framework 3.5.
The event that signals when a match is won or lost is raised in the instantiated class TableTennisMatch. This class keeps track of the score in properties and whenever the score is changed, it checks to see if the game is over. If it is, the MatchWon() event is raised with a type Integer parameter that tells the code handling the event (Record_WinLoss) which player won the match. This code updates the XML file, announces the win, and disables the buttons.
The following illustration shows the event related code and how statements in the two classes tie together ... in this version.
--------
Click Here to display the illustration
--------
An alternative way to code this solution would be to explicitly code a delegate. I decided to put it completely outside the existing classes. That way, the scope would include those classes. I also coded the instantiation of the class, TableTennisMatch, as part of the TTMatchControl class rather than the form where it's used.
Public Delegate Sub MatchWonHandler(ww As Integer)Public Class TTMatchControlDim theMatch As New TableTennisMatchTo wireup the event handler to the event, I used an AddHandler statement instead of the Handles clause on the event handler subroutine itself.
AddHandler theMatch.MatchWon, AddressOf Me.Record_WinLoss...Public Sub Record_WinLoss(ByVal ww As Integer) ' Note - No Handles clauseThen the Event itself refers to the delegate - MatchWon As MatchWonHandler - rather than specifying a hardcoded parameter - MatchWon(whoWon As Integer).
Public Class TableTennisMatchPublic Event MatchWon As MatchWonHandlerThe use of a delegate and the AddHandler statement gives you extra flexibility. Although this example is a little 'forced' to match the table tennis metaphor I'm using, you could add two event handlers now, one for the players and another to signal that the table is available for another match. Since the first parameter will signal which player won, I added another parameter for the table.
Public Delegate Sub MatchWonHandler(ww As Integer, tt As Integer)Then both handlers have to be added, not just one. The AddHandler statement is a little bit unusual in the way it works here. A linked list of all handlers that have been added is maintained by VB.NET and executed one at a time. In some cases, this can be a problem because later handlers won't run until earlier ones finish and this can be a blocking problem. I'll cover this a bit more in the second part of this series.
AddHandler theMatch.MatchWon, AddressOf Me.Record_WinLossAddHandler theMatch.MatchWon, AddressOf Me.UpdateTableThe RaiseEvent statement has to be modified.
RaiseEvent MatchWon(0, Table)Finally, another event processing subroutine has to be present. In this case, I just added text to a label, but a complete system to update a "table" database and possibly raise another event could be coded here.
Public Sub UpdateTable(ByVal ww As Integer,ByVal tt As Integer)lblUpdateTable.Text ="Table " & tt &vbCrLf & " is available."End Sub--------
Click Here to display the illustration
--------
VB.NET actually handles all events in pretty much the same way, but with most options, much of the code that makes it work is added by the compiler and isn't shown. You can add your own code to replace this automatic code, but understanding how it ties together isn't obvious ... and (Surprise!) Microsoft's documentation doesn't help a lot. Part Two of this series covers some of these mysteries and explains how the "Custom" keywork in declaring your event changes things.
To continue this series: Using the Custom Event Keyword
Source...