AddAdvise 方法(Visio) EventListEventList.AddAdvise method (Visio)

Event对象添加到要接收其事件的源对象的EventList集合中。Adds an Event object to the EventList collection of the source object whose events you want to receive. 选择的事件发生时,源对象将通知接收对象。When selected events occur, the source object notifies your sink object.

语法Syntax

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

_表达式_一个代表**EventList** 对象的变量。expression A variable that represents an EventList object.

参数Parameters

名称Name 必需/可选Required/Optional 数据类型Data type 说明Description
EventCodeEventCode 必需Required IntegerInteger 生成通知的事件。The event(s) that generate notifications.
SinkIUnkOrIDispSinkIUnkOrIDisp 必需Required VariantVariant 对对象上接收事件通知的 COM 接口的引用。A reference to a COM interface on the object that is to receive event notifications.
IIDSinkIIDSink RequiredRequired StringString 保留以供将来使用。Reserved for future use. 必须为“”。Must be "".
TargetArgsTargetArgs RequiredRequired StringString 传递给Event对象以设置其TargetArgs属性的字符串。The string that is passed to your Event object to set its TargetArgs property.

返回值Return value

事件Event

备注Remarks

使用AddAdvise方法创建的事件对象的Action属性为visActCodeAdviseEvent objects created with the AddAdvise method have an Action property of visActCodeAdvise. 这些对象不是永久的,也就是说,它们不能存储在 Visio 文档中,而且必须在运行时重新创建。They are not persistent, that is, they cannot be stored with a Visio document and must be re-created at run time.

源对象,其EventList集合包含Event对象,用于建立报告事件的范围。The source object whose EventList collection contains the Event object establishes the scope in which the events are reported. 为源对象和对象模型层次结构中较低的对象报告事件。Events are reported for the source object and objects lower in the object model hierarchy. 例如,若要在保存特定文档时收到通知,请将DocumentSaved事件的event对象添加到该文档的EventList集合中。For example, to receive notification when a particular document is saved, add an Event object for the DocumentSaved event to the EventList collection of that document. 若要在应用程序实例中打开任何文档时收到通知,请将 Event 对象添加到 Application 对象的 EventList 集合中。To receive notification when any document is opened in an instance of the application, add the Event object to the EventList collection of the Application object.

创建事件对象是处理 c + + 或其他非 Microsoft Visual Basic 解决方案中的事件的常用方法。Creating Event objects is a common way to handle events from C++ or other non-Microsoft Visual Basic solutions. 使用 Visual Basic WithEvents关键字处理事件时,会触发源对象的事件集中的所有事件。When you use the Visual Basic WithEvents keyword to handle events, all the events in a source object's event set fire. 但是,创建用于处理事件的 Event 对象时,只会向程序通知您选择的事件。When you create Event objects to handle events, however, your program will only be notified of the events you select. 根据您的解决方案,这可能会提高性能。Depending on your solution, this may result in improved performance.

_EventCode_参数通常是常量的组合。The EventCode argument is often a combination of constants. 例如, visEvtMod + visEvtCellCellChanged事件的事件代码。For example, visEvtMod + visEvtCell is the event code for the CellChanged event. 事件常量由 Visio 类型库声明,并且带有 visEvt 前缀。Event constants are declared by the Visio type library and are prefixed with visEvt. 若要查找要创建的事件的事件代码,请参阅事件代码To find an event code for the event that you want to create, see Event codes.

传递给AddAdvise方法的参数设置Event对象的事件ActionvisCodeRunAddAdvise)和TargetArgs属性的初始值。The arguments passed to the AddAdvise method set the initial values of the Event object's Event, Action (visCodeRunAddAdvise), and TargetArgs properties.

从 Visio 2002 开始,可以使用事件筛选器来优化在程序中收到的事件。Beginning with Visio 2002, you can use event filters to refine the events that you receive in your program. 可以按对象、单元格、单元格区域或命令 ID 来筛选事件。You can filter events by object, cell, ranges of cells, or command ID. 有关使用事件筛选器的详细信息,请参阅以SetFilterGetFilter为前缀的方法主题。For details about using event filters, see the method topics prefixed with SetFilter and GetFilter.

使用AddAdvise方法创建的事件对象的Action属性为visActCodeAdviseEvent objects created with the AddAdvise method have an Action property of visActCodeAdvise. 这些对象不是永久的,也就是说,它们不能存储在 Visio 文档中,而且必须在运行时重新创建。They are not persistent, that is, they cannot be stored with a Visio document and must be re-created at run time.

源对象,其EventList集合包含Event对象,用于建立报告事件的范围。The source object whose EventList collection contains the Event object establishes the scope in which the events are reported. 为源对象和对象模型层次结构中较低的对象报告事件。Events are reported for the source object and objects lower in the object model hierarchy. 例如,若要在保存特定文档时收到通知,请将DocumentSaved事件的event对象添加到该文档的EventList集合中。For example, to receive notification when a particular document is saved, add an Event object for the DocumentSaved event to the EventList collection of that document. 若要在应用程序实例中打开任何文档时收到通知,请将 Event 对象添加到 Application 对象的 EventList 集合中。To receive notification when any document is opened in an instance of the application, add the Event object to the EventList collection of the Application object.

