Raising Events | ASP.NET by Example

I l @ ve RuBoard

Sometimes you will want to raise events of your own from within your controls. For example, a validation control might raise an event to let its parent control know that it found an invalid element. Although not necessary for many kinds of controls and a bit more advanced, custom events can be a powerful tool. A simple example of raising an event and handling it from an ASP.NET page is really all that we have room for in this chapter, but it should give you an idea of how this works and get you started if you need to build an event-raising control of your own.

Just to keep things simple, we're going to add an event to our HelloPerson class that we used earlier in the chapter. We have decided that if this control's PersonName property is left blank, that this is "event-worthy" and should raise a PersonNameRequired event. Because we are not doing anything too fancy with our event, like returning a custom data structure, we can take advantage of the default data structures System.EventArgs , System.EventHandler , and System.Web.UI.Control.Events .

In order to wire up an event, we need to define two items in our class: an event and an event-handler routine. There are several ways to define these items; the technique described here is the one recommended by the documentation as being the most optimized for performance. Once the event is defined in the class, it is still necessary that something cause the event to be raised. In our example, we are going to check the value of the PersonName property during the pre-render phase of our control's life cycle, and raise the event there if we find that the PersonName property is not set. The complete source of our new control, HelloPersonEvents.cs, is in Listing 12.13.

Listing 12.13 Raising Events From Your Control (HelloPersonEvents.cs)

 using System; namespace ASPNETByExample {     public class HelloPersonEvents : System.Web.UI.Control     {         private static readonly object PersonNameRequiredEvent = new object();         protected virtual void OnPersonNameRequired(EventArgs e)         {             EventHandler onPersonNameRequiredHandler =                 (EventHandler)Events[PersonNameRequiredEvent];             if (onPersonNameRequiredHandler != null)                 onPersonNameRequiredHandler(this, e);         }         public event EventHandler PersonNameRequired         {             add             {                 Events.AddHandler(PersonNameRequiredEvent, value);             }             remove             {                 Events.RemoveHandler(PersonNameRequiredEvent, value);             }         }         public string PersonName         {             get             {                 if(ViewState["PersonName"]!=null)                     return ViewState["PersonName"].ToString();                 else                     return "";             }             set             {                 ViewState["PersonName"] = value;             }         }         protected override void OnPreRender(EventArgs e)         {             base.OnPreRender(e);             if((PersonName == null)  (PersonName.Length == 0))             {                 OnPersonNameRequired(EventArgs.Empty);             }         }         protected override void Render(System.Web.UI.HtmlTextWriter htwOutput)         {             htwOutput.Write("Hello " + PersonName);         }     } }

Note that both the OnPersonNameRequired routine and the PersonNameRequired event rely on the Events collection, which is exposed by System.Web.UI.Control . This collection manages event handlers for us, allowing us to enable support for an event in just a few lines of code.

In order to actually raise an event, you need to call its handler from within the control. In this case, the OnPreRender method does a check to see if the PersonName property is empty, and if it is, it calls OnPersonNameRequired() , passing it an empty EventArgs parameter.

Of course, raising the event is only half the story. It's up to the ASP.NET page to actually do something when this event occurs. In this case, the page will display an error message to notify the user that they need to provide a value for the control, providing functionality similar to that of the RequiredFieldValidator control. The complete source code of the test page is in Listing 12.14.

Listing 12.14 Handling Events from Controls (HelloPersonEvents.aspx)

 <%@ Page Language="C#" %> <%@ Register TagPrefix="Hello" Namespace="ASPNETByExample" Assembly="HelloWorld" %> <%@ Import Namespace="ASPNETByExample" %> <script runat="server"> void Page_Load(){     hello.PersonName = person.Text; } void hello_PersonNameRequired(object sender, EventArgs e) {     Error.Text = "You must enter a value for the textbox."; } </script> <html>     <body>         <form runat="server">             <Hello:HelloPersonEvents                 runat="server"                 id="hello"                 OnPersonNameRequired="hello_PersonNameRequired"             />             <br />             <asp:TextBox Runat="server" ID="person" Text="Steve" />             <asp:Button Runat="server" Text="PostBack" />             <br />             <asp:Label                 Runat="server"                 ID="Error"                 ForeColor="Red"                 EnableViewState="False"             />         </form>     </body> </html>

There are two key things to note about this page. First, in the declaration of the control, the OnPersonNameRequired event is defined to invoke the hello_PersonNameRequired event handler. Second, looking at this event handler in the page's source code, we see that it looks just like any other event, and can participate in the page's execution freely . In this case we use it to set the value of an error Label . Now, when this page is loaded, if no value is set in the TextBox (and thus no value is copied to the HelloPersonEvents control), the PersonNameRequired event will fire and result in the red error message being displayed.

You can view this example live online at http://aspauthors.com/aspnetbyexample/ch12/.

I l @ ve RuBoard