EventList.AddAdvise-Methode (Visio)

Artikel
04/07/2023

Fügt der EventList-Auflistung des Quellobjekts, dessen Ereignisse Sie empfangen möchten, ein Event-Objekt hinzu. Wenn ausgewählte Ereignisse auftreten, wird das sink-Objekt vom Quellobjekt benachrichtigt.

Syntax

Ausdruck. AddAdvise( _EventCode_ , _SinkIUnkOrIDisp_ , _IIDSink_ , _TargetArgs_ )

Ausdruck Eine Variable, die ein EventList-Objekt darstellt.

Parameter

Name	Erforderlich/Optional	Datentyp	Beschreibung
EventCode	Erforderlich	Integer	Die Ereignisse, die Benachrichtigungen generieren.
SinkIUnkOrIDisp	Erforderlich	Variant	Ein Verweis auf eine COM-Schnittstelle im Objekt, das Ereignisbenachrichtigungen empfangen soll.
IIDSink	Erforderlich	String	Reserviert für zukünftige Verwendung. Muss "" sein.
TargetArgs	Erforderlich	String	Die Zeichenfolge, die an das Event-Objekt übergeben wird, um dessen TargetArgs-Eigenschaft festzulegen.

Rückgabewert

Ereignis

Hinweise

Ereignisobjekte , die mit der AddAdvise-Methode erstellt wurden, weisen die Action-EigenschaftvisActCodeAdvise auf. Sie sind nicht permanent, das heißt, sie können nicht mit einem Visio-Dokument erstellt werden und müssen zur Laufzeit erneut erstellt werden.

Das Quellobjekt, dessen EventList-Auflistung das Event-Objekt enthält, richtet den Bereich ein, in dem die Ereignisse gemeldet werden. Ereignisse werden für das Quellobjekt und untergeordnete Objekte in der Objektmodellhierarchie gemeldet. Um beispielsweise eine Benachrichtigung zu erhalten, wenn ein bestimmtes Dokument gespeichert wird, fügen Sie der EventList-Auflistung dieses Dokuments ein Event-Objekt für das DocumentSaved-Ereignis hinzu. Um benachrichtigt zu werden, wenn ein beliebiges Dokument in einer Instanz der Anwendung geöffnet wird, fügen Sie das Event-Objekt der EventList-Auflistung dss Application-Objekts hinzu.

Das Erstellen von Event-Objekten ist eine gängige Methode, um Ereignisse aus C++ oder anderen als Microsoft Visual Basic-Lösungen zu behandeln. Wenn Sie die Visual Basic WithEvents-Schlüsselwort (keyword) zum Behandeln von Ereignissen verwenden, werden alle Ereignisse im Ereignissatz eines Quellobjekts ausgelöst. Wenn Sie jedoch Event-Objekte zum Behandeln von Ereignissen erstellen, wird Ihr Programm nur über die von Ihnen ausgewählten Ereignisse benachrichtigt. Je nach Lösung kann dies zu einer Leistungsverbesserung führen.

Das EventCode-Argument ist oft eine Kombination aus Konstanten. Beispielsweise ist visEvtMod + visEvtCell der Ereigniscode für das CellChanged-Ereignis . Ereigniskonstanten werden von der Visio-Typbibliothek deklariert und erhalten das Präfix visEvt. Informationen zum Suchen eines Ereigniscodes für das Ereignis, das Sie erstellen möchten, finden Sie unter Ereigniscodes.

Mit den Argumenten, die an die AddAdvise-Methode übergeben werden, werden die Ausgangswerte für die Event-, Action- (visCodeRunAddAdvise) und TargetArgs- Eigenschaften des Event-Objekts festgelegt.

Ab Visio 2002 können mithilfe von Ereignisfiltern die Ereignisse, die Sie in Ihrem Programm empfangen, genauer gefiltert werden. Sie können Ereignisse nach Objekt, Zelle, Zellbereichen oder Befehls-ID filtern. Weitere Informationen zur Verwendung von Ereignisfiltern finden Sie unter den Themen zu den Methoden mit dem Präfix SetFilter und GetFilter.

Behandeln von Ereignisbenachrichtigungen in Microsoft Visual Basic oder Visual Basic für Applikationen für Ihr Programm

Zum Behandeln von Benachrichtigungen sollten Sie ein Klassenmodul erstellen, das die IVisEventProc-Schnittstelle implementiert, und dann eine Instanz dieser Klasse erstellen, die als Argument an die AddAdvise-Methode übergeben wird.

Die IVisEventProc-Schnittstelle enthält eine einzige Funktion mit der folgenden Deklaration:

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

Die folgende Tabelle enthält Beschreibungen der Argumente für VisEventProc.

