An Event Overview

3 4

Earlier chapters in this guide describe how to control Microsoft Visio objects by using Automation to get and set properties and to invoke methods. This one-way communication has its limitations: Your program can tell a Visio instance what to do, but it cannot find out what is happening in a Visio instance without explicitly checking for each possible case. Events allow objects and their clients to engage in bidirectional communication.

Working with an object's events differs from working with an object's properties and methods in this key respect: Properties and methods are both defined and implemented by Visio; events are defined by Visio, however, you are responsible for writing the code to implement them.

The following illustration shows how your program calls Visio to implement properties and events, and how Visio calls your program to implement events.

Figure 21-1 The interaction between Visio and your client program.

An event has both a subject and a source, which are typically different objects. The subject of an event is the object to which the event actually happens. For example, the subject of a ShapeAdded event is the Shape object that was added.

The source of an event is the object that produces the event. Most events have several potential sources. The source object you choose determines the scope in which the event fires—the higher the source object in the object hierarchy, the greater the scope. For example, if the source is a Page object, the ShapeAdded event fires whenever a shape is added to that page. If the source is the Application object, the ShapeAdded event fires whenever a shape is added to any page of any document that is open in the Visio instance.

Obviously, the more often an event fires, the more likely it is to affect the performance of your solution. Therefore, when you pick a source object, think first about the scope in which you want to handle the event.

Note

---

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 Filtering Your Event Object later in this chapter and see the method topics prefixed with SetFilter and GetFilter in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

The events that a source object can fire are called its event set. For Microsoft Visual Basic for Applications (VBA) or Visual Basic, these can be viewed in the Object Browser in the Visual Basic Editor. A Visio object that can source events will identify the members of its event set with a lightning bolt symbol. To search for events by object, by name, or by viewing a complete list of events, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).