创建事件对象是处理 c + + 或其他非 Microsoft Visual Basic 解决方案中的事件的常用方法。Creating Event objects is a common way to handle events from C++ or other non-Microsoft Visual Basic solutions. 使用 Visual Basic WithEvents关键字处理事件时,会触发源对象的事件集中的所有事件。When you use the Visual Basic WithEvents keyword to handle events, all the events in a source object's event set fire. 但是,创建用于处理事件的 Event 对象时,只会向程序通知您选择的事件。When you create Event objects to handle events, however, your program will only be notified of the events you select. 根据您的解决方案,这可能会提高性能。Depending on your solution, this may result in improved performance.

_EventCode_参数通常是常量的组合。The EventCode argument is often a combination of constants. 例如, visEvtMod + visEvtCellCellChanged事件的事件代码。For example, visEvtMod + visEvtCell is the event code for the CellChanged event. 事件常量由 Visio 类型库声明,并且带有 visEvt 前缀。Event constants are declared by the Visio type library and are prefixed with visEvt. 若要查找要创建的事件的事件代码,请参阅事件代码To find an event code for the event that you want to create, see Event codes.

传递给AddAdvise方法的参数设置Event对象的事件ActionvisCodeRunAddAdvise)和TargetArgs属性的初始值。The arguments passed to the AddAdvise method set the initial values of the Event object's Event, Action (visCodeRunAddAdvise), and TargetArgs properties.

从 Visio 2002 开始,可以使用事件筛选器来优化在程序中收到的事件。Beginning with Visio 2002, you can use event filters to refine the events that you receive in your program. 可以按对象、单元格、单元格区域或命令 ID 来筛选事件。You can filter events by object, cell, ranges of cells, or command ID. 有关使用事件筛选器的详细信息,请参阅以SetFilterGetFilter为前缀的方法主题。For details about using event filters, see the method topics prefixed with SetFilter and GetFilter.

使程序可以处理来自 Microsoft Visual Basic 或 Visual Basic for Applications 的事件通知Enabling your program to handle event notifications from Microsoft Visual Basic or Visual Basic for Applications

若要处理通知,应创建一个实现IVisEventProc接口的类模块,然后创建此类的一个实例以将其作为参数传递给AddAdvise方法。To handle notifications, you should create a class module that implements the IVisEventProc interface and then create an instance of this class to pass as an argument to the AddAdvise method.

IVisEventProc接口包含一个具有以下声明的函数:The IVisEventProc interface contains a single function with the following declaration:

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参数的说明。Following are descriptions of the arguments to VisEventProc.

* * 参数 * *** Argument** * * 说明 * *** Description**
nEventCodenEventCode 已发生的事件。The event(s) that occurred. 可以为每个事件提供一个不同的对象,也可提供单个对象,该对象接收所有的通知并根据 nEventCode 在内部进行切换。You can provide a distinct object for each event or provide a single object that receives all notifications and switches internally based on nEventCode.
pSourceObjpSourceObj 对象,其EventList集合包含触发通知的Event对象。The object whose EventList collection contains the Event object that triggered the notification.
nEventIDnEventID EventList集合中的Event对象的唯一标识符。The unique identifier of the Event object within the EventList collection. (与EventList集合的Index属性不同的是,nEventID 不会随着在集合中添加或删除事件对象而发生变化。)您可以使用以下代码从VisEventProc中获取Event对象:(Unlike the Index property of the EventList collection, nEventID does not change as Event objects are added to or deleted from the collection.) You can get the Event object from VisEventProc by using the following code:
pSourceObj .EventList.ItemFromID(nEventID )

| |nEventSeqNum |事件相对于应用程序调用实例中发生的事件序列的序号位置。| | nEventSeqNum| The ordinal position of the event with respect to the sequence of events that have occurred in the calling instance of the application. 在 Visio 实例中发生的第一个事件的序列号为 1,第二个事件的序列号为 2,依此类推。The first event that occurs in a Visio instance has a sequence number of 1, the second event 2, and so forth. 在某些情况下,可以将序列号与EventInfo属性结合使用,以获取有关事件的详细信息。 ||pSubjectObj |事件所涉及的对象。In some cases, you can use the sequence number in conjunction with the EventInfo property to obtain more information about the event.| | pSubjectObj| The object that the event is about. 例如, ShapeAdded事件的主题是一个Shape对象,该对象代表刚添加的形状,而BeforeSelectionDelete事件的主题是选择要在其中删除的形状的Selection对象。 ||vMoreInfo |有关事件主题的其他信息。For example, the subject of a ShapeAdded event is a Shape object representing the shape that was just added, while the subject of a BeforeSelectionDelete event is a Selection object in which the shapes that are about to be deleted are selected.| | vMoreInfo| Additional information about the subject of the event. 对于多数事件,附加信息是指类似于应用程序传递它所执行的加载项时所用的命令行的字符串。For many events, it is a string similar to the command line the application passes the add-ons it executes. 如果通知中不包括附加信息,则此参数将被设置为 NothingIf the notification does not include additional information, this parameter is set to Nothing. 有关特定事件的通知参数的详细信息,请参阅本参考中的特定事件主题。 |For details about notification parameters for a particular event, see the particular event topic in this reference.|

