From: 011netservice@gmail.com
Date: 2022-04-24
Subject: EventHandler.txt

[System.Serializable]
public delegate void EventHandler<TEventArgs>(object sender, TEventArgs e);


----------
20210415

ref:
https://docs.microsoft.com/en-us/dotnet/api/system.eventhandler-1?view=netframework-4.6&f1url=%3FappId%3DDev16IDEF1%26l%3DEN-US%26k%3Dk(System.EventHandler);k(TargetFrameworkMoniker-.NETFramework,Version%253Dv4.6);k(DevLang-csharp)%26rd%3Dtrue

The following example shows an event named ThresholdReached. The event is associated with an EventHandler<TEventArgs> delegate.


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); // 發出事件通知.
            }
        }

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

    public class ThresholdReachedEventArgs : EventArgs  // 若事件通知需要傳遞資料, 則可繼承 EventArgs 後, 以欄位資料方式傳遞.
    {
        public int Threshold { get; set; }
        public DateTime TimeReached { get; set; }
    }
}

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.
實體函數對應到事件定義後, 只要發出事件通知時, 對應的實體函數就會啟動執行回應事件通知.