EventList.AddAdvise 方法 (Visio)

  • 發行項

會針對想要接收其事件的來源物件，將 Event 物件新增至該物件的 EventList 集合。 發生選取的事件時，來源物件會通知您的接收器物件。

語法

運算式。 AddAdvise( _EventCode_ , _SinkIUnkOrIDisp_ , _IIDSink_ , _TargetArgs_ )

表達 代表 EventList 物件的變數。

參數

名稱 必要/選用 資料類型 描述
EventCode 必要 整數 產生通知的事件
SinkIUnkOrIDisp 必要 Variant 對要接收通知的物件上之 COM 介面的參考
IIDSink 必要 String 保留供日後使用。 必須為 ""
TargetArgs 必要 字串 傳遞給 Event 物件，以便設定物件 TargetArgs 屬性的字串。

傳回值

事件

註解

使用AddAdvise方法建立的事件物件具有visActCodeAdvise的Action屬性。 這些物件是不可保留的，也就是說無法與 Visio 文件一起儲存，而必須在執行階段重建。

當來源物件的 EventList 集合含有 Event 物件時，會限制事件的報告範圍。 所報告的事件範圍，僅限於來源物件以及物件模型階層中較低層級的物件。 例如，若要在儲存特定檔時接收通知，請將DocumentSaved事件的Event物件新增至該檔的EventList集合。 若要在應用程式的執行個體中開啟任何文件時收到通知，可將 Event 物件新增至 Application 物件的 EventList 集合。

建立 Event 物件是處理來自 C++ 或其他非 Microsoft Visual Basic 解決方案之事件的常用方式。 當您使用 Visual Basic WithEvents 關鍵字來處理事件時，會引發來源物件事件集中的所有事件。 建立 Event 物件來處理事件時，則程式只會收到所選事件的通知。 根據您使用的解決方案，這可能會獲致效能上的提升。

EventCode 引數通常是多個常數的組合。 例如，visEvtMod + visEvtCell是CellChanged事件的事件代碼。 事件常數是透過 Visio 型態程式庫來宣告，而且開頭為 visEvt。 若要尋找您要建立之事件的事件代碼，請參閱 事件代碼。

傳送至 AddAdvise 方法的引數會為 Event 物件的 Event、Action (visCodeRunAddAdvise) 及 TargetArgs 等屬性設定初始值。

從 Visio 2002 開始，您可以使用事件篩選來細分程式中收到的事件。 篩選事件時，可使用物件、儲存格、儲存格範圍或命令識別碼做為篩選依據。 如需使用事件篩選的詳細資訊，請參閱開頭為 SetFilter 及 GetFilter 的方法主題。

使用AddAdvise方法建立的事件物件具有visActCodeAdvise的Action屬性。 這些物件是不可保留的，也就是說無法與 Visio 文件一起儲存，而必須在執行階段重建。

當來源物件的 EventList 集合含有 Event 物件時，會限制事件的報告範圍。 所報告的事件範圍，僅限於來源物件以及物件模型階層中較低層級的物件。 例如，若要在儲存特定檔時接收通知，請將DocumentSaved事件的Event物件新增至該檔的EventList集合。 若要在應用程式的執行個體中開啟任何文件時收到通知，可將 Event 物件新增至 Application 物件的 EventList 集合。

建立 Event 物件是處理來自 C++ 或其他非 Microsoft Visual Basic 解決方案之事件的常用方式。 當您使用 Visual Basic WithEvents 關鍵字來處理事件時，會引發來源物件事件集中的所有事件。 建立 Event 物件來處理事件時，則程式只會收到所選事件的通知。 根據您使用的解決方案，這可能會獲致效能上的提升。

EventCode 引數通常是多個常數的組合。 例如，visEvtMod + visEvtCell是CellChanged事件的事件代碼。 事件常數是透過 Visio 型態程式庫來宣告，而且開頭為 visEvt。 若要尋找您要建立之事件的事件代碼，請參閱 事件代碼。

傳送至 AddAdvise 方法的引數會為 Event 物件的 Event、Action (visCodeRunAddAdvise) 及 TargetArgs 等屬性設定初始值。