如果 nEventCode 标识查询事件(以查询为前缀的事件),则返回 True以取消该事件,并返回False以允许发生此事件。If nEventCode identifies a query event (events prefixed with Query), return True to cancel the event, and False to allow it to happen. 对于其他事件,此值可为任意值。The value is arbitrary for other events. 如果不返回显式值,则 Microsoft Visual Basic for Applications (VBA) 将返回空的 Variant,Visio 将该值解释为 FalseIf no explicit value is returned, Microsoft Visual Basic for Applications (VBA) returns an empty Variant, which Visio interprets as False.

源对象和Event对象之间的连接会一直存在,直到出现以下情况之一为止:The connection between the source object and the Event object exists until one of the following occurs:

  • 程序将删除事件对象。The program deletes the Event object.

  • 程序将释放对源对象的最后一个引用。The program releases the last reference to the source object. EventList集合和事件对象保留对其源对象的引用。)(The EventList collection and Event objects hold a reference on their source object.)

  • 应用程序终止。The application terminates.

从 Visio 2000 开始, VisEventProc定义为一个返回值的函数。Beginning with Visio 2000, VisEventProc is defined as a function that returns a value. 但是,Visio 只会从对传递了查询事件代码的VisEventProc调用中查看返回值。However, Visio only looks at return values from calls to VisEventProc that are passed a query event code. 通过IDispatch提供VisEventProc事件对象无需更改。Event objects that provide VisEventProc through IDispatch require no change. 若要修改现有的事件处理程序以使其可以处理查询事件,请将Sub过程更改为Function过程,并返回适当的值。To modify existing event handlers so that they can handle query events, change the Sub procedure to a Function procedure and return the appropriate value. (有关查询事件的详细信息,请参阅本参考中带有 "查询" 前缀的事件主题。)(For details about query events, see this reference for event topics prefixed with Query.)

示例Example

本示例演示如何创建一个类模块来处理由 Microsoft Office Visio 中的源对象(例如, Document对象)触发的事件。This example shows how to create a class module to handle events fired by a source object in Microsoft Office Visio, for example, the Document object. 该模块包含 VisEventProc 函数,它使用 Select Case 块查找三个事件:DocumentSavedPageAddedShapesDeletedThe module consists of the function VisEventProc, which uses a Select Case block to check for three events: DocumentSaved, PageAdded, and ShapesDeleted. 其他事件属于默认情况 (Case Else)。Other events fall under the default case (Case Else). 每个Case块都构造一个字符串( strMessage ),其中包含触发的事件的名称和事件代码。Each Case block constructs a string ( strMessage ) that contains the name and event code of the event that fired. 最后,该函数在“立即”窗口中显示这一字符串。Finally, the function displays the string in the Immediate window.

将此示例代码复制到 Microsoft Visual Basic for Applications (VBA)或 Visual Basic 中的一个新的类模块中,命名模块clsEventSinkCopy this sample code into a new class module in Microsoft Visual Basic for Applications (VBA) or Visual Basic, naming the module clsEventSink. 然后,可以使用接下来的事件接收模块创建 clsEventSink 类的一个实例以及用于向该类实例发送事件引发通知的 Event 对象。You can then use the event-sink module that follows to create an instance of the clsEventSink class and Event objects that send notifications of event firings to the class instance.

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方法来接收事件。The following VBA module shows how to use the AddAdvise method to sink events. 该模块包含两个公共过程。The module contains two public procedures.

CreateEventObjects过程创建一个名为clsEventSink的接收器对象(事件处理)类的实例,该实例将传递给AddAdvise方法,并接收事件的通知。The CreateEventObjects procedure creates an instance of a sink-object (event-handling) class named clsEventSink that gets passed to the AddAdvise method, and that receives notifications of events. 此外,该过程创建下面三个 Event 对象,以便将 Document 对象产生的三个事件的引发通知发送给该接收对象:DocumentSavedPageAddedShapesDeletedIn addition, the procedure creates three Event objects to send notifications of firings of three events sourced by the Document object to the sink object: DocumentSaved, PageAdded, and ShapesDeleted.

当您的程序使用完这些事件对象时, DeleteEventObjects过程将删除这些对象。The DeleteEventObjects procedure deletes these Event objects when your program is finished using them.

ClsEventSink类实现IVisEventProc接口。The clsEventSink class implements the IVisEventProc interface.

该示例假定 Visio 应用程序窗口中存在活动文档。The example assumes that there is an active document in the Visio application window.

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 and feedback

有关于 Office VBA 或本文档的疑问或反馈?Have questions or feedback about Office VBA or this documentation? 请参阅 Office VBA 支持和反馈,获取有关如何接收支持和提供反馈的指南。Please see Office VBA support and feedback for guidance about the ways you can receive support and provide feedback.