Event Filters Sample for Microsoft Visio 2002This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
Microsoft Visio Professional 2002
Microsoft Visio Standard 2002
Summary: This article demonstrates how to filter events in Microsoft Visio 2002. (6 printed pages)
Microsoft® Visio® developers using Microsoft Visual Basic® for Applications (VBA) can now use event filters to reduce the overhead of event processing. This sample shows how to use the new event filtering methods in Visio 2002 to reduce the total number of events that are processed. The new filters control the event firing at the source so that the speed at which events are processed increases as the number of events decreases.
- You can control the items that fire events by setting filters.
- You can filter by:
- Visio object types (Document, Page, Shape, Group, Foreign, Guide).
- Visio cells (specified by ranges of section, row, and cell index).
- Specific Visio user interface (UI) commands (specified by ranges).
- You can view the sample code to see how various filters are used to control different groups of events. This sample code can serve as a starting point for writing your own code.
Important This demo requires Microsoft Visio 2002 to operate correctly. Please install this program before running the demo.
To prepare for the demo
- Download the VisioEventFilters.exe file and unzip it into a temporary directory.
- Open the VisioEventFilters.vsd file, and click Enable Macros.
- Demo opens with a Sample Information window that explains how the sample works. Double-click anywhere in this window to start the demo.
- You will now see the Event Control Window dialog box. Follow the steps shown below to run the demo.
Figure 1. Event control window
To run the demo
- In the Event Control Window dialog box, click Run. This animates the screen, running various operations on the picture. Since the events are not enabled, the event count is zero.
- Select the Enable Events check box.
- Click Run again. This time the event counter shows many events. This duplicates event handling in previous versions of Visio where a solution either listened to all cell changes, or to no cell changes.
- Now select the Enable Filtering check box and click Run. No events occur because the S-R-C (Section-Row-Column) filter and the object filter check boxes are not checked.
- Select the Group check box from the Objects section. Then click All from the S-R-C section.
- Clicking Run generates events, but you now see a lot fewer events than in Step 3 since only events related to the Group object are firing.
- To filter out even more events:
- Select All in the Objects section.
- Clear the All check box in the S-R-C section.
- Select just the PinX check box in the third row of S-R-C section.
- Click Run. Now you see only events firing that result from changes to the Text XForm PinX cell.
- To see the effects of a command filter:
- Select All in the Objects section.
- Select the All check box in the S-R-C section.
- Clear the All check box in the Commands section, and then select the CmdTextBold check box.
- Click on the Visio drawing window and select the Fast Lane shape.
- Click the Bold button on the Toolbar and there should be one event.
- Clear the CmdTextBold check box.
- Click Bold again and there should be no new events, thus indicating the command filter has screened out the Bold button.
- You can view other event filtering results by selecting and clearing the check boxes in the Event Control Window dialog box, and clicking Run. You can also change items on the Visio screen directly to see how many events are generated.
To Exit the Demo
- Click Exit to return to the Sample Information window.
- If you want to view the code that does the filtering, click Exit to Visio. From the Tools menu, select Macros, and then select Visual Basic Editor.
The code that does the actual filtering is in a separate module named EventFilters.
- If you want to run the demo again, right-click on the picture and select the StartEventSample macro at the top of the list.
- Click Exit All in the Sample Information window to close the sample. Or just close the Visio drawing if the window is not visible.
Do not save the file as it is set to read only, which reminds you not to save any changes you might have made.
The filtering is controlled by three arrays. Each array is applied to the events that are generated to screen out events before they are sent to the event sink. All three filters are applied to the events. If you don't want a particular filter to affect the events, you must set it to pass all events or just leave it in its original state when the event object was created.
The first array is the simplest and consists of six object types and their associated settings. Each object type can be set True or False to allow or disallow events that are associated with that type. In the sample, each object type has a check box, and each check box controls the True/False setting in the filter array. Since there are only six terms, it is easiest to just set all six in the array. If you set them all True, then the filter lets all events through. If all are set False, then no events are passed through the filter.
The second array is the Section, Row, and Cell (SRC) array. Each entry in the array consists of seven elements: start section, start row, and start cell, end section, end row, end cell, and the true or false setting. The true or false setting applies to all cells specified in the range. In this sample, the All check box sets a filter that passes all cell events. If none of the boxes are checked, then the sample code specifically puts in a filter that excludes all the cells. Note that setting a filter with only false terms has a special effect of disabling the false ranges but enabling all the rest of the cells. The sample code does not do that for the SRC filter. By selecting one of the PinX or PinY check boxes, the sample creates a filter that allows a single cell to generate events.
The third array filters events that occur as a result of executing UI commands like the command bar buttons. Each entry is three elements: start UI command, end UI command, and the true or false setting. Care must be taken when using ranges with this filter because you can filter out commands you may not expect or want to filter. In the sample code, the All check box creates a filter that allows all UI commands to generate events, and the None check box causes none of the UI commands to generate events.
Special Notes about the Command Filter Method
Cell formulas or other conditions can cause events that are a result of a UI command but are not considered to be within the scope of the command filter and therefore are not controlled by the filter. In particular, the TEXTWIDTH and TEXTHEIGHT functions exhibit this behavior. Also, events may fire that are not filtered by the command filter if the bounding box changes as a result of a UI command.
Many UI commands do not have assigned names in the visUICmds list. Also, if you create your own buttons or dialogs, the buttons will have command IDs that will be affected by the command filter. For example, the None check box in the Commands section stops the Run button from generating events. The Run button is a UI command (as are any custom command bar buttons or menus), but does not have a defined visUICmds name and the value of the control falls among the other controls so it is possible to disable it inadvertently.
In general, care must be taken with the command filter because it is not as straightforward as the object and SRC filters. It is best simply to avoid setting the command filter if you don't need to filter any commands. Once you set a command filter, you cannot set it back to a non-filter state except by deleting the event object itself and creating a new one.
The VBA code in the sample is divided into two forms and two modules. The two forms are Information and EventControl. The first is simply the startup information, and the second is the dialog with all the check boxes that control the demo.
The two modules are EventFilters and CEventHandler. The CEventHandler is a very simple event sink that receives all the events, and increments the counter in the display. Normally the event processing code would be placed here to respond to events that are fired. The EventFilters module contains the code that actually sets the filters and is the module of most interest to a developer who wants to use these new methods. This module is commented to help understand how the filters work.
- Creating Visio 2002 Event Filters discusses how developers can refine the type of events sent to their event handlers.
- Developing Microsoft Visio Solutions Chapter 21, Handling Visio Events Visio Event Objects demonstrates how to create an event sink, get and set objects, and filter events that are passed to the event sink.
- For other details about using event filters, see the method topics prefixed with SetFilter and GetFilter in the Microsoft Visio Developer Reference in Microsoft Visio 2002 (on the Help menu, click Developer Reference).