Метод EventList.AddAdvise (Visio)

Статья
04/07/2023

Добавляет объект Event в коллекцию EventList исходного объекта, события которого требуется получить. При возникновении выбранных событий исходный объект уведомляет объект приемника.

Синтаксис

выражение. AddAdvise( _EventCode_ , _SinkIUnkOrIDisp_ , _IIDSink_ , _TargetArgs_ )

Выражение Переменная, представляющая объект EventList .

Параметры

Имя	Обязательный или необязательный	Тип данных	Описание
EventCode	Обязательный	Integer	События, которые создают уведомления.
SinkIUnkOrIDisp	Обязательный	Variant	Ссылка на COM-интерфейс объекта, который получает уведомления о событиях.
IIDSink	Обязательный	String	Зарезервировано для последующего использования. Должно быть "".
TargetArgs	Обязательный	String	Строка, передаваемая объекту Event для задания свойства TargetArgs .

Возвращаемое значение

Событие

Замечания

Объекты событий, созданные с помощью метода AddAdvise, имеют свойство ActionvisActCodeAdvise. Они не являются постоянными, то есть не могут храниться вместе с документом Visio и должны быть повторно созданы во время выполнения.

Исходный объект , коллекция EventList которого содержит объект Event , устанавливает область, в которой передаются события. События передаются для исходного объекта и объектов ниже в иерархии объектной модели. Например, чтобы получать уведомление о сохранении определенного документа, добавьте объект Event для события DocumentSaved в коллекцию EventList этого документа. Чтобы получать уведомление при открытии любого документа в экземпляре приложения, добавьте объект Event в коллекцию EventList объекта Application .

Создание объектов event — это распространенный способ обработки событий из C++ или других решений Visual Basic, отличных от Microsoft. При использовании ключевого слова 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 для приложений

Для обработки уведомлений необходимо создать модуль класса, реализующий интерфейс 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.

Аргумент	Description
nEventCode	Произошедшие события. Вы можете предоставить отдельный объект для каждого события или один объект, который получает все уведомления и переключения внутренне на основе nEventCode.
pSourceObj	Объект, коллекция EventList которого содержит объект Event , активировав уведомление.
nEventID	Уникальный идентификатор объекта Event в коллекции EventList . (В отличие от свойства Index коллекции EventList , nEventID не изменяется, так как объекты Event добавляются в коллекцию или удаляются из нее.) Получите объект Event из VisEventProc с помощью следующего кода: `pSourceObj .EventList.ItemFromID(nEventID )`
nEventSeqNum	Порядковый номер события относительно последовательности событий, произошедших в вызывающем экземпляре приложения. Первое событие, возникающее в экземпляре Visio, имеет порядковый номер 1, второе событие 2 и т. д. В некоторых случаях можно использовать порядковый номер в сочетании со свойством EventInfo для получения дополнительных сведений о событии.
pSubjectObj	Объект, о который относится событие. Например, темой события ShapeAdded является объект Shape , представляющий только что добавленную фигуру, а темой события BeforeSelectionDelete является объект Selection , в котором выбираются фигуры, которые должны быть удалены.
vMoreInfo	Дополнительные сведения о теме события. Для многих событий это строка, аналогичная командной строке, в которой приложение передает выполняемые надстройки. Если уведомление не содержит дополнительных сведений, для этого параметра задано значение Nothing. Дополнительные сведения о параметрах уведомлений для определенного события см. в разделе о конкретном событии в этом справочнике.

Если nEventCode идентифицирует событие запроса (события с префиксом Query), верните значение True , чтобы отменить событие, и Значение False , чтобы разрешить его выполнение. Значение является произвольным для других событий. Если явное значение не возвращается, Microsoft Visual Basic для приложений (VBA) возвращает пустой вариант Variant, который Visio интерпретирует как false.

Соединение между исходным объектом и объектом Event существует до тех пор, пока не произойдет одно из следующих действий:

Программа удаляет объект Event .
Программа освобождает последнюю ссылку на исходный объект. (Коллекция EventList и объекты Event содержат ссылку на исходный объект.)
Приложение завершает работу.

Начиная с Visio 2000 , VisEventProc определяется как функция, которая возвращает значение. Однако Visio просматривает только возвращаемые значения из вызовов VisEventProc , передаваемых кодом события запроса. Объекты событий , которые предоставляют VisEventProc через IDispatch , не требуют изменения. Чтобы изменить существующие обработчики событий, чтобы они могли обрабатывать события запросов, измените процедуру Sub на процедуру Function и верните соответствующее значение. (Дополнительные сведения о событиях запроса см. в этом справочнике по разделам событий с префиксом Query.)

Пример

В этом примере показано, как создать модуль класса для обработки событий, инициируемых исходным объектом в Microsoft Office Visio, например объектом Document . Модуль состоит из функции VisEventProc, которая использует блок Select Case для проверки наличия трех событий: DocumentSaved, PageAdded и ShapesDeleted. Другие события относятся к регистру по умолчанию (Case Else). Каждый блок Case создает строку ( strMessage ), которая содержит имя и код события, которое сработает. Наконец, функция отображает строку в окне Интерпретация.

Скопируйте этот пример кода в новый модуль класса в Microsoft Visual Basic для приложений (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-object (обработка событий) с именем 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 и обратная связь.