Partilhar via

Método EventList.AddAdvise (Visio)

  • Artigo

Adiciona um objeto Event à coleção EventList do objeto de origem cujos eventos você deseja receber. Quando ocorrem determinados eventos, o objeto de origem notifica seu objeto coletor.

Sintaxe

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

Expressão Uma variável que representa um objeto EventList .

Parâmetros

Nome Obrigatório/Opcional Tipo de dados Descrição
EventCode Obrigatório Integer O(s) evento(s) que gera(m) notificações.
SinkIUnkOrIDisp Obrigatório Variantes Uma referência à interface COM no objeto que está para receber notificações de evento.
Iidsink Obrigatório String Reserved for future use. Deve ser "".
TargetArgs Obrigatório String A sequência de caracteres passada para seu objeto Event para definir sua propriedade TargetArgs.

Valor de retorno

Evento

Comentários

Os objetos de evento criados com o método AddAdvise têm uma propriedade Action do visActCodeAdvise. Eles não são persistentes, isto é, não podem ser armazenados com um documento Visio e devem ser recriados em tempo de execução.

O objeto de origem cuja coleção EventList contém o objeto Event estabelece o escopo no qual os eventos são relatados. Os eventos são relatados para o objeto de origem e os objetos inferiores na hierarquia de modelo do objeto. Por exemplo, para receber a notificação quando um documento específico for salvo, adicione um objeto Event para o evento DocumentSaved à coleção EventList desse documento. Para receber uma notificação quando qualquer documento for aberto em uma instância do aplicativo, adicione o objeto Event à coleção EventList do objeto Application.

Criar objetos Event é uma maneira comum de manipular eventos no C++ ou em outras soluções diferentes do Microsoft Visual Basic. Quando você usa a palavra-chave WithEvents do Visual Basic para lidar com eventos, todos os eventos no evento de um objeto de origem ateam fogo. Quando você cria objetos Event para manipular eventos, no entanto, seu programa é notificado somente sobre eventos selecionados. Dependendo da solução, isso pode resultar em uma melhora no desempenho.

O argumento EventCode é muitas vezes uma combinação de constantes. Por exemplo, visEvtMod + visEvtCell é o código de evento do evento CellChanged . Constantes de evento são declaradas pela biblioteca de tipos do Visio e são precedidos por visEvt. Para localizar um código de evento que você deseja criar, consulte Códigos de eventos.

Os argumentos passados ao método AddAdvise definem os valores iniciais das propriedades Event, Action (visCodeRunAddAdvise) e TargetArgs do objeto Event.

No Visio 2002, você pode usar filtros de evento para refinar os eventos que recebe no programa. Você pode filtrar eventos por objeto, célula, série de células ou ID de comando. Para obter detalhes sobre como usar filtros de evento, consulte os tópicos de método precedidos de SetFilter e GetFilter.

Os objetos de evento criados com o método AddAdvise têm uma propriedade Action do visActCodeAdvise. Eles não são persistentes, isto é, não podem ser armazenados com um documento Visio e devem ser recriados em tempo de execução.

O objeto de origem cuja coleção EventList contém o objeto Event estabelece o escopo no qual os eventos são relatados. Os eventos são relatados para o objeto de origem e os objetos inferiores na hierarquia de modelo do objeto. Por exemplo, para receber a notificação quando um documento específico for salvo, adicione um objeto Event para o evento DocumentSaved à coleção EventList desse documento. Para receber uma notificação quando qualquer documento for aberto em uma instância do aplicativo, adicione o objeto Event à coleção EventList do objeto Application.

Criar objetos Event é uma maneira comum de manipular eventos no C++ ou em outras soluções diferentes do Microsoft Visual Basic. Quando você usa a palavra-chave WithEvents do Visual Basic para lidar com eventos, todos os eventos no evento de um objeto de origem ateam fogo. Quando você cria objetos Event para manipular eventos, no entanto, seu programa é notificado somente sobre eventos selecionados. Dependendo da solução, isso pode resultar em uma melhora no desempenho.

O argumento EventCode é muitas vezes uma combinação de constantes. Por exemplo, visEvtMod + visEvtCell é o código de evento do evento CellChanged . Constantes de evento são declaradas pela biblioteca de tipos do Visio e são precedidos por visEvt. Para localizar um código de evento que você deseja criar, consulte Códigos de eventos.

Os argumentos passados ao método AddAdvise definem os valores iniciais das propriedades Event, Action (visCodeRunAddAdvise) e TargetArgs do objeto Event.

No Visio 2002, você pode usar filtros de evento para refinar os eventos que recebe no programa. Você pode filtrar eventos por objeto, célula, série de células ou ID de comando. Para obter detalhes sobre como usar filtros de evento, consulte os tópicos de método precedidos de SetFilter e GetFilter.

Habilitando seu programa para manipular notificações de evento do Microsoft Visual Basic ou do Visual Basic for Applications