Argument	Beschreibung
nEventCode	Die aufgetretenen Ereignisse. Sie können für jedes Ereignis ein anderes Objekt bereitstellen, oder ein einziges Objekt, das alle Benachrichtigungen empfängt und intern in Abhängigkeit von nEventCode umgeschaltet wird.
pSourceObj	Das Objekt, dessen EventList-Auflistung das Event-Objekt enthält, das die Benachrichtigung ausgelöst hat.
nEventID	Der eindeutige Bezeichner des Event-Objekts innerhalb der EventList-Auflistung. (Im Gegensatz zur Index-Eigenschaft der EventList-Auflistung ändert sich nEventID nicht, wenn Event-Objekte der Auflistung hinzugefügt oder daraus gelöscht werden.) Rufen Sie das Event-Objekt aus VisEventProc mithilfe des folgenden Codes ab: `pSourceObj .EventList.ItemFromID(nEventID )`
nEventSeqNum	Die Position des Ereignisses in Bezug auf die Abfolge von Ereignissen, die in der aufrufenden Instanz der Anwendung aufgetreten sind. Das erste Ereignis, das in einer Visio-Instanz auftritt, weist die Sequenznummer 1 auf, das zweite Ereignis die Nummer 2 usw. In einigen Fällen können Sie die Sequenznummer in Verbindung mit der EventInfo-Eigenschaft verwenden, um weitere Informationen zum Ereignis zu erhalten.
pSubjectObj	Das Objekt, um das das Ereignis geht. Der Betreff eines ShapeAdded-Ereignisses ist beispielsweise ein Shape-Objekt , das die gerade hinzugefügte Form darstellt, während der Betreff eines BeforeSelectionDelete-Ereignisses ein Selection-Objekt ist, in dem die Shapes ausgewählt werden, die gelöscht werden sollen.
vMoreInfo	Zusätzliche Informationen zum Betreff des Ereignisses. Für viele Ereignisse handelt es sich dabei um eine Zeichenfolge, die der Befehlszeile ähnelt, an die von der Anwendung die ausgeführten Add-Ons übergeben werden. Falls die Benachrichtigung keine zusätzlichen Informationen enthält, ist dieser Parameter auf Nothing festgelegt. Ausführliche Informationen zu Benachrichtigungsparametern für ein bestimmtes Ereignis finden Sie im Thema zu bestimmten Ereignissen in dieser Referenz.

Wenn nEventCode ein Abfrageereignis (Ereignisse mit dem Präfix Query) identifiziert, gibt True zurück, um das Ereignis abzubrechen, und False , um dies zuzulassen. Der Wert ist für andere Ereignisse beliebig. Wenn kein expliziter Wert zurückgegeben wird, gibt Microsoft Visual Basic for Applications (VBA) einen leeren Variant-Wert zurück, der von Visio als False interpretiert wird.

Die Verbindung zwischen dem Quellobjekt und dem Event-Objekt ist vorhanden, bis eine der folgenden Aktionen ausgeführt wird:

Das Event-Objekt wird vom Programm gelöscht.
Der letzte Verweis auf das Quellobjekt wird vom Programm freigegeben. (Die EventList-Auflistung und die Event-Objekte enthalten einen Verweis auf das Quellobjekt.)
Die Anwendung wird beendet.

Ab Visio 2000 wird VisEventProc als Funktion definiert, die einen Wert zurückgibt. Visio untersucht jedoch nur Rückgabewerte von Aufrufen von VisEventProc , denen ein Abfrageereigniscode übergeben wird. Ereignisobjekte , die VisEventProc über IDispatch bereitstellen, erfordern keine Änderung. Um vorhandene Ereignishandler so zu ändern, dass sie Abfrageereignisse ausführen können, ändern Sie die Sub-Prozedur in eine Function-Prozedur, und geben Sie den entsprechenden Wert zurück. (Weitere Informationen zu Abfrageereignissen finden Sie in dieser Referenz in Ereignisthemen mit dem Präfix Query.)

Beispiel

In diesem Beispiel wird gezeigt, wie Sie ein Klassenmodul zum Behandeln von Ereignissen erstellen, die von einem Quellobjekt in Microsoft Office Visio ausgelöst werden, z. B. das Document-Objekt. Das Modul besteht aus der VisEventProc-Funktion, die einen Select Case-Block zum Überprüfen von drei Ereignissen verwendet: DocumentSaved, PageAdded und ShapesDeleted. Andere Ereignisse fallen unter den Standardfall (Case Else). Jeder Case-Block erstellt eine Zeichenfolge ( strMessage ), die den Namen und den Ereigniscode des ausgelösten Ereignisses enthält. Schließlich wird die Zeichenfolge von der Funktion im Direktfenster angezeigt.

Kopieren Sie diesen Beispielcode in ein neues Klassenmodul in Microsoft Visual Basic for Applications (VBA) oder Visual Basic, und nennen Sie das Modul clsEventSink. Anschließend können Sie das folgende Ereignissenkenmodul verwenden, um eine instance der clsEventSink-Klasse und der Event-Objekte zu erstellen, die Benachrichtigungen über Ereignisauslösungen an die Klasse instance senden.

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

Das folgende VBA-Modul veranschaulicht, wie Sie die AddAdvise-Methode zum Auffangen von Ereignissen verwenden. Das Modul enthält zwei öffentliche Prozeduren.

Die CreateEventObjects-Prozedur erstellt eine instance einer Senkenobjektklasse (Ereignisbehandlung) namens clsEventSink, die an die AddAdvise-Methode übergeben wird und Benachrichtigungen über Ereignisse empfängt. Darüber hinaus erstellt die Prozedur drei Event-Objekte , um Benachrichtigungen über das Auslösen von drei Ereignissen, die vom Document-Objekt stammen, an das Senkenobjekt zu senden: DocumentSaved, PageAdded und ShapesDeleted.

Die DeleteEventObjects-Prozedur löscht diese Event-Objekte, wenn sie nicht mehr vom Programm verwendet werden.

Die clsEventSink-Klasse implementiert die IVisEventProc-Schnittstelle.

Im folgenden Beispiel wird davon ausgegangen, dass im Visio-Anwendungsfenster ein aktives Dokument vorhanden ist.

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

Support und Feedback

Haben Sie Fragen oder Feedback zu Office VBA oder zu dieser Dokumentation? Unter Office VBA-Support und Feedback finden Sie Hilfestellung zu den Möglichkeiten, wie Sie Support erhalten und Feedback abgeben können.

Freigeben über