Steven Houben Student Human-Computer Interaction

C# Event

Introduction

Most people can use the standard events that are build-in most objects in the .Net framework. Visual Studio and MonoDevelop provide  both a very simple interface to create, edit, delete or change events. These interfaces hide the logic behind the event  for the programmer. This is fine for most situations but when confronted with custom events, the problems start. In this blogpost I am demonstrating and explaining how you can create a custom event.

Event?

An event is a notification message that is send from one object to another object. It is used to notify an other object about the changed state of the object. Lets use an example to explain the context of events. Image we have a class called Main, that holds the application logic. In this  Main class we want to use a parser, a xml analyzer for example. We declare a new instance of the object Parser by using a piece of code that could look like this:

Parser parser = new Parser();

We can now access the parser class from the main class by using its methods and properties. We could for example call the method parse and set the property TimeOutTime:

parser.parse(data);
parser.TimeOutTime = 2;

In figure 1 you can see a conceptual representation of this process. The down arrow demonstrates this instantiation and use of methods and properties. If we would send some raw data to the parser in order to change something in our main class, it would be nice that the parser can send back the result of the parse method. One way could be to add a return type to the parse method. This can be efficient in some situations but when timing, or threading are an issue this may not work well. We could perhaps let the Parser class create an instance of the main class, so we can use the methods and properties of the main class to update it. The latter wont work because the new instance is not the same as the existing instance that created the parser class in the first place. Although both instances are of the same object, they are not the same. Another issue that may be of concern is the fact that the parse class doesn't really need to know anything about the main class. It simply wants to process data and output the result. With the usage of an event the parse class can simply send a Parsed message when the parsing is done. In figure 1 you can see this process. The Parser class simply sends a Parsed event when it is done parsing. This  instantiation of Class B by Class A and the usage of an event to notify class A should make clear that Class A uses Class B but Class B has in fact no knowledge about Class A, it is simply used by Class A. This is called Loose Coupling [1].

Event in C# (.Net)

To create a custom event in .net we need three components: a delegate [2], an event arguments class and the event. We will use the example of the Main class and the Parse class to demonstrate how to implement an event in c#. You can find the complete class files at the bottom of the page.

It is not necessary to have a deep understanding of a delegate. Simply remember that a delegate is basically a type-safe pointer that points to a specific memory address. A delegate is used as a point where you can hook your event on ( a callback function). An event is actually an instance of a delegate. The delegate is a static point that links your event message from one class to an other class.

So, first of all we need to create a delegate outside (!) all classes. You typically do this at the top of your code file inside the namespace but outside(!!) the class. In our example we are creating an event for the Parser class so we will put the delegate in this file but outside(!!!) the class.

public delegate void ParserHandler(Object obj, ParserEventArgs e);

We named our delegate ParserHandler, as it is going to handle parser events. The arguments for our delegate are an object and a ParserEventArgs class. We will use the object so we can check what instance has send the event. The ParserEventArgs doesn't exist so we need to make it.

Any event arguments class holds information about the state of the object. This class is the actual message or notification we are sending to another class. In this case we want to send a result back to another class. There are two ways we can do this:

1. First of all we could create an empty EventArgs  class. When an event is send the Main class will receive an empty event message. This may seem not seem very useful but we could use this event as a trigger to retrieve information. The parse could have a property Result. When we receive this empty message we know that the Result property is updated with the new result and we can retrieve it by using the property.
2. Secondly we can put the result into the EventArgs and send it over. When the main class receives the message we can find the result inside the message

Iin this example we are using the second method. We need to create a new class ParserEventArgs that hold a Object field and a Result field:

  public class ParserEventArgs
    {
        public string Result { get; set; }
        public Object Object { get; set; }
        public ParserEventArgs() { }
        public ParserEventArgs(Object obj, string result)
        {
            this.Result = result;
            this.Object = obj;
        }
    }

Now that we've got our delegate and our ParseEventArgs class, it is time to implement our event. First of all we need to create our event:

 public event ParserHandler parserEventHandler = null;

Place this event inside the Parser class. Next we are going to wrap this event for simplicity and to make sure the event is never null.

 protected void OnParseEvent(ParserEventArgs e)
        {
            if (parserEventHandler != null)
            {
                parserEventHandler(this, e);
            }
        }

If we now want to send the event, in this case when the parsing is done, we simply need to call the OnParseEvent method:

 public void Parse(Object rawdata)
        {
            //parse code here
            string result = "ParsedData";

            OnParseEvent(new ParserEventArgs(this, result));
        }

The Parser class is now modified to send an event when the parse function is done. We can now use this in our main class:

>class Main
    {
        Parser parser = new Parser();
        public Main()
        {
            parser.parserEventHandler += new ParserHandler(parser_Parsed);
            parser.Parse("RAWDATA");
        }
        private void parser_Parsed(object sender, ParserEventArgs e)
        {
            string result = e.Result;
        }
    }

This may seem familiar as this code is basically what the IDE generate when you use a standard event. In the main class we create a parser object. In the constructor we hook an event listener to this and call the parse method. When the raw data is parsed the parsed object sends a Parsed event that we are catching with our handler.

The complete Parser class:

namespace Parser
    {
        public delegate void ParserHandler(Object obj, ParserEventArgs e);
        public class Parser
        {
            public event ParserHandler parserEventHandler = null;

            public void Parse(Object rawdata)
            {
                //parse code here
                string result = "ParsedData";

                OnParseEvent(new ParserEventArgs(this, result));
            }
            protected void OnParseEvent(ParserEventArgs e)
            {
                if (parserEventHandler != null)
                {
                    parserEventHandler(this, e);
                }
            }
        }
        public class ParserEventArgs
        {
            public string Result { get; set; }
            public Object Object { get; set; }
            public ParserEventArgs() { }
            public ParserEventArgs(Object obj, string result)
            {
                this.Result = result;
                this.Object = obj;
            }
        }
    }

References

[1] Loose Coupling, http://en.wikipedia.org/wiki/Loose_coupling

[2] Delegate, http://en.wikipedia.org/wiki/Delegate_(.NET)