從 Visio 2002 開始，您可以使用事件篩選來細分程式中收到的事件。 篩選事件時，可使用物件、儲存格、儲存格範圍或命令識別碼做為篩選依據。 如需使用事件篩選的詳細資訊，請參閱開頭為 SetFilter 及 GetFilter 的方法主題。

讓程式處理來自 Microsoft Visual Basic 或 Visual Basic for Applications 的事件通知

若要處理通知，您應建立一個實作 IVisEventProc 介面的類別模組，然後建立此類別的執行個體以做為引數傳送至 AddAdvise 方法。

IVisEventProc 介面含有具有下列宣告的單一函數：

Implements IVisEventProc 
 
Private Function IVisEventProc_VisEventProc( _  
    ByVal nEventCode As Integer, _  
    ByVal pSourceObj As Object, _  
    ByVal nEventID As Long, _  
    ByVal nEventSeqNum As Long, _  
    ByVal pSubjectObj As Object, _  
    ByVal vMoreInfo As Variant) As Variant  
End Function

下表列出 VisEventProc引數的描述。

引數 描述
nEventCode 所發生的事件。 您可以為每個事件各提供一個物件，或提供能接收所有通知並根據 nEventCode 進行內部切換的單一物件。
pSourceObj EventList集合包含觸發通知之 Event物件的物件。
nEventID EventList集合內Event物件的唯一識別碼。 (與EventList集合的Index屬性不同，nEventID 不會隨著Event物件加入集合或從集合中刪除而變更。)
使用下列程式碼從VisEventProc取得Event物件：pSourceObj .EventList.ItemFromID(nEventID )
nEventSeqNum 在呼叫應用程式執行個體已發生的事件順序中，事件所佔的序數位置。 發生在 Visio 執行個體中的第一個事件其序號為 1，第二個事件為 2，依此類推。 在某些情況下，您可以使用序號搭配 EventInfo 屬性來取得事件的詳細資訊。
pSubjectObj 與事件有關的物件。 例如，ShapeAdded 事件的主體是 Shape 物件，代表剛新增的圖形，而 BeforeSelectionDelete 事件的主體是 Selection 物件，代表要刪除的選取圖形。
vMoreInfo 事件主體的詳細資訊。 對許多事件而言，它是一個字串，類似於應用程式傳送所執行附加元件的命令列。 如果通知不含額外資訊，此參數會設為 Nothing。 如需特定事件之通知參數的詳細資訊，請參閱本參考中的特定事件主題。

如果 nEventCode 識別了某查詢事件 (事件開頭為 Query)，則傳回 True 會取消該事件，傳回 False 會允許其發生。 此值對其他事件而言是自訂的。 如果不傳回明確的值，Microsoft Visual Basic for Applications (VBA) 會傳回空的 Variant，而 Visio 會將這個值解譯為 False。

除非發生下列其中一項，否則來源物件與 Event 物件之間的連接會一直存在：

  • 程式會刪除 Event 物件。
  • 程式會釋放來源物件的最後一個參考。 (EventList 集合和 Event 物件在其來源物件上保留參考。)
  • 應用程式終止。

從 Visio 2000 開始， VisEventProc 會定義為傳回值的函式。 不過，Visio 只會查看呼叫 VisEventProc 的傳回值，這些呼叫會傳遞查詢事件代碼。 透過IDispatch提供VisEventProc的事件物件不需要變更。 若要修改現有的事件處理常式以便處理查詢事件，請將 Sub 程式變更為 Function 程式，並傳回適當的值。 (如需查詢事件的詳細資訊，請參閱此參考以 Query.)

範例

本範例會顯示如何建立類別模組，以處理由 Microsoft Office Visio 中的來源物件 (例如 Document 物件) 所引發的事件。 模組內含函數 VisEventProc 會使用 Select Case 區塊來檢查下列三個事件：DocumentSaved、PageAdded 及 ShapesDeleted。 其他事件則歸為預設情況 (Case Else)。 每個 Case 區塊都會建構一個字串 ( strMessage ) ，其中包含所引發事件的名稱和事件代碼。 最後，該函數會在 [立即] 視窗中顯示字串。

請將本範例程式碼複製到 Microsoft Visual Basic for Applications (VBA) 或 Visual Basic 新的類別模組中，並將該模組命名為 clsEventSink。 然後，您就可以使用事件接收模組來建立 clsEventSink 類別的執行個體，以及可將發生事件的通知傳送給類別執行個體的 Event 物件。