Para manipular notificações, você deve criar um módulo de classe que implementa a interface IVisEventProc e, em seguida, cria uma instância dessa classe para passar como um argumento ao método AddAdvise.

A interface IVisEventProc contém uma única função com a seguinte declaração:

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

A tabela a seguir lista as descrições dos argumentos para VisEventProc.

Argumento Descrição
nEventCode O(s) evento(s) ocorrido(s). Você pode fornecer um objeto distinto para cada evento ou fornecer um único objeto que receba todas as notificações e seja alterado internamente com base em nEventCode.
pSourceObj O objeto cuja coleção EventList contém o objeto Event que acionou a notificação.
nEventID O identificador exclusivo do objeto Event na coleção EventList. (Ao contrário da propriedade Index da coleção EventList , nEventID não é alterada à medida que objetos Event são adicionados ou excluídos da coleção.)
Obtenha o objeto Event do VisEventProc usando o seguinte código: pSourceObj .EventList.ItemFromID(nEventID )
nEventSeqNum A posição ordinal do evento com respeito à sequência de eventos ocorridos na instância de chamada do aplicativo. O primeiro evento que ocorre em uma instância do Visio possui um número de sequência 1, o segundo evento 2 e assim por diante. Em alguns casos, você pode usar o número de sequência em conjunto com a propriedade EventInfo para obter mais informações sobre o evento.
pSubjectObj O objeto sobre o qual trata o evento. Por exemplo, o assunto de um evento ShapeAdded é um objeto Shape representando a forma que acabou de ser adicionada, enquanto o assunto de um evento BeforeSelectionDelete é um objeto Selection no qual as formas prestes a serem excluídas são selecionadas.
vMoreInfo Informações adicionais sobre o assunto do evento. Para vários eventos, é uma sequência de caracteres similar à linha de comando pela qual o aplicativo passa os complementos que executa. Se a notificação não incluir informações adicionais, esse parâmetro é definido como Nothing. Para obter detalhes sobre parâmetros de notificação para um evento específico, consulte o tópico de evento específico nesta referência.

Se nEventCode identifica um evento de consulta (eventos precedidos de Query), retorne True para cancelar o evento e False para permitir que ele aconteça. O valor é arbitrário para outros eventos. Se nenhum valor explícito for retornado, o Microsoft Visual Basic for Applications (VBA) retorna uma Variant vazia, que o Visio interpreta como False.

A conexão entre o objeto de origem e o objeto Event existe até que uma das seguintes opções ocorra:

  • O programa exclui o objeto Event.
  • O programa libera a última referência ao objeto de origem. (A coleção EventList e os objetos Event mantêm uma referência em seu objeto de origem.)
  • O aplicativo é finalizado.

A partir do Visio 2000, o VisEventProc é definido como uma função que retorna um valor. No entanto, o Visio analisa apenas valores retornados de chamadas para VisEventProc que são passadas um código de evento de consulta. Objetos de evento que fornecem VisEventProc por meio do IDispatch não exigem nenhuma alteração. Para modificar manipuladores de eventos existentes, para que manipulem eventos de consulta, altere o procedimento Sub para um procedimento Function e retorne o valor apropriado. (Para obter detalhes sobre eventos de consulta, consulte esta referência para tópicos de evento precedidos de Query.)

Exemplo

Este exemplo mostra como criar um módulo de classe para manipular eventos disparados por um objeto de origem no Microsoft Office Visio, por exemplo, o objeto Document. O módulo consiste na função VisEventProc, que usa um bloco Select Case para verificar três eventos: DocumentSaved, PageAdded e ShapesDeleted. Outros eventos se encaixam no caso padrão (Case Else). Cada bloco Case constrói uma cadeia de caracteres ( strMessage ) que contém o nome e o código de evento do evento que foi disparado. Finalmente, a função exibe a sequência de caracteres na janela Immediate.

Copie esse código de exemplo em um novo módulo de classe no Microsoft Visual Basic for Applications (VBA) ou Visual Basic, nomeando o módulo clsEventSink. Você pode então usar o módulo evento-coletor que segue para criar uma instância da classe clsEventSink e objetos Event que enviam notificações de eventos que disparam à instância da classe.

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

O seguinte módulo VBA mostra como usar o método AddAdvise para eventos coletores. O módulo contém dois procedimentos públicos.

O procedimento CreateEventObjects cria uma instância de classe de objeto coletor (manipulação de eventos) denominada clsEventSink que é passada para o método AddAdvise e recebe notificações de eventos. Além disso, o procedimento cria três objetos Event para enviar notificações de disparos de três eventos originados pelo objeto Document para o objeto coletor: DocumentSaved, PageAdded e ShapesDeleted.

O procedimento DeleteEventObjects exclui os objetos Event quando esses objetos são usados na conclusão do programa.

A classe clsEventSink implementa a interface IVisEventProc.

O exemplo a seguir pressupõe que há um documento ativo na janela de aplicativo do 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

Suporte e comentários

Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.