From: 011netservice@gmail.com
Date: 2022-04-24
Subject: EventArgs.txt, 歡迎來信交流



Represents the base class for classes that contain event data, and provides a value to use for events that do not include event data.
ref:
https://docs.microsoft.com/en-us/dotnet/api/system.eventargs?view=netframework-4.6&f1url=%3FappId%3DDev16IDEF1%26l%3DEN-US%26k%3Dk(System.EventArgs);k(TargetFrameworkMoniker-.NETFramework,Version%253Dv4.6);k(DevLang-csharp)%26rd%3Dtrue

[System.Serializable]
[System.Runtime.InteropServices.ComVisible(true)]
public class EventArgs

The following example shows a custom event data class named ThresholdReachedEventArgs that derives from the EventArgs class. An instance of the event data class is passed to the event handler for the ThresholdReached event.

using System;

namespace ConsoleApplication1
{
    class Program
    {
        static void Main(string[] args)
        {
            Counter c = new Counter(new Random().Next(10));
            c.ThresholdReached += c_ThresholdReached;  // 實體函數對應到事件通知.

            Console.WriteLine("press 'a' key to increase total");
            while (Console.ReadKey(true).KeyChar == 'a')
            {
                Console.WriteLine("adding one");
                c.Add(1);
            }
        }

        static void c_ThresholdReached(object sender, ThresholdReachedEventArgs e) // 實體函數回應事件通知.
        {
            Console.WriteLine("The threshold of {0} was reached at {1}.", e.Threshold,  e.TimeReached);
            Environment.Exit(0);
        }
    }

    class Counter
    {
        private int threshold;
        private int total;

        public Counter(int passedThreshold)
        {
            threshold = passedThreshold;
        }

        public void Add(int x)
        {
            total += x;
            if (total >= threshold)
            {
                ThresholdReachedEventArgs args = new ThresholdReachedEventArgs(); // 將要傳遞的資料以 EventArgs 方式包裝.
                args.Threshold = threshold;
                args.TimeReached = DateTime.Now;
				
                OnThresholdReached(args); // 傳入資料, 發出事件通知.
            }
        }

        protected virtual void OnThresholdReached(ThresholdReachedEventArgs e) // 提供外部發出事件通知方法.
        {
            EventHandler<ThresholdReachedEventArgs> handler = ThresholdReached; 
            if (handler != null)
            {
                handler(this, e); // 發出事件通知.
            }
        }

		// 使用 EventHandler<TEventArgs> delegate 語法, 可以簡化自訂事件函數的步驟, 只要將要傳遞的 EventArgs 型態的資料代入 TEventArgs.
        public event EventHandler<ThresholdReachedEventArgs> ThresholdReached; 
    }

	
    public class ThresholdReachedEventArgs : EventArgs   // 繼承 EventArgs 後可於事件通知時傳遞資料.
    {
        public int Threshold { get; set; }
        public DateTime TimeReached { get; set; }
    }
}

Remarks
This class serves as the base class for all classes that represent event data. For example, the System.AssemblyLoadEventArgs class derives from EventArgs and is used to hold the data for assembly load events. To create a custom event data class, create a class that derives from the EventArgs class and provide the properties to store the necessary data. The name of your custom event data class should end with EventArgs.

To pass an object that does not contain any data, use the Empty field.



Remarks:
The event model in the .NET Framework is based on having an event delegate that connects an event with its handler. To raise an event, two elements are needed:
1. A delegate that refers to a method that provides the response to the event.
2. Optionally, a class that holds the event data, if the event provides data.
.NET Framework 的事件模型建立在(一個 event delegate)連結到處理函數.
要發出一個事件訊息, 必須有兩個元素:
1. 一個代理函數(delegate) 對應到 (回應事件訊息)的實體函數.
2. 若事件訊息需要傳遞資料, 則可透過物件(class)包含資料. 

The delegate is a type that defines a signature, that is, the return value type and parameter list types for a method. You can use the delegate type to declare a variable that can refer to any method with the same signature as the delegate.
代理函數是一個函數型別定義(signature), 可連結到符合定義的任何實體函數.

The standard signature of an event handler delegate defines a method that does not return a value. This method's first parameter is of type Object and refers to the instance that raises the event. Its second parameter is derived from type EventArgs and holds the event data. If the event does not generate event data, the second parameter is simply the value of the EventArgs.Empty field. Otherwise, the second parameter is a type derived from EventArgs and supplies any fields or properties needed to hold the event data.
標準的事件訊息定義( event handler delegate), 必須是一個沒有回傳值的函數, 
並且第1個參數型別為 Object, 代表發出訊息的來源,
第2個參數型別為 EventArgs 包含了需要傳遞的資料. 若不需要傳遞資料, 則可代入 EventArgs.Empty.

The EventHandler<TEventArgs> delegate is a predefined delegate that represents an event handler method for an event that generates data. The advantage of using EventHandler<TEventArgs> is that you do not need to code your own custom delegate if your event generates event data. You simply provide the type of the event data object as the generic parameter.
使用 EventHandler<TEventArgs> delegate 預先定義的代理函數的語法, 可以簡化自訂事件函數的步驟, 只要將要傳遞的資料代入 TEventArgs.

To associate the event with the method that will handle the event, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate.
實體函數對應到事件定義後, 只要發出事件通知時, 對應的實體函數就會啟動執行回應事件通知. 





----------
20200920

using System;

// FireEventArgs: a custom event inherited from EventArgs.

// 自訂參數需繼承自EventArgs
public class FireEventArgs: EventArgs {
	public FireEventArgs(string room, int ferocity) {
		this.room = room;
		this.ferocity = ferocity;
	}

	// The fire event will have two pieces of information-- 
	// 1) Where the fire is, and 2) how "ferocious" it is.  

	public string room;
	public int ferocity;

}	//end of class FireEventArgs


// Class with a function that creates the eventargs and initiates the event
public class FireAlarm {

	// Events are handled with delegates, so we must establish a FireEventHandler
	// as a delegate:
	
	// 宣告delegate名稱與參數約定
	public delegate void FireEventHandler(object sender, FireEventArgs fe);

	// Now, create a public event "FireEvent" whose type is our FireEventHandler delegate. 
	// Event與delegate需對應建立.
	public event FireEventHandler FireEvent;	

	// This will be the starting point of our event-- it will create FireEventArgs,
	// and then raise the event, passing FireEventArgs. 

	public void ActivateFireAlarm(string room, int ferocity) {

	    // 建立實體自訂參數
		FireEventArgs fireArgs = new FireEventArgs(room, ferocity);

		// Now, raise the event by invoking the delegate. Pass in 
		// the object that initated the event (this) as well as FireEventArgs. 
		// The call must match the signature of FireEventHandler.
        
		// 送出Event, 參數(sender=this, arg=自訂參數)
		FireEvent(this, fireArgs); 
	}
}	// end of class FireAlarm


// Class which handles the event

class FireHandlerClass {

	// Create a FireAlarm to handle and raise the fire events. 

	public FireHandlerClass(FireAlarm fireAlarm)	{

		// Add a delegate containing the ExtinguishFire function to the class'
		// event so that when FireAlarm is raised, it will subsequently execute 
		// ExtinguishFire.

		fireAlarm.FireEvent += new FireAlarm.FireEventHandler(ExtinguishFire);
	}

	// This is the function to be executed when a fire event is raised. 

	void ExtinguishFire(object sender, FireEventArgs fe) {

		Console.WriteLine("\nThe ExtinguishFire function was called by {0}.", sender.ToString());

		// Now, act in response to the event.

		if (fe.ferocity < 2)
			Console.WriteLine("This fire in the {0} is no problem.  I'm going to pour some water on it.", fe.room);
		else if (fe.ferocity < 5)
			Console.WriteLine("I'm using FireExtinguisher to put out the fire in the {0}.",  fe.room);
		else 
			Console.WriteLine("The fire in the {0} is out of control.  I'm calling the fire department!", fe.room);
	}
}	//end of class FireHandlerClass

public class FireEventTest {
	public static void Main () 	{	

		// Create an instance of the class that will be firing an event.

		FireAlarm myFireAlarm = new FireAlarm();
		
		// Create an instance of the class that will be handling the event. Note that 
		// it receives the class that will fire the event as a parameter. 

		FireHandlerClass myFireHandler = new FireHandlerClass(myFireAlarm);
		
		//use our class to raise a few events and watch them get handled
		// 送出不同的event
		myFireAlarm.ActivateFireAlarm("Kitchen", 3);
		myFireAlarm.ActivateFireAlarm("Study", 1);
		myFireAlarm.ActivateFireAlarm("Porch", 5);
		
		return;

	}	//end of main

}	// end of FireEventTest