Event 陳述式
更新：2007 年 11 月
宣告使用者定義事件。
[ <attrlist> ] [ accessmodifier ] _
[ Shared ] [ Shadows ] Event eventname[(parameterlist)] _
[ Implements implementslist ]
' -or-
[ <attrlist> ] [ accessmodifier ] _
[ Shared ] [ Shadows ] Event eventname As delegatename _
[ Implements implementslist ]
' -or-
[ <attrlist> ] [ accessmodifier ] _
[ Shared ] [ Shadows ] Custom Event eventname As delegatename _
[ Implements implementslist ]
[ <attrlist> ] AddHandler(ByVal value As delegatename)
[ statements ]
End AddHandler
[ <attrlist> ] RemoveHandler(ByVal value As delegatename)
[ statements ]
End RemoveHandler
[ <attrlist> ] RaiseEvent(delegatesignature)
[ statements ]
End RaiseEvent
End Event
參數
組成部分 |
描述 |
||||||
|---|---|---|---|---|---|---|---|
attrlist |
選擇項，套用至這個事件的屬性 (Attribute) 清單。屬性之間以逗號分隔。您必須將 屬性清單置於角括弧中 ("<" 和 ">")。 |
||||||
accessmodifier |
選擇項，指定哪個程式碼可以存取事件。可以是下列其中一項：
您可以指定 Protected Friend，以便從事件的類別、衍生類別或相同組件內的程式碼進行存取。 |
||||||
Shared |
選擇項，指定這個事件不會與類別或結構的特定執行個體相關聯。 |
||||||
Shadows |
選擇項，表示這個事件會重新宣告並隱藏基底類別中同名的程式設計項目，或一組多載項目。您可以用任意一種宣告項目遮蔽其他宣告項目。 除非無法存取主導遮蔽項目 (Shadowing Element)，否則受遮蔽項目 (Shadowed Element) 無法從遮蔽它的衍生類別進行存取。例如，如果 Private 項目會遮蔽基底類別項目，則無權存取 Private 項目的程式碼會改為存取基底類別項目。 |
||||||
eventname |
必要項，事件的名稱，依照標準變數命名規範來命名。 |
||||||
parameterlist |
選擇項，表示這個事件之參數的區域變數清單。必須以括號括住 參數清單。 |
||||||
Implements |
選擇項，表示此事件會實作介面的事件。 |
||||||
implementslist |
如果提供 Implements，則為必要項。實作的 Sub 程序清單。程序之間以逗號分隔。 implementedprocedure [ , implementedprocedure ...] 每個 implementedprocedure 都具有下列語法和參數： interface.definedname
|
||||||
Custom |
必要項。宣告為 Custom 的事件必須定義自訂的 AddHandler、RemoveHandler 和 RaiseEvent 存取子 (Accessor)。 |
||||||
delegatename |
選擇項。指定事件處理常式簽章之委派的名稱。 |
||||||
AddHandler |
必要項，宣告 AddHandler 存取子，此存取子會指定當加入事件處理常式 (不論是透過明確使用 AddHandler 陳述式，還是隱含使用 Handles 子句) 時，所要執行的陳述式。 |
||||||
End AddHandler |
必要項，結束 AddHandler 區塊。 |
||||||
value |
必要項，參數名稱。 |
||||||
RemoveHandler |
必要項。宣告 RemoveHandler 存取子，此存取子會指定當使用 RemoveHandler 陳述式移除事件處理常式時，所要執行的陳述式。 |
||||||
End RemoveHandler |
必要項，結束 RemoveHandler 區塊。 |
||||||
RaiseEvent |
必要項。宣告 RaiseEvent 存取子，此存取子會指定當使用 RaiseEvent 陳述式引發事件時，所要執行的陳述式。通常這會叫用由 AddHandler 和 RemoveHandler 存取子所維護的委派清單。 |
||||||
End RaiseEvent |
必要項，結束 RaiseEvent 區塊。 |
||||||
delegatesignature |
必要項。符合 delegatename 委派所需參數的參數清單。必須以括號括住 參數清單。 |
||||||
statements |
選擇項。包含 AddHandler、RemoveHandler 和 RaiseEvent 方法之主體的陳述式。 |
||||||
End Event |
必要項，結束 Event 區塊。 |
備註
一旦宣告事件後，請使用 RaiseEvent 陳述式來引發事件。一般事件可依照下面程式碼片段中顯示的來宣告和引發：
Public Class EventSource
' Declare an event.
Public Event LogonCompleted(ByVal UserName As String)
Sub CauseEvent()
' Raise an event on successful logon.
RaiseEvent LogonCompleted("AustinSteele")
End Sub
End Class
.gif "注意事項") 注意事項： |
|---|
您可以利用宣告程序引數的方式來宣告事件引數，不過下列情況除外：事件不可擁有具名引數、ParamArray 引數或 Optional 引數。事件不具傳回值。 |
若要處理事件，您必須使用 Handles 或 AddHandler 陳述式，建立事件與事件處理常式的關聯。副程式與事件的簽章必須相符。若要處理共用事件，您必須使用 AddHandler 陳述式。
只能在模組層級使用 Event。這表示事件的「宣告內容」必須是類別、結構、模組或介面，且不能是原始程式檔 (Source File)、命名空間 (Namespace)、程序或區塊。如需詳細資訊，請參閱宣告內容和預設存取層級。
在大多數情況下，您可以使用本主題之「語法」一節中用於宣告事件的第一個語法。不過，某些案例需要您對事件的細部行為有更多控制。本主題之「語法」一節中的最後一個語法，可藉由讓您使用 Custom 關鍵字定義自訂事件，進而提供這樣的控制能力。在自訂事件中，您可以確切地指出當程式碼將事件處理常式加入至事件或從中移除時，或當程式碼引發事件時，會發生什麼情況。如需詳細資訊，請參閱 HOW TO：宣告節省記憶體使用量的事件和 HOW TO：宣告避免封鎖的事件。
範例
下列範例會使用事件以便從 10 秒倒數計時到 0 秒。這個程式碼將說明數個與事件相關的方法、屬性和陳述式，包括 RaiseEvent 陳述式。
引發事件的類別是事件來源 (Event Source)，而處理事件的方法則是事件處理常式。一個事件來源可有多個處理常式來處理產生的事件。當類別引發事件時，這個事件便會在每個選定為物件執行個體處理事件的類別上引發。
這個範例也會使用包含一個按鈕 (Button1) 和一個文字方塊 (TextBox1) 的表單 (Form1)。當您按一下按鈕時，第一個文字方塊會顯示從 10 秒到 0 秒的倒數計時。整段時間 (10 秒) 結束時，第一個文字方塊會顯示「完成」。
Form1 的程式碼會指定表單的初始和終結狀態。其中也包含引發事件時執行的程式碼。
若要使用這個範例，請開啟新的 Windows Form 專案。接著將名為 Button1 的按鈕和名為 TextBox1 的文字方塊加入至名為 Form1 的主要表單。然後以滑鼠右鍵按一下表單，再按 [檢視程式碼]，以開啟程式碼編輯器。
將 WithEvents 變數加入至 Form1 類別的宣告區段中。
Private WithEvents mText As TimerState
將下列程式碼加入至 Form1 的程式碼中：請取代任何可能存在的重複程序，例如 Form_Load 或 Button_Click。
Private Sub Form1_Load(ByVal sender As Object, _
ByVal e As System.EventArgs) _
Handles MyBase.Load
Button1.Text = "Start"
mText = New TimerState
End Sub
Private Sub Button1_Click(ByVal sender As System.Object, _
ByVal e As System.EventArgs) _
Handles Button1.Click
mText.StartCountdown(10.0, 0.1)
End Sub
Private Sub mText_ChangeText() Handles mText.Finished
TextBox1.Text = "Done"
End Sub
Private Sub mText_UpdateTime(ByVal Countdown As Double) _
Handles mText.UpdateTime
TextBox1.Text = Format(Countdown, "##0.0")
' Use DoEvents to allow the display to refresh.
My.Application.DoEvents()
End Sub
Class TimerState
Public Event UpdateTime(ByVal Countdown As Double)
Public Event Finished()
Public Sub StartCountdown(ByVal Duration As Double, _
ByVal Increment As Double)
Dim Start As Double = DateAndTime.Timer
Dim ElapsedTime As Double = 0
Dim SoFar As Double = 0
Do While ElapsedTime < Duration
If ElapsedTime > SoFar + Increment Then
SoFar += Increment
RaiseEvent UpdateTime(Duration - SoFar)
End If
ElapsedTime = DateAndTime.Timer - Start
Loop
RaiseEvent Finished()
End Sub
End Class
按 F5 執行上述範例，再按一下標記為 [Start] 的按鈕。第一個文字方塊會開始倒數計時秒數。整段時間 (10 秒) 結束時，第一個文字方塊會顯示「完成」。
| 注意事項： |
|---|
My.Application.DoEvents 方法處理事件的方式和表單處理事件的方式不同。若要讓表單直接處理事件，您可以使用多執行緒處理。如需詳細資訊，請參閱 Visual Basic 中的多執行緒。 |