event (C++ 元件擴充功能)

event 關鍵字會宣告「事件」(Event)，這是提供給已註冊訂閱者 (「事件處理常式」(Event Handler)) 的通知，表示相關的事情發生了。

所有執行階段

C++/CX 支援宣告「事件成員」(Event Member) 或「事件區塊」(Event Block)。 事件成員是用於宣告事件區塊的速記。 根據預設，事件成員會宣告明確宣告於事件區塊中的 add()、remove() 和 raise() 函式。 若要自訂事件成員中的函式，請宣告事件區塊，然後覆寫您需要的函式。

語法

// event data member
modifier event delegate^ event_name;   

// event block
modifier event delegate^ event_name 
{
   modifier return_value add(delegate^ name);
   modifier void remove(delegate^ name);
   modifier void raise(parameters);
}

參數

• 修飾詞
  可以用於事件宣告或事件存取子方法的修飾詞。 可能的值為 static 和 virtual。

• 委派
  委派，其簽章必須與事件處理常式相符。

• event_name
  事件的名稱。

• return_value
  事件存取子方法的傳回值型別。 若要可驗證，傳回型別必須是 void。

• 參數
  (選擇性) raise 方法的參數，這些參數與 delegate 參數相符。

備註

事件是委派和成員函式 (事件處理常式) 之間的關聯，這個關聯可回應事件的觸發，並允許任何類別中的用戶端註冊符合基礎委派之簽章與傳回型別的方法。

事件宣告有兩種類型：

• 「事件資料成員」(Event Data Member)
  編譯器會自動以委派型別成員的形式建立事件的儲存區，並建立內部 add()、remove() 和 raise() 成員函式。 事件資料成員必須在類別內宣告。 委派的傳回型別必須符合事件處理常式的傳回型別。

• 「事件區塊」(Event Block)
  事件區塊可讓您明確宣告和自訂 add()、remove() 及 raise() 方法的行為。

您可以使用 operators+= 和 operator-= 新增和移除事件處理常式，或明確呼叫 add() 和 remove() 方法。

event 為內容相關性關鍵字。如需詳細資訊，請參閱視內容而有所區別的關鍵字 (C++ 元件擴充功能)。

Windows 執行階段

備註

如需詳細資訊，請參閱事件 (C++/CX)。

如果您想要新增事件處理常式，然後再加以移除，則必須儲存新增作業所傳回的 EventRegistrationToken 結構。 然後在移除作業中，您必須使用儲存的 EventRegistrationToken 結構來識別要移除的事件處理常式。

需求

編譯器選項：/ZW

Common Language Runtime

event 關鍵字可讓您宣告事件。 某些相關的事情發生時，事件會是類別用來提供通知的一種方式。

語法

// event data member
modifier event delegate^ event_name; 

// event block
modifier event delegate^ event_name 
{
   modifier return_value add(delegate^ name);
   modifier void remove(delegate^ name);
   modifier void raise(parameters);
}

參數

• 修飾詞
  可以用於事件宣告或事件存取子方法的修飾詞。 可能的值為 static 和 virtual。

• 委派
  委派，其簽章必須與事件處理常式相符。

• event_name
  事件的名稱。

• return_value
  事件存取子方法的傳回值型別。 若要可驗證，傳回型別必須是 void。

• 參數
  (選擇性) raise 方法的參數，這些參數與 delegate 參數相符。

備註

事件是委派和成員函式 (事件處理常式) 之間的關聯，這個關聯可回應事件的觸發，並允許任何類別中的用戶端註冊符合基礎委派之簽章與傳回型別的方法。

委派可以有一個或多個相關聯的方法，當您的程式碼表示有事件發生時，將會呼叫這些方法。 一個程式中的事件可以提供給目標設為 .NET Framework Common Language Runtime 的其他程式使用。 如需範例，請參閱引發不同組件中定義的事件。

事件宣告有兩種類型：

• 「事件資料成員」(Event Data Member)
  事件的儲存區 (採用委派型別成員的形式) 是由編譯器針對資料成員事件所建立。 事件資料成員必須在類別內宣告。 這也稱為 trivial 事件 (請參閱下面的程式碼範例)。

• 「事件區塊」(Event Block)
  事件區塊可讓您藉由實作加入、移除和引發等方法，自訂加入、移除及引發方法的行為。 add、remove 和 raise 方法的簽章必須符合委派的簽章。 事件區塊事件不是資料成員，因此當做資料成員使用的任何事件區塊事件都會產生編譯器錯誤。 如需範例，請參閱定義事件存取子方法。

事件處理常式的傳回型別必須符合委派的傳回型別。

