| 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. TIP 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 perhaps 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 your 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 End Sub TIP 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 that 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 the 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 if 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 Click Me button, you should see text appear in the Label control on the page. What happened? Clicking a CommandButton control always triggers an immediate postback to the server. At that point, the page's Load event procedure runs. Then, the btnClickMe_Click event procedure takes its turn, running the code you just added that writes text to the Label control on the page. The SelectedIndexChanged Event Selecting an item from a DropDownList control triggers that control's SelectedIndexChanged event. To test this out, open Events.aspx in Design view and double-click the DropDownList control (ddlProducts) on the page. Modify the event procedure stub so that it looks like this: Private Sub ddlProducts_SelectedIndexChanged( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles ddlProducts.SelectedIndexChanged lblMessage.Text = "You selected " & _ ddlProducts.SelectedItem.Text End Sub TIP The SelectedItem property of the DropDownList control retrieves a ListItem object representing the item you selected from the list. The Text property of this object contains the text of the selected item in the control.
Try running Events.aspx and select an item. Nothing happens. Click the Click Me button, and you'll see that the page posts back to the server and that the text is inserted. If you look carefully, you might see the selected item from the DropDownList control before you see the text from the command button. What's up? Selecting an item in a DropDownList control doesn't trigger an automatic postback, unlike clicking a command button, which does. When you do click a command button, you trigger a postback, and the page framework runs both event procedures (btnClickMe_Click and ddlProducts_SelectedIndexChanged). The order of event handlers isn't clear, but both run. If you want to trigger an immediate postback when you select an item from the DropDownList control, you'll need to set the control's AutoPostBack property to be True (it's False by default). Try that now. With Events.aspx open in Design view, set the AutoPostBack property of ddlProducts to True. Try running Events.aspx again, and this time, select an item from the DropDownList control. Now, selecting an item triggers an immediate postback, and the event procedure writes text into the lblMessage control. The CheckChanged Event A RadioButton control raises its CheckChanged event when you change the "checked" state of the control. Just like the DropDownList control, the RadioButton control doesn't trigger an automatic postback unless you set the control's AutoPostBack property to True. In addition, you normally want RadioButton controls to work in a group that is, if you select one control, you'd like other controls in the same group to be deselected (in other words, the selections in the group are mutually exclusive). In order for this to happen, you must set the GroupName property of associated controls to be the same group name. TIP If you simply require a group of radio buttons that work dependently, you might consider using the RadioButtonList control. This control provides a single group of radio buttons, all working together, allowing for a single choice only. Using individual RadioButton controls requires more effort (you must set the GroupName property for each one). What you lose in convenience, you gain in flexibility.
It would be nice if you could share the same CheckChanged event handler for both RadioButton controls, because both controls require similar actions when you select them. In order to make that happen, you'll take advantage of the power of the Handles clause. Double-click one of the RadioButton controls, and Visual Studio .NET places you in the CheckChanged event procedure for that control. Modify the procedure so that it looks like Listing 7.1. Listing 7.1 You Can Use the sender Parameter to Determine Which Control Was Selected Private Sub Sex_CheckedChanged( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles rdoMale.CheckedChanged, rdoFemale.CheckedChanged If sender Is Me.rdoMale Then lblMessage.Text = _ "You clicked on the Male radio button" Else lblMessage.Text = _ "You clicked on the Female radio button" End If End Sub Because this procedure lists multiple object.event items in its Handles clause, the page framework will run this event procedure in reaction to the events of either control. Because the code runs for either control, you must use the sender parameter to determine which control raised the event. TIP The sample code uses the Is operator to determine which RadioButton control raised the event. This operator compares objects (not values). Because the code is attempting to determine which object raised the event and is comparing one object (sender) to another (the controls), the Is operator is required. (The alternative would be to use the = operator, which compares values, not objects.)
The Page's Load Event Each and every time you request a page, that page's Load event runs the code you've placed in the Page_Load event procedure. You may have some code that you'd like to have run only the first time the page is loaded, and other code for subsequent loads. To make that possible, the Page object provides the IsPostBack property a Boolean value that indicates whether the page is being loaded because of a postback. The sample page, Events.aspx, only needs to fill in the drop-down list of products the first time it's loaded. To accomplish this goal, choose the View, Code menu item to display the code-behind file for the page and then find the Page_Load procedure, which looks like Listing 7.2. Listing 7.2 You Can Use the Page_Load Procedure to Preload Values into Controls Private Sub Page_Load( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles MyBase.Load If Not Page.IsPostBack Then With ddlProducts .Items.Add("Apples") .Items.Add("Pears") .Items.Add("Plums") End With End If End Sub You'll see that the code only loads the list (ddlProducts) with values if Page.IsPostBack isn't True. You can take advantage of this same mechanism to take different steps, depending on whether your page is posting back to itself. There are clearly many more controls, many more objects, and many more events to be investigated in ASP.NET. We've selected a small subset to give you the flavor of working with event procedures and controls. When working with any control, investigate its event procedures carefully and take advantage of the event-specific parameters passed to those procedures from the page framework. | 