Implements Visio.IVisEventProc  
 
'Declare visEvtAdd as a 2-byte value 
'to avoid a run-time overflow error 
Private Const visEvtAdd% = &H8000 
 
Private Function IVisEventProc_VisEventProc( _  
    ByVal nEventCode As Integer, _  
    ByVal pSourceObj As Object, _  
    ByVal nEventID As Long, _  
    ByVal nEventSeqNum As Long, _  
    ByVal pSubjectObj As Object, _  
    ByVal vMoreInfo As Variant) As Variant  
 
    Dim strMessage As String 
     
    'Find out which event fired 
    Select Case nEventCode  
        Case visEvtCodeDocSave  
            strMessage = "DocumentSaved (" & nEventCode & ")"  
        Case (visEvtPage + visEvtAdd)  
            strMessage = "PageAdded (" & nEventCode & ")"  
        Case visEvtCodeShapeDelete 
            strMessage = "ShapesDeleted(" & nEventCode & ")"  
        Case Else  
            strMessage = "Other (" & nEventCode & ")"  
    End Select 
     
    'Display the event name and the event code 
    Debug.Print strMessage  
 
End Function

下列 VBA 模組會顯示如何使用 AddAdvise 方法接收事件。 該模組含有兩個公用程序。

CreateEventObjects 程序會建立 Sink 物件 (事件處理) 類別的實例，此類別稱為 clsEventSink 且會被傳送到 AddAdvise 方法並接收事件的通知。 此外，該程序會建立三個 Event 物件，用以將源自 Document 物件的下列三個事件觸發通知傳送給接收器物件：DocumentSaved、PageAdded 及 ShapesDeleted。

DeleteEventObjects 程序會在您的程式用完這些 Event 物件後加以刪除。

clsEventSink 類別會實作 IVisEventProc 介面。

下列範例假設 Visio 應用程式視窗中有使用中檔。

Option Explicit 
 
Private mEventSink As clsEventSink 
 
Dim vsoDocumentEvents As Visio.EventList       
Dim vsoDocumentSavedEvent As Visio.Event  
Dim vsoPageAddedEvent As Visio.Event  
Dim vsoShapesDeletedEvent As Visio.Event 
    
'Declare visEvtAdd as a 2-byte value 
'to avoid a run-time overflow error 
Private Const visEvtAdd% = &H8000  
 
Public Sub CreateEventObjects()      
 
    'Create an instance of the clsEventSink class 
    'to pass to the AddAdvise method. 
    Set mEventSink = New clsEventSink 
  
    'Get the EventList collection of the active document. 
    Set vsoDocumentEvents = ActiveDocument.EventList  
 
    'Add Event objects that will send notifications. 
    'Add an Event object for the DocumentSaved event. 
    Set vsoDocumentSavedEvent= vsoDocumentEvents.AddAdvise( _  
     visEvtCodeDocSave, mEventSink, "", "Document saved...")  
 
    'Add an Event object for the PageAdded event. 
    Set vsoPageAddedEvent= vsoDocumentEvents.AddAdvise( _  
     visEvtAdd + visEvtPage, mEventSink, "", "Page added...")  
 
    'Add an Event object for the ShapesDeleted event. 
    Set vsoShapesDeletedEvent = vsoDocumentEvents.AddAdvise( _  
     visEvtCodeShapeDelete, mEventSink, "", "Shapes deleted...")  
 
End Sub   
 
Public Sub DeleteEventObjects()  
 
    'Delete the Event object for the DocumentSaved event.    
    vsoDocumentSavedEvent.Delete  
    Set vsoDocumentSavedEvent = Nothing 
 
    'Delete the Event object for the PageAdded event. 
    vsoPageAddedEvent.Delete  
    Set vsoPageAddedEvent = Nothing 
 
    'Delete the Event object for the ShapesDeleted event.  
    vsoShapesDeletedEvent.Delete  
    Set vsoShapesDeletedEvent = Nothing 
 
End Sub

支援和意見反應

有關於 Office VBA 或這份文件的問題或意見反應嗎？ 如需取得支援服務並提供意見反應的相關指導，請參閱 Office VBA 支援與意見反應。