在 .NET Framework 中，您可以將資料成員視同方法本身 (也就是，其對應委派的 Invoke 方法)。 您必須預先定義用來宣告 Managed 事件資料成員的委派型別。 相反地，Managed 事件方法會隱含定義對應的 Managed 委派 (如果尚未定義的話)。 如需範例，請參閱本主題結尾的程式碼範例。

宣告 Managed 事件時，您可以指定會在使用 += 和 -= 運算子加入或移除事件處理常式時呼叫的 add 和 remove 存取子。 add、remove 和 raise 是可以明確呼叫的方法。

在 Visual C++ 中必須採取下列步驟才能建立和使用事件：

1. 建立或識別委派。 如果您要定義自己的事件，您也必須確定已有搭配 event 關鍵字使用的委派。 如果事件是預先定義的 (例如，在 .NET Framework 中定義)，則事件的消費者只需要知道委派的名稱。

2. 建立包含下列項目的類別：

   • 從委派建立的事件。

   • (選擇性) 一個驗證使用 event 關鍵字所宣告之委派執行個體是否存在的方法。 否則，這個邏輯必須置於引發事件的程式碼中。

   • 呼叫事件的方法。 這些方法可以是某些基底類別功能的覆寫。

   這個類別會定義事件。

3. 定義一個或多個連接方法與事件的類別。 這其中每一個類別都會將一個或多個方法與基底類別中的事件建立關聯。

4. 使用事件：

   • 建立包含事件宣告之類別的物件。

   • 建立包含事件定義之類別的物件。

如需 C++/CLI 事件的詳細資訊，請參閱

• 介面中的事件

• 覆寫 add、remove 和 raise 方法的預設存取

• 事件的多個處理常式

• Managed 虛擬事件

• 事件存取子方法

• 靜態事件

• 引發不同組件中定義的事件

• 抽象事件

需求

編譯器選項：/clr

範例

範例

下列程式碼範例示範宣告成對的委派、事件和事件處理常式；訂閱 (新增) 事件處理常式；叫用事件處理常式，然後取消訂閱 (移除) 事件處理常式。

// mcppv2_events.cpp
// compile with: /clr
using namespace System;

// declare delegates
delegate void ClickEventHandler(int, double);
delegate void DblClickEventHandler(String^);

// class that defines events
ref class EventSource {
public:
   event ClickEventHandler^ OnClick;   // declare the event OnClick
   event DblClickEventHandler^ OnDblClick;   // declare OnDblClick

   void FireEvents() {
      // raises events
      OnClick(7, 3.14159);
      OnDblClick("Hello");
   }
};

// class that defines methods that will called when event occurs
ref class EventReceiver {
public:
   void OnMyClick(int i, double d) {
      Console::WriteLine("OnClick: {0}, {1}", i, d);
   }

   void OnMyDblClick(String^ str) {
      Console::WriteLine("OnDblClick: {0}", str);
   }
};

int main() {
   EventSource ^ MyEventSource = gcnew EventSource();
   EventReceiver^ MyEventReceiver = gcnew EventReceiver();

   // hook handler to event
   MyEventSource->OnClick += gcnew ClickEventHandler(MyEventReceiver, &EventReceiver::OnMyClick);
   MyEventSource->OnDblClick += gcnew DblClickEventHandler(MyEventReceiver, &EventReceiver::OnMyDblClick);

   // invoke events
   MyEventSource->FireEvents();

   // unhook handler to event
   MyEventSource->OnClick -= gcnew ClickEventHandler(MyEventReceiver, &EventReceiver::OnMyClick);
   MyEventSource->OnDblClick -= gcnew DblClickEventHandler(MyEventReceiver, &EventReceiver::OnMyDblClick);
}

Output

範例

下列程式碼範例示範用於產生 trivial 事件之 raise 方式的邏輯：如果事件有一個或多個訂閱者，則呼叫 raise 方法會隱含或明確呼叫委派。 如果委派的傳回型別不是 void，而且沒有事件訂閱者，則 raise 方法會傳回委派型別的預設值。 如果沒有事件訂閱者，則呼叫 raise 方法只是單純返回，而不會引發任何例外狀況。 如果委派的傳回型別不是 void，則傳回委派型別。

// trivial_events.cpp
// compile with: /clr /c
using namespace System;
public delegate int Del();
public ref struct C {
   int i;
   event Del^ MyEvent;

   void FireEvent() {
      i = MyEvent();
   }
};

ref struct EventReceiver {
   int OnMyClick() { return 0; }
};

int main() {
   C c;
   c.i = 687;

   c.FireEvent();
   Console::WriteLine(c.i);
   c.i = 688;

   EventReceiver^ MyEventReceiver = gcnew EventReceiver();
   c.MyEvent += gcnew Del(MyEventReceiver, &EventReceiver::OnMyClick);
   Console::WriteLine(c.i);   
}

Output

請參閱

概念

執行階段平台的元件擴充功能