Méthode EventList.AddAdvise (Visio)

Ajoute un objet Event à la collection EventList de l'objet source dont vous souhaitez recevoir les événements. Lorsque les événements sélectionnés se produisent, l'objet source avertit votre objet récepteur.

Syntaxe

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

Expression Variable qui représente un objet EventList .

Parameters

Nom	Requis/Facultatif	Type de données	Description
EventCode	Requis	Integer	Événements générant des notifications.
SinkIUnkOrIDisp	Requis	Variant	Référence à une interface COM sur l'objet qui doit recevoir des notifications d'événement.
IIDSink	Requis	String	Réservé à une utilisation future. Doit être "".
TargetArgs	Requis	String	Chaîne transmise à votre objet Event pour définir sa propriété TargetArgs.

Valeur renvoyée

Événement

Remarques

Les objets d’événement créés avec la méthode AddAdvise ont une propriété Action de visActCodeAdvise. De tels événements ne sont pas permanents, ils ne peuvent donc pas être stockés dans un document Visio et doivent être recréés au moment de l'exécution.

L'objet source dont la collection EventList contient l'objet Event détermine la portée avec laquelle les événements sont signalés. Les événements sont signalés pour l'objet source et les objets situés à un échelon inférieur dans la hiérarchie de modèle d'objet. Par exemple, pour recevoir une notification lors de l’enregistrement d’un document particulier, ajoutez un objet Event pour l’événement DocumentSaved à la collection EventList de ce document. Pour recevoir une notification quel que soit le document ouvert dans une instance de l'application, ajoutez l'objet Event à la collection EventList de l'objet Application.

La création d'objets Event est une technique courante pour gérer les événements provenant de solutions C++ ou d'autres solutions n'appartenant pas à Microsoft Visual Basic. Lorsque vous utilisez le mot clé Visual Basic WithEvents pour gérer les événements, tous les événements dans le jeu d’événements d’un objet source se déclenchent. Toutefois, lorsque vous créez des objets Event pour gérer des événements, votre programme ne reçoit une notification que pour les événements sélectionnés. Selon votre solution, vous pourrez constater une amélioration des performances.

L’argument EventCode est généralement une combinaison de constantes. Par exemple, visEvtMod + visEvtCell est le code d’événement de l’événement CellChanged . Les constantes d’événement sont déclarées par la bibliothèque de types Visio et commencent par le préfixe visEvt. Pour rechercher le code de l’événement à créer, voir Codes d’événement.

Les arguments transmis à la méthode AddAdvise définissent les valeurs initiales des propriétés Event, Action, (visCodeRunAddAdvise) et TargetArgs de l'objet Event.

À partir de Visio 2002, vous pouvez utiliser des filtres d'événement pour affiner les événements reçus dans votre programme. Vous pouvez filtrer les événements par objet, cellule, plages de cellules ou ID de commande. Pour plus de détails concernant l'utilisation des filtres d'événement, reportez-vous aux rubriques des méthodes commençant par les préfixes SetFilter et GetFilter.

Les objets d’événement créés avec la méthode AddAdvise ont une propriété Action de visActCodeAdvise. De tels événements ne sont pas permanents, ils ne peuvent donc pas être stockés dans un document Visio et doivent être recréés au moment de l'exécution.

L'objet source dont la collection EventList contient l'objet Event détermine la portée avec laquelle les événements sont signalés. Les événements sont signalés pour l'objet source et les objets situés à un échelon inférieur dans la hiérarchie de modèle d'objet. Par exemple, pour recevoir une notification lors de l’enregistrement d’un document particulier, ajoutez un objet Event pour l’événement DocumentSaved à la collection EventList de ce document. Pour recevoir une notification quel que soit le document ouvert dans une instance de l'application, ajoutez l'objet Event à la collection EventList de l'objet Application.

La création d'objets Event est une technique courante pour gérer les événements provenant de solutions C++ ou d'autres solutions n'appartenant pas à Microsoft Visual Basic. Lorsque vous utilisez le mot clé Visual Basic WithEvents pour gérer les événements, tous les événements dans le jeu d’événements d’un objet source se déclenchent. Toutefois, lorsque vous créez des objets Event pour gérer des événements, votre programme ne reçoit une notification que pour les événements sélectionnés. Selon votre solution, vous pourrez constater une amélioration des performances.

L’argument EventCode est généralement une combinaison de constantes. Par exemple, visEvtMod + visEvtCell est le code d’événement de l’événement CellChanged . Les constantes d’événement sont déclarées par la bibliothèque de types Visio et commencent par le préfixe visEvt. Pour rechercher le code de l’événement à créer, voir Codes d’événement.

Les arguments transmis à la méthode AddAdvise définissent les valeurs initiales des propriétés Event, Action, (visCodeRunAddAdvise) et TargetArgs de l'objet Event.

À partir de Visio 2002, vous pouvez utiliser des filtres d'événement pour affiner les événements reçus dans votre programme. Vous pouvez filtrer les événements par objet, cellule, plages de cellules ou ID de commande. Pour plus de détails concernant l'utilisation des filtres d'événement, reportez-vous aux rubriques des méthodes commençant par les préfixes SetFilter et GetFilter.

Activation du programme pour la gestion des notifications d'événements Microsoft Visual Basic ou Visual Basic pour Applications

Pour gérer les notifications, créez un module de classe qui implémente l'interface IVisEventProc, puis créez une instance de cette classe à transmettre en tant qu'argument à la méthode AddAdvise.

L'interface IVisEventProc contient une seule fonction avec la déclaration suivante.

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

Le tableau suivant répertorie les descriptions des arguments de VisEventProc.

Argument	Description
nEventCode	Événements qui se sont produits. Vous pouvez fournir un objet distinct pour chaque événement ou un seul objet qui reçoit toutes les notifications et bascule de façon interne en fonction de nCodeÉvénement.
pSourceObj	Objet dont la collection EventList contient l’objet Event qui a déclenché la notification.
nEventID	Identificateur unique de l'objet Event de la collection EventList. (Contrairement à la propriété Index de la collection EventList , nEventID ne change pas à mesure que des objets Event sont ajoutés ou supprimés de la collection.) Obtenez l’objet Event à partir de VisEventProc à l’aide du code suivant : pSourceObj .EventList.ItemFromID(nEventID )
nEventSeqNum	Position ordinale de l'événement, compte tenu de la séquence des événements qui se sont produits dans l'instance appelante de l'application. Le premier événement qui se produit dans une instance Visio a un numéro de séquence 1, le deuxième événement 2, et ainsi de suite. Dans certains cas, vous pouvez utiliser le numéro de séquence conjointement avec la propriété EventInfo pour obtenir plus d’informations sur l’événement.
pSubjectObj	Objet dont traite l'événement. Par exemple, le sujet d'un événement ShapeAdded est un objet Shape représentant la forme qui vient d'être ajoutée, tandis que le sujet d'un événement BeforeSelectionDelete est un objet Selection dans lequel les formes qui sont sur le point d'être supprimées sont sélectionnées.
vMoreInfo	Informations supplémentaires sur le sujet de cet événement. Pour de nombreux événements, il s'agit d'une chaîne similaire à la ligne de commande que l'application transmet aux modules complémentaires qu'elle exécute. Si la notification ne comprend pas d'informations supplémentaires, ce paramètre est défini sur la valeur Aucune (Nothing). Pour plus d’informations sur les paramètres de notification d’un événement particulier, consultez la rubrique relative à l’événement particulier dans cette référence.

Si nCodeÉvénement identifie un événement de requête (événements ayant le préfixe Query), renvoie la valeur Truepour annuler l'événement et la valeur False pour l'autoriser à se produire. La valeur est arbitraire pour les autres événements. Si aucune valeur explicite n'est renvoyée, Visual Basic pour Applications (VBA) renvoie un argument Variant vide que Visio interprète comme la valeur False.

Le lien entre l'objet source et l'objet Event existe jusqu'à ce que l'une des actions suivantes se produise :

• Le programme supprime l'objet Event.
• Le programme libère la dernière référence à l'objet source. (La collection EventList et les objets Event conservent une référence à leur objet source.)
• L'application Visio va s'arrêter.

À compter de Visio 2000, VisEventProc est défini comme une fonction qui retourne une valeur. Toutefois, Visio examine uniquement les valeurs de retour des appels à VisEventProc qui reçoivent un code d’événement de requête. Les objets Event qui fournissent VisEventProc via IDispatch ne nécessitent aucune modification. Pour modifier des gestionnaires d'événement existants de manière à ce qu'ils puissent gérer les événements de requête, transformez la procédure Sub en procédure Function et renvoyez la valeur appropriée. (Pour plus de détails sur les événements de requête, reportez-vous à cette référence pour les rubriques d'événement ayant pour préfixe Query.)

Exemple

Cet exemple indique comment créer un module de classe pour gérer des événements déclenchés par un objet source dans Microsoft Office Visio, par exemple l'objet Document. Le module est composé de la fonction VisEventProc qui utilise un bloc Select Case pour vérifier trois événements : DocumentSaved, PageAdded et ShapesDeleted. Les autres événements relèvent du cas par défaut (Case Else). Chaque bloc Case construit une chaîne ( strMessage ) qui contient le nom et le code d’événement de l’événement qui s’est déclenché. Enfin, la fonction affiche la chaîne dans la fenêtre Exécution.

Copiez cet exemple de code dans un nouveau module de classe dans Microsoft Visual Basic pour Applications (VBA) ou Visual Basic en nommant le module clsEventSink. Vous pouvez ensuite utiliser le module récepteur d'événement suivant pour créer une instance de la classe clsEventSink et des objets Event qui envoient des notifications d'événement se déclenchant vers l'instance de 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

Le module VBA suivant indique comment utiliser la méthode AddAdvise pour recevoir des événements. Le module contient deux procédures publiques.

La procédure CreateEventObjects crée une instance d'une classe d'objet récepteur (traitement d'événement) nommée clsEventSink transmise à la méthode AddAdvise et qui reçoit des notifications d'événement. En outre, la procédure crée trois objets Event pour envoyer des notifications de déclenchement de trois événements dont la source est l'objet Document à l'objet récepteur : DocumentSaved, PageAdded et ShapesDeleted.

La procédure DeleteEventObjects supprime ces objets Event lorsque votre programme ne les utilise plus.

La classe clsEventSink implémente l'interface IVisEventProc.

L’exemple suivant suppose qu’il existe un document actif dans la fenêtre de l’application 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

Assistance et commentaires

Avez-vous des questions ou des commentaires sur Office VBA ou sur cette documentation ? Consultez la rubrique concernant l’assistance pour Office VBA et l’envoi de commentaires afin d’obtenir des instructions pour recevoir une assistance et envoyer vos commentaires.