Event-Handling Basics The process of creating a Web Forms user interface involves placing controls onto a page and then writing code to react to events that occur as users interact with those controls. ASP.NET makes it simple for you to work with pages, controls, and events as if the entire process were taking place on a client computer.
Interacting with the Server In actuality, almost all event handling takes place on the Web server, and it''''s important that you understand what happens when you add event code that runs in reaction to user events. More important, code that you write in reaction to control events always runs on the server, except in one case: When you write script code that handles events on the client, in JavaScript or VBScript, the code does run on the client. Even the validation controls (covered in Chapter 8, "Validation Controls") run code on the server to validate data, even though the controls also provide client-side script for validating on the client side.
When you place a command button on a page, you can add code to react to that button''''s Click event. Clicking a command button control always triggers a postback to the server, where the page''''s Load event occurs. Then, your button''''s Click event procedure runs, allowing the procedure to react to the user clicking the button.
Each control supplies its own set of events that it can react to. For example, CommandButton controls provide a Click event. ListBox and DropDownList controls supply a SelectedIndexChanged event. RadioButton controls provide a CheckChanged event. It''''s your job as a developer to learn which controls supply which events and write code reacting to the appropriate events.
It''''s important to remember that none of the code you create in reaction to events, in your page''''s code-behind file, runs on the client. All this code runs on the server and requires a roundtrip to the server in order to run. This is a startling realization for Visual Basic 6.0 developers, who are used to having all event code run immediately in response to triggering an event.
Very few controls automatically trigger a postback to the server (in other words, very few controls'''' code runs automatically when you interact with the controls). For example, selecting an item in a list box won''''t automatically trigger a postback to the server and won''''t run the SelectedIndexChanged event procedure. The next time the page does post back, the code will run. If you want immediate feedback (more like a Visual Basic 6.0 form), you can set the AutoPostBack property for most controls to True. Doing this causes a change to the control''''s value to trigger a postback to the server.
You''''ll need to set the AutoPostBack property to True for controls in which you require immediate feedback梡erhaps selecting an item from a list requires updating a label on the page. Alternatively, you might want to filter a list of values based on a selection in another list. Several examples in this chapter make use of the AutoPostBack property.
WARNING
There''''s no "free lunch" here. A roundtrip to the server is, well, a roundtrip to the server, and that takes time. If you have every control on your page initiate a roundtrip, by setting the AutoPostBack property to True for all the controls, you might be sorry due to increased network traffic and the time it takes for the page to respond to the user. With the Web server on your local machine, it''''s hard to determine the price you''''ll pay for postbacks, but even there, roundtrips aren''''t immediate. Consider carefully when you actually need to post back to the server梱our users will appreciate it.
How Event Handling Works In order to demonstrate some of the features of event handling and the VB .NET language, we''''ve provided a simple project named VBLanguage.sln. You''''ll want to load this sample project so you can follow along with the discussion. This project already includes the layout for the pages, but you''''ll need to add the appropriate event code. The first page we''''ll discuss, Events.aspx, is shown in Figure 7.1.
Figure 7.1. Clicking a button or changing the selection within a drop-down
list can fire an event procedure back on the server.
We''''ll start by investigating the Click event of the CommandButton control on this page. Each server control (such as the CommandButton control) provides a default event procedure, and double-clicking the control in Design view will load the code editor and create the stub of the event procedure for you. Double-clicking the Click Me command button, for example, loads the code editor and writes this code for you:
Private Sub btnClickMe_Click( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles btnClickMe.Click
Here, and throughout this book, we''''ve reformatted event procedures so that they fit within the requirements of the printed page. We''''ve added line continuation characters (a space, followed by an underscore, and then a carriage return/linefeed) to the end of lines that need to be broken to fit on the printed page. The Visual Studio .NET editor doesn''''t perform these same line breaks for you, so the code you see on the screen will be formatted slightly different from the code you see printed here.
You should notice some important things about this procedure:
Visual Studio .NET generates a procedure name for you. In this case, the procedure is named btnClickMe_Click. Unlike in Visual Basic 6.0, the name of the procedure is arbitrary梩hat is, the name isn''''t used internally by the event handling in the page framework. Visual Studio .NET generates a name based on the name of the control and the name of the event, but that''''s only for your convenience梩he name could be anything at all. When you double-click the Click Me button, you''''ll see the following code:
Private Sub btnClickMe_Click( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles btnClickMe.Click
End Sub
The event procedure provides two parameters, which you''''ll learn about in the next sections. These parameters are highlighted here:
Private Sub btnClickMe_Click( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles btnClickMe.Click
End Sub
The procedure ends with a Handles clause. This clause indicates to the event handler that the page framework should run this particular procedure in reaction to the specified event (btnClickMe.Click, in this case). This object.event name is crucial梚f the object and its event name don''''t match an actual object and event on the page, your code won''''t compile. We''''ve highlighted the Handles clause here:
Private Sub btnClickMe_Click( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles btnClickMe.Click
End Sub
The sender Parameter The first parameter passed to every event procedure is a reference to the object that raised the event. In most cases, this will be the control listed in the Handles clause. However, as you''''ll see later in this chapter, it''''s possible for one event procedure to handle more than one control''''s events. In that case, the Handles clause will contain a comma-delimited list of controls, and the sender parameter will indicate which of those controls raised the event.
The e Parameter For some events, the page framework will need to pass information to the event-handling procedure. The page framework passes most controls'''' events an object of type EventArgs in this parameter. This object has no useful properties itself, but many controls'''' events use classes that inherit from this base class. For example, if you place an ImageButton control on a page, its Click event receives an object of type ImageClickEventArgs in this parameter. This object has all the standard EventArgs properties, and in addition, supplies X and Y properties so that the event procedure can determine where, within the image, the user clicked.
TIP
Many classes inherit from the base EventArgs class. You should always investigate, for any event procedure you write, the e parameter, to see whether the page framework is sending your procedure useful information based on the conditions when the event was raised.
Button Control Events To test out event handling, you could have a label display some text in reaction to clicking a button. On the sample page, you might have the Label control, lblMessage, display "You clicked on a button" when you click btnClickMe. To make that happen, modify the btnClick_Click procedure so
that it looks like this:
Private Sub btnClickMe_Click(_ ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles btnClickMe.Click lblMessage.Text = "You clicked on a button" End Sub
Right-click the Events.aspx page in the Solution Explorer window and select Build and Browse from the context menu. When you click the Clic