Delegates and Events

A method is a procedure created as a member of a class. Methods are used to access or manipulate the characteristics of an object or a variable. There are mainly two categories of methods you will use in your classes:

• If you are using a control such as one of those provided by the Toolbox, you can call any of its public methods. The requirements of such a method depend on the class being used
• If none of the existing methods can perform your desired task, you can add a method to a class.

The Windows controls available from the .NET Framework are equipped with various methods ready to be used. Of course, no library can surely provide every single type of method that every programmer would use. For this reason, it will not be unusual that you need a method that is not available for a control you are using. In the same way, when you create a Windows Forms Application that is based on the Form class, you will likely need a method that is not defined in the Form class. In this case, you can create your own and new method.

A method is created like a normal procedure. If you want to add it to a form, you can open the Code Editor and write your procedure. Here is an example:

public:
        double CalculateRectangleArea(Rectangle Recto)
        {
	return Recto.Width * Recto.Height;
        }
};

In the same way, if you derive a class from one of the existing classes because you want to get a custom control from it, you can declare a new method as you see fit and use it appropriately.

Probably the best way is to let the Code Editor insert the new method based on your specifications. To do that, in the Class View, first expand the name of the project. Then, right-click the name of the class where you want to add a new method, position the mouse on Add, and click Add Function... This would open the Add Member Function Wizard you can fill out and click Finish.

As a variable can be declared as a pointer, so can a function. A pointer to a function is a type of variable whose name can be used as a variable although it is not a traditional variable the others. This concept has always been very helpful in Microsoft Windows programming because it allows the use of callback functions. Thanks to their effectiveness (and legacy code), the concept of callback functions was carried out in the .NET Framework but they were defined with the name of delegate.

A delegate is a special type of user-defined variable that references a method of a class. There are similarities and differences between a function pointer and a delegate:

• Like a function pointer, a delegate is not defined like a normal function
• Like a function pointer, a delegate has the appearance of a variable that is declared as a pointer
• Like a function pointer, a delegate can take argument(s)
• While a function pointer can be associated with a global function, that is, a function that is not a member of a class, a delegate can be associated, or can reference only, a member of a class

To declare a delegate, you use the __delegate keyword. The basic formula used to create a delegate is:

Access Level __delegate Function-Signature;

The Function-Signature factor is created as you would declare a normal C++ function. This means that the Function-Signature must have

1. A return type: The return type can be void, one of the primitive data types (int, long, double, short, etc), a .NET Framework type (Double, Decimal, etc), a .NET Framework class, or a class you created
2. A name: Like every variable, function, or class, a delegate must have a name
3. Parentheses: Like every function, a delegate must have a name
4. Optional arguments: If the method(s) that this delegate will reference has/have argument, this delegate must also have argument(s) of exactly the same kind)

After defining the Function-Signature, you must end the delegate declaration with a semi-colon. Here is an example:

__delegate double Addition();

A declaration of a delegate can also use an access level as public or private. If you plan to use the delegate only locally, you can omit the access level or declare it as private, which is the default. If you plan to use the delegate outside of the project in which it is created, you should declare it as public.

After declaring a delegate, remember that it only provides a skeleton for a method, not an actual method. In order to use it, you must define a method that would carry an assignment the method is supposed to perform. That method must have the same return type and the same (number of) argument(s), if any. Here is an example:

private __delegate double Addition();

__gc class MathOperations
{
public:
	double Plus()
	{
		double a = 248.66, b = 50.28;

		return a + b;
	}
};

After implementing the method, you can associate it to the name of the delegate. To do that, where you want to use the method, first declare a pointer of the type of the delegate using the new operator and calling its default constructor.

After properly declaring and initializing the instance, it becomes ready and you can use it. When you declare a delegate, at run time, the compiler generates a class for it. The generated class automatically receives the following characteristics:

• The class is derived from the System::MulticastDelegate class which itself derives from the System::Delegate class. Both classes are defined in the System.dll assembly
• The class is equipped a constructor that (actually the class is overloaded with two constructors that each) takes two arguments as follows:
    

  protected: MulticastDelegate(Object *target, String *method); protected: MulticastDelegate(Type *target, String *method);

• The class is automatically equipped with a method called Invoke. Its return type and its argument become the same as those of the declared delegate

As mentioned in the second point, the instance of the delegate must take two arguments. If you declared the method as done earlier (__delegate double Addition();), the first argument of the instance must be a pointer to the class that implements the method associated with the delegate. This would be done as follows:

