5.5 Handling Control Events

One of the most convenient aspects of the new ASP.NET Web Forms model is that it brings event-driven programming, popularized by Visual Basic, to the web world without all the kludginess of the late unlamented Visual Basic WebClasses. As explained in Chapter 3, ASP.NET has a number of built-in events at the page level for which you can write event handlers to execute code.

Moreover, most server controls expose one or more events for which you can write handlers. Table 5-8 shows a list of common events and the controls that support them. These events and controls are in addition to the standard events, such as Init, Load, PreRender, and UnLoad, that are inherited from the base Control class.

For example, the Button server control exposes the Click and Command events. These events are both raised when the button is clicked, but while the Click event is usually used simply to handle the event for a single button, the Command event can be used to handle clicking on several buttons (so long as the buttons' CommandName property is set). The CommandName property, along with an optional CommandArgument property, become properties of the CommandEventArgs object, which is passed as a parameter of the Command event handler. You can then examine the CommandName and CommandArgument properties within the event handler code to determine what action(s) to take.

Table 5-8. Common control events

Event	Event type	Description	Controls
OnAdCreated	Change	Raised after creation of the control and immediately before the page is rendered. If an Advertisement file is provided, OnAdCreated is raised after an ad has been selected from the file. Passes an AdCreatedEventArgs argument.	AdRotator
OnClick	Action	Raised when the user clicks the control. Passes an EventArgs argument.	Button ImageButton LinkButton
OnCommand	Action	Raised when a button containing OnCommand, CommandName, and CommandArgument attributes is clicked. Passes a CommandEventArgs argument containing the CommandName and CommandArgument attribute values.	Button ImageButton LinkButton
OnSelectedIndexChanged	Change	Raised when the user changes the selection. Passes an EventArgs argument.	CheckBoxList DropDownList ListBox RadioButtonList
OnCheckedChanged	Change	Raised when the user clicks the control. Passes an EventArgs argument.	CheckBox RadioButton
OnPageIndexChanged	Change	Raised when the user clicks a page selection element. Passes a DataGridPageChangedEventArgs argument.	DataGrid

The basic format of an event handler is as follows:

' VB.NET Sub MyButton_Click(Sender As Object, E As EventArgs)    'Event handling code End Sub    // C# void MyButton_Click(object Sender, EventArgs e) {    // Event handling code }

While you can name your event handling procedures whatever you like, it's common to use the ObjectName_EventName convention, which makes it very easy to immediately see which procedures are event handlers. All event handlers are passed an Object argument that is a reference to the control from which the event was fired. They are also passed an instance of the EventArgs class or of a class that derives from EventArgs. For example, the OnCommand event of a Button control passes an argument of type CommandEventArgs, which contains information about the command represented by the button:

Sub MyButton_Command(Sender As Object, E As CommandEventArgs)    Message.Text = "Command " & E.CommandName & _       "was sent." End Sub

As with creating controls, two techniques are available for creating and wiring up event handlers in ASP.NET: declarative and programmatic.

5.5.1 Wiring Up Events in Declarative Tags

The technique typically used to wire up events that are handled in a server-side <script> block, which is probably the simplest way to wire an event handler, is to add the appropriate attribute to the declarative tag used to create the control. The following code snippet sets the OnClick event handler to SubmitBtn_Click:

<asp:button  text="Submit" onclick="MyBtn_Click" runat="server"/>

To handle this event, you would then add the following code to your page in a server-side <script> block:

' Visual Basic .NET Sub MyBtn_Click(sender As Object, e As EventArgs)    'event handling code End Sub    //C# void MyBtn_Click(Object sender, EventArgs e) {    // event handling code }

The event handler for the Command event of the Button control is wired up in much the same fashion:

<asp:button      text="Sort"     commandname="Sort"    commandargument="Descending"    oncommand="Button_Command"    runat="server"/>    <asp:button      text="Filter"     commandname="Filter"    commandargument="B"    oncommand="Button_Command"    runat="server"/>

Note that the event handler changes slightly (EventArgs is replaced by the CommandEventArgs subclass, which contains information about the clicked command button):

' Visual Basic .NET Sub Button_Command(sender As Object, ce As CommandEventArgs)    Select ce.CommandName       Case "Sort"          ' Sort logic       Case "Filter"          ' Filter logic    End Select End Sub    //C# void Button_Command(Object sender, CommandEventArgs ce) {    switch(cs.CommandName)    {       case "Sort":          // Sort logic       case "Filter":          // Filter logic    } }

It's a good habit to name your event handlers based on the name of the control whose event they handle and the name of the event, separated by an underscore (e.g., MyBtn_Click). However, as you can see from the OnCommand event example, you may want to make an exception sometimes.

5.5.2 Wiring Up Events Programmatically

Programmatic wiring of control events is typically used with code-behind classes; it's a little more complicated than the declarative technique, but still pretty straightforward. Note that programmatic event wiring is language dependent. Two techniques wire up events programmatically in Visual Basic .NET and one wires up events in C#.

The preferred approach for programmatically wiring events in Visual Basic .NET uses the WithEvents and Handles keywords to associate event handlers with events. As the following snippet illustrates, you first declare an instance of the desired control using the WithEvents keyword to indicate that you want event support for the instance.

Then you add the Handles clause to the procedure declaration for the event handler, specifying the object and event that it will handle:

Sub Page_Load( )    Protected WithEvents MyButton As New Button( ) End Sub    Sub MyButton_Click(sender As Object, e As EventArgs) _ Handles MyButton.Click    'Event handling code End Sub

When declaring control instances in a code-behind class, it's a good idea to use the Protected keyword to ensure that the instance is available only to the class itself and to any class (such as the .aspx page) that inherits from it.

An alternate technique in Visual Basic .NET uses the AddHandler statement to specify a control event along with the address of the procedure that should be invoked when that event occurs:

Sub Page_Load( )    Protected MyButton As New Button( )    AddHandler MyButton.Click, AddressOf MyButton_Click End Sub    Sub MyButton_Click(sender As Object, e As EventArgs)    'Event handling code End Sub

A corresponding RemoveHandler statement also allows you to stop handling a particular event. The advantage of this technique is that you can stop and start handling a particular event dynamically. In C#, the += operator is used to assign an event handler to an event:

void Page_Load( ) {    Button MyButton = new Button( );    MyButton.Click += new EventHandler(this.MyButton_Click); }    void MyButton_Click(Object sender, EventArgs e) {    // Event handling code }

As with Visual Basic's AddHandler keyword, the += operator has a corresponding -= operator that allows you to unwire an event from its handler dynamically.