AddAdvise method

Microsoft Visio Developer Reference

AddAdvise method

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 will notify your sink object.

Version added

4.1

Syntax

`evtObj = object.AddAdvise (eventCode, eventSink, IIDSink, targetArgs)`
evtObj	The new Event object.
object	Required. An expression that returns an EventList collection.
eventCode	Required Integer. The event(s) that generate notifications.
eventSink	Required Object. A reference to an OLE interface on the object that is to receive event notifications.
IIDSink	Required String. Reserved for future use. Must be "".
targetArgs	Required String. The string that is passed to your sink object.

Remarks

Event objects created with the AddAdvise method have an Action property of visActCodeAdvise. They are not persistent, that is, they cannot be stored with a Visio document and must be re-created at run time.

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. 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. 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.

Creating Event objects is a common way to handle events from C++ or other non–Microsoft Visual Basic solutions. Unlike events handled using the Visual Basic WithEvents keyword (all the events in a source object's event set fire), your program will only be notified of the events you select. Depending on your solution, this may result in improved performance.

The eventCode argument is often a combination of constants. For example, visEvtMod+visEvtCell is the event code for the CellChanged event. Event constants are declared by the Visio type library and are prefixed with visEvt. To find an event code for the event you want to create, see Event codes.

The arguments passed to the AddAdvise method set the initial values of the Event object's Event, Action (visCodeRunAddAdvise), and TargetArgs properties.

Beginning with Microsoft Visio 2002, you can use event filters to refine the events that you receive in your program. You can filter events by object, cell, ranges of cells, or command ID. For details about using event filters, see the method topics prefixed with SetFilter and GetFilter.

Enabling your program to handle event notifications from Microsoft Visual Basic or Visual Basic for Applications

To handle notifications, you should create a class module that implements the IVisEventProc interface, then create an instance of this class to pass as an argument to the AddAdvise method.

The IVisEventPRoc interface contains a single function with the following arguments.

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

Following are descriptions of the arguments to VisEventProc.

Argument	Description
nEventCode	The event(s) that occurred. You can provide a distinct object for each event or provide a single object that receives all notifications and switches internally based on nEventCode.
pSourceObj	The object whose EventList collection contains the Event object that triggered the notification.
nEventID	The unique identifier of the Event object within the EventList collection (unlike its index, which can change as Event objects are added or deleted from the EventList collection). VisEventProc can access the Event object by using pSourceObj.EventList.ItemFromID(nEventID).
nEventSeqNum	The ordinal position of the event with respect to the sequence of events that have occurred in the calling instance of the application. The first event that occurs in a Visio instance has a sequence number of 1, the second event 2, and so forth. In some cases, you can use sequence in conjunction with the EventInfo property to obtain more information about the event.
pSubjectObj	The object that the event is about. 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. If 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.

If the event 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. If no explicit value is returned, Visual Basic for Applications returns an empty Variant, which Visio interprets as False.

The connection between the source object and the event sink object exists until one of the following occurs:

The program deletes the Event object.

The program releases the last reference on the source object. (The EventList collection and Event objects hold a reference on their source object.)

The application terminates.

Note Beginning with Visio 2000, VisEventProc is defined as a function that returns a value. However, Visio only looks at return values from calls to VisEventProc that are passed a query event code. Sink objects that provide VisEventProc through IDispatch require no change. To modify existing event handlers so 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.)

previous page start next page