private __delegate double Addition();

__gc class MathOperations
{
public:
	double Plus()
	{
		double a = 248.66, b = 50.28;

		return a + b;
	}
};

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		MathOperations *oper = new MathOperations;
		Addition *add = new Addition(oper, . . .);
		
		InitializeComponent();
	}
};

After the first argument, the second argument must be a reference to the class' method that implements the desired behavior of the delegate. Here is an example:

private __delegate double Addition();

__gc class MathOperations
{
public:
	double Plus()
	{
		double a = 248.66, b = 50.28;

		return a + b;
	}
};

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		MathOperations *oper = new MathOperations;
		Addition *add = new Addition(oper, &MathOperations::Plus);
		
		InitializeComponent();
	}
};

The declaration gives meaning to the delegate. To actually use the method, you can call the name of the delegate as if it were a defined method. If you want to retrieve the value that the delegate produced, in the above third point, we mentioned that the delegate's class is equipped with a method called Invoke that completely "understand" the method that implements it. This means that the Invoke() method returns the same value as the associated method. In our example, the Invoke() method of the delegate would return a double since the delegate was declared as returning a double.

Here is an example that uses the delegate:

#pragma once
#include <windows.h>

#using <mscorlib.dll>
#using <System.dll>
#using <System.Windows.Forms.dll>

using namespace System;
using namespace System::Windows::Forms;

private __delegate double Addition();

__gc class MathOperations
{
public:
	double Plus()
	{
		double a = 248.66, b = 50.28;

		return a + b;
	}
};

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		MathOperations *oper = new MathOperations;
		Addition *add = new Addition(oper, &MathOperations::Plus);
		
		InitializeComponent();

		double nbr = add->Invoke();
		this->Text = nbr.ToString();
	}

private:
	void InitializeComponent()
	{

	}
};

int APIENTRY WinMain(HINSTANCE hInstance,
                     HINSTANCE hPrevInstance,
                     LPTSTR    lpCmdLine,
                     int       nCmdShow)
{
	Application::Run(new CExercise);

	return 0;
}

This would produce:

We mentioned earlier that you could declare the associated method of a delegate like any normal method, in which case you must pass a pointer to the class as the first argument of the instance of the delegate. This is a requirement if you plan to instantiate the delegate outside of the class that defines its associated method. That was the case for our MathOperations class since the Plus() method was going to be used in the CExercise class. If you plan to use a delegate in the same class that implements its associated method, you can declare the method static. Here is an example:

#pragma once
#include <windows.h>

#using <mscorlib.dll>
#using <System.dll>
#using <System.Windows.Forms.dll>

using namespace System;
using namespace System::Windows::Forms;

private __delegate double Addition();
private __delegate double Multiplication();

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		InitializeComponent();
	}

private:
	void InitializeComponent()
	{

	}

	
	static double Times()
	{
		double a = 248.66, b = 50.28;

		return a * b;
	}
};

Once again, to use the delegate, you must first declare its pointer and allocate its memory using the new operator and calling the constructor that takes two arguments. This time, the first argument must be null or 0. The second argument must still be a reference to the method that implements the desired behavior. Here is an example:

#pragma once
#include <windows.h>

#using <mscorlib.dll>
#using <System.dll>
#using <System.Windows.Forms.dll>

using namespace System;
using namespace System::Windows::Forms;

#define NULL 0

private __delegate double Addition();
private __delegate double Multiplication();

__gc class MathOperations
{
public:
	double Plus()
	{
		double a = 248.66, b = 50.28;

		return a + b;
	}
};

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		MathOperations *oper = new MathOperations;
		Addition *add = new Addition(oper, &MathOperations::Plus);
		
		Multiplication *multi = new Multiplication(NULL, &Times);

		InitializeComponent();

		double nbr = multi->Invoke();
		this->Text = nbr.ToString();
	}

private:
	void InitializeComponent()
	{

	}
	
	static double Times()
	{
		double a = 248.66, b = 50.28;

		return a * b;
	}
};

int APIENTRY WinMain(HINSTANCE hInstance,
                     HINSTANCE hPrevInstance,
                     LPTSTR    lpCmdLine,
                     int       nCmdShow)
{
	Application::Run(new CExercise);

	return 0;
}

This would produce:

Because delegates are usually declared globally, that is, outside of a class, they can be associated with a method of any class, provided the method has the same return type (and the same (number of) argument(s)) as the delegate.

One of the characteristics that set delegates apart from C/C++ function pointers is that one delegate can be added to another using the overloaded addition assignment operator. This is referred to as composition. This is done by adding one delegate variable to another.

If you want to associate a method that takes arguments to a delegate, when declaring the delegate, provide the necessary argument(s) in its parentheses. Here is an example of a delegate that takes two arguments (and returns a value):

__delegate double Addition(double x, double y);

When defining the associated method, besides returning the same type of value if not void, make sure that the method takes the same number of arguments. Here is an example:

private __delegate double Addition(double x, double y);
private __delegate double Multiplication(double x, double y);

__gc class MathOperations
{
public:
	double Plus(double x, double y)
	{
		return x + y;
	}
};

Once again, to associate the method, declare a variable of the type of delegate and pass a reference to the method as the second argument to the constructor of the delegate. Here is an example:

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		MathOperations *oper = new MathOperations;
		Addition *add = new Addition(oper, &MathOperations::Plus);
		
		Multiplication *multi = new Multiplication(NULL, &Times);

		InitializeComponent();
	}

private:
	void InitializeComponent()
	{

	}
	
	static double Times(double x, double y)
	{
		return x * y;
	}
};

Notice that only the name of the method is passed to the delegate. To actually use the value that the delegate produces, when calling its Invoke() method, you must pass the exact number of arguments with their correct values:

#pragma once
#include <windows.h>

#using <mscorlib.dll>
#using <System.dll>
#using <System.Windows.Forms.dll>

using namespace System;
using namespace System::Windows::Forms;

#define NULL 0

private __delegate double Addition(double x, double y);
private __delegate double Multiplication(double x, double y);

__gc class MathOperations
{
public:
	double Plus(double x, double y)
	{
		return x + y;
	}
};

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		double value1 = 90.18, value2 = 42.75;

		MathOperations *oper = new MathOperations;
		Addition *add = new Addition(oper, &MathOperations::Plus);
		
		Multiplication *multi = new Multiplication(NULL, &Times);

		InitializeComponent();

		double nbr = multi->Invoke(value1, value2);
		this->Text = nbr.ToString();
	}

private:
	void InitializeComponent()
	{

	}
	
	static double Times(double x, double y)
	{
		return x * y;
	}
};

int APIENTRY WinMain(HINSTANCE hInstance,
                     HINSTANCE hPrevInstance,
                     LPTSTR    lpCmdLine,
                     int       nCmdShow)
{
	Application::Run(new CExercise);

	return 0;
}

Using delegates, one method can be indirectly passed as argument to another method. To proceed, first declare the necessary delegate. Here is a example of such a delegate:

public __delegate double Squared(double x);

A delegate can be passed as argument to a method. Such an argument would be used as if it were a method itself. This means that, when accessed in the body of the method, the name of the delegate must be accompanied by parentheses and if the delegate takes an argument or arguments, the argument(s) must be provided in the parentheses of the called delegate. Here is an example:

public __delegate double Squared(double x);

public __gc class Circle
{
private:
	double _radius;

public:
	double Area(Squared *sqd)
	{
		return sqd(_radius) * Math::PI;
	}

public:
	__property double get_Radius() { return _radius; }
	__property void   set_Radius(double r) { _radius = r; }
};

After declaring a delegate, remember to define a method that implements the needed behavior of that delegate. Here is an example:

public __delegate double Squared(double x);

public __gc class Circle
{
private:
	double _radius;

public:
	double Area(Squared *sqd)
	{
		return sqd(_radius) * Math::PI;
	}

	static double ValueTimesValue(double Value)
	{
		return Value * Value;
	}

public:
	__property double get_Radius() { return _radius; }
	__property void   set_Radius(double r) { _radius = r; }
};

You can also define the associated method in another class, not necessarily in the class where the delegate would be needed. Once the method that implements the delegate is known, you can use the delegate as you see fit. To do that, you can declare a pointer of the type of that delegate and pass the implementing method to its constructor. Here is an example:

using namespace System;

namespace GeometricFormulas
{
	public delegate double Squared(double x);

	public class Circle
	{
		private double _radius;


		public static double ValueTimesValue(double Value)
		{
			return Value * Value;
		}

		public double Area(Squared sqd)
		{
			return sqd(_radius) * Math.PI;
		}

		public void CircleCharacteristics()
		{
			Squared Sq = new Squared(ValueTimesValue);
		}
	}

}

This declaration gives life to the delegate and can then be used as we have proceed with delegates so far. Here is an example:

#pragma once
#include <windows.h>

#using <mscorlib.dll>
#using <System.dll>
#using <System.Windows.Forms.dll>

using namespace System;
using namespace System::Windows::Forms;

#define NULL 0

public __delegate double Squared(double x);

public __gc class Circle
{
private:
	double _radius;

public:
	double Area(Squared *sqd)
	{
		return sqd(_radius) * Math::PI;
	}

	static double ValueTimesValue(double Value)
	{
		return Value * Value;
	}

public:
	__property double get_Radius() { return _radius; }
	__property void   set_Radius(double r) { _radius = r; }
};

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		Circle *round = new Circle;
		Squared *sqr = new Squared(round, Circle::ValueTimesValue);

		round->Radius = 32.48;

		InitializeComponent();

		this->Text = sqr->Invoke(round->Radius).ToString();
	}

private:
	void InitializeComponent()
	{

	}
};

int APIENTRY WinMain(HINSTANCE hInstance,
                     HINSTANCE hPrevInstance,
                     LPTSTR    lpCmdLine,
                     int       nCmdShow)
{
	Application::Run(new CExercise);

	return 0;
}

This would produce:

The primary role of a control that belongs to an application is to interact with others, either to request values and methods of the other controls or to provide other controls with some values or a behavior they need. When a controls A requests a value or service from another control B, control A is referred to as a client of control B. This relationship is important not simply because it ensures the flow of data between both controls but also because control B should be ready to provide the value or behavior that a client needs at a certain time.

While a control B is asked to provide some values to, or perform some assignment(s) for, another control A, many things would happen. In fact, there is an order that the actions should follow. For example, during the lifetime of a program, that is, while a program is running, a control may be holding a value it can provide to its client but at another time, that value may not be available anymore, for any reason; nothing strange, this is just the ways it happens. Because different things can happen to a control B while a program is running, and because only control B would be aware of these, it must be able to signal to the other control when there is a change. This is the basis of events: An event is an action that occurs on an object and affects it in a way that its clients must be made aware of.

As mentioned already, an event is an action that occurs. For example, suppose you are spaghetti and the red sauce regularly draws some lines on your lips. You know this because your brain sends a signal that your mouth is dirty. To appear fine, you must wipe your mouth regularly. Every time you have wiped your mouth, another signal is sent to the brain to let it know that your mouth is fine now (and when the mouth becomes dirty again, another signal lets the brain know). These signal prompt you to do something. Signaling an event is also referred to as firing it.

Based on its concept, an event is carried by a delegate. This means that, in order to fire an event, you must have defined an appropriate delegate. For good habits, the name of a delegate that signals an event includes EventHandler. For example, if you are declaring a delegate that would carry the signal when your mouth has been wiped, you may call it WipeMouthEventHandler. The WipeMouth part indicates the possible type of signal. The EventHandler part specifies that this delegate is primarily used to handle an event.

A delegate may need additional information in order to carry its signal. Such additional information is called argument(s). You can declare a delegate that doesn't take an argument. For example, when the mouth has been wiped, if you simply want to signal that it has been, you can fire a simple event accordingly. The delegate of such an event may not take any argument. It could be declared as follows:

__delegate void WipeMouthEventHandler();

You can also have a delegate that takes one argument. For example, if you want to define a delegate that would carry the signal that your mouth has been wiped, the delegate can take as arguments the name of the hand that wiped the mouth (unless you can afford an assistant who would do that for you). Such a delegate could be declared as follows:

__delegate void WipeMouthEventHandler(int LeftOrRightHand);

You can also have a delegate that takes more than one argument. For example, when you wipe your mouth, you may use use the reverse of your hand, your shirt, or a napkin. To define your delegate, you can provide an additional argument that specifies what you would use to wipe your mouth.

As seen earlier, after declaring a delegate, you must define the method that implements it. Here is an example:

__delegate void WipeMouthEventHandler(int LeftOrRightHand);

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		InitializeComponent();
	}

private:
	void InitializeComponent()
	{

	}
	
	static void MouthWiper(int LeftOrRightHand)
	{

	}
};

An event is declared like a pseudo-variable but based on a delegate. To actually declare an event, you use the __event keyword with the following formula:

Access Level __event PointerToDelegate NameOfEvent;

The Access Level factor specifies whether the events will be used as private, public, or protected using the appropriate C++ keyword: public, private, or protected. You can omit the access level. If you do, the event is considered private.

The __event keyword is required.

To define an event, you must specify the delegate that is used to carry the event. To do this, you must provide the delegate as a pointer.

Like everything in a program, an event must have a name. This would allow the clients to know what (particular) event occurred. To be indicative, the name of an event starts with On and usually ends with the beginning name of its delegate without the EventHandler part. Here is an example:

__delegate void WipeMouthEventHandler(int LeftOrRightHand);

public __gc class CExercise : public Form
{
public:
	__event WipeMouthEventHandler *OnWipeMouth;

	CExercise(void)
	{

	}
};

When the event occurs, its delegate would be invoked. This specification is also referred to as hooking up an event. As the event occurs (or fires), the method that implements the delegate runs. This provides the functionality of the event and makes the event ready to be used. Both the declarations of the delegate and of the event we have performed above are not related, we only gave them name that resemble each other. Before using an event, you must combine it to the delegate that will carry it. To do this, you must declare a pointer to the event. To initialize it, you would call the constructor of the delegate, passing it the two arguments that we reviewed earlier. To combine the delegate and the event, you initialize the event using the += operator. Once this is done, you can call the event. Here is an example:

#pragma once
#include <windows.h>

#using <mscorlib.dll>
#using <System.dll>
#using <System.Windows.Forms.dll>

using namespace System;
using namespace System::Windows::Forms;

__delegate void WipeMouthEventHandler(int LeftOrRightHand);

public __gc class CExercise : public Form
{
public:
	__event WipeMouthEventHandler *OnWipeMouth;

	CExercise(void)
	{
		InitializeComponent();
	}

private:
	void InitializeComponent()
	{
		OnWipeMouth += new WipeMouthEventHandler(0, &MouthWiper);
	}
	
	static void MouthWiper(int LeftOrRightHand)
	{

	}
};

int APIENTRY WinMain(HINSTANCE hInstance,
                     HINSTANCE hPrevInstance,
                     LPTSTR    lpCmdLine,
                     int       nCmdShow)
{
	Application::Run(new CExercise);

	return 0;
}

An application is made of various objects or controls. During the lifetime of an application, its controls regularly send messages to the operating system to do something on their behalf. These messages are similar to human messages and must be processed appropriately. Since most of the time more than one application is running on the computer, the controls of such an application also send messages to the operating system. As the operating system is constantly asked to perform these assignments, because there can be so many requests presented unpredictably, the operating system leaves it up to the controls to specify what they want, when they want it, and what behavior or result they expect. These scenarios work by the controls sending events.

Events in the .NET Framework are implements through the concepts of delegates and events as reviewed above. The most common events have already been created for the objects of the .NET Framework controls so much that you will hardly need to define new events, at least not in the beginning of your GUI programming adventure. Most of what you will do consists of implementing the desired behavior when a particular event fires. To start, you should know what events are available, when they are needed, how they work, and what they produce.

To process a message, it (the message) must provide at least two pieces of information: What caused the message and what type of message is it? Both values are passed as the arguments to the event. Since all controls used in the .NET Framework are based on the Object class, the first argument must be an Object type and represents the control that sent the message. 

As mentioned already, each control sends its own messages when necessary. Based on this, some messages are unique to some controls according to their roles. Some other messages are common to various controls, as they tend to provide similar actions. To manage such various configurations, the .NET Framework considers the messages in two broad categories.

Some messages don't require much information. This type of message would be sent without much detailed information. This type of message is carried by an argument of type EventArgs passed as the second parameter of the event.

Some messages must be accompanied by additional information. When a message must carry additional information, the control that sent the message specifies that information by the name of the second argument. Because there are various types of messages like that, there are also different types of classes used to carry such messages. We will introduce each class when appropriate.

Although there are different means of implementing an event, there are three main ways you can initiate its coding. If the control has a default event and if you double-click it, the studio would initiate the default event and open the Code Editor. The cursor would be positioned in the body of the event, ready to receive your instructions. Another technique you can use consists of displaying the form first and clicking either the form or the control that will fire the event. Then, in the Properties window, click the Events button , and double-click the name of the event you want to use.

You can also manually code an event. To do this, first define the method that will carry the event. Here is an example:

public __gc class CExercise : public Form
{
public:
	CExercise(void)
	{
		InitializeComponent();
	}

private:
	void InitializeComponent()
	{

	}
	
	Void WasClicked(Object *sender, EventArgs *e)
	{
		Close();
	}
};

Then, add the control if it is not added yet. Use the += operator to assign the type of delegate that handles the event, passing as the second argument the name of the method defined above. This assignment must be performed on the name of the event that will be fired. Here is an example: