This documentation is archived and is not being maintained.

Creating Visio 2002 Event Filters

This 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 Corporation

May 2001

Applies to:
   Microsoft Visio Professional 2002
   Microsoft Visio Standard 2002

Summary: This article discusses how developers can refine the type of events sent to their event handlers by using the AddAdvise method on any Microsoft Visio 2002 EventList object.

Download VisioEventFilters.exe.

Contents

Introduction
About Event Filters
Creating an Event Filter
Filter Reference
Event Filter Resources

Introduction

Event filters allow solution developers to have tighter control over the Microsoft® Visio® platform, specifically in the area of event handling. In previous versions of Visio, listening to cell-changed events was a yes or no question. One either listened to all cell changes, or to no cell changes. A Visio solution can quickly become overburdened when a drawing contains many objects, or when bulk operations (such as moving many shapes at a time) occur. Event filtering allows developers to tailor the events their solution listens to, and prevents many of the events they don't want to hear from being entered into the event queue.

This article assumes that you use the AddAdvise method in your events, and that you are interested in fine-tuning your event handling code. This article does not apply to the WithEvents mechanism for handling events in Microsoft® Visual Basic® and Microsoft Visual Basic for Applications.

For previous versions of Visio, developers called AddAdvise to indicate which events they wanted added to the EventList. The Visio engine then sent those events to event handlers in the developer's code. Microsoft Visio 2002 now provides an additional set of methods on the Event object that allows a developer to set filters on the events. The Visio engine passes the event queue through this filter before calling the event handler, thus reducing the number of events that the handler needs to process.

About Event Filters

You can think of the events triggered in a Visio application as a stream of water. Certain operations trigger lots of events that can overwhelm your event handler. Event filters can selectively control that stream until you have a flow that works for your application.

You can set event filters for four categories:

  1. Certain predefined Visio object types from the VisShapeTypes class:
    • Pages
    • Groups
    • Shapes
    • Foreign objects (imported shapes)
    • Guides
    • Documents
  2. Any individual cell specified by the section, row, and cell index.
  3. A range of cells indicated by specifying the section, row, and cell indexes.
  4. A range of Visio user interface (UI) commands specified by command ID.

For details about how to combine filter events, see Filter Event Logic.

Creating an Event Filter

The methods provided on the EventFilter object are SetFilterObjects, SetFilterSRC, SetFilterCommands, and the corresponding GetFilterObjects, GetFilterSRC, and GetFilterCommands. Figure 1 shows the event handling architecture.

Aa140328.evntfilters1(en-us,office.10).gif

Figure 1. Visio Event Filters

Register the events you want through the normal mechanism of calling the AddAdvise method of the EventList object with the appropriate VisEventCodes values. The following code excerpt registers a handler to be called whenever the value of a cell changes.

Set objEvent = objEventList.AddAdvise(visEvtCell + visEvtMod, evhEventSink, "", "")

To create and set an event filter, use the methods SetFilterObjects, SetFilterSRC, SetFilterCommands to limit the events by category. The following code excerpt initializes the SRC filter array and sets the filter for cell events affecting the first and second cell indexes in a user-defined row in a user-defined section.

Dim Filter(7) As Integer
   Filter(1) = visSectionUser      'begin Section
   Filter(2) = visRowUser          'begin Row
   Filter(3) = visCellFirst        'begin Cell Index
   Filter(4) = visSectionUser      'end Section
   Filter(5) = visRowUser          'end Row
   Filter(6) = visCellFirst + 1    'end Cell Index
   Filter(7) = True                'Only these events
   objEvent.SetFilterSRC Filter    'set the filter

Setting the filter to True causes the Visio engine to call the handler only for changes to cell indexes 1 and 2 in all rows of the user-defined section. Events triggered for other cell changes will be filtered out.

The corresponding methods GetFilterObjects, GetFilterSRC, and GetFilterCommands retrieve the current settings of the filters.

Filter Reference

This information applies to all the GetFilterxxx and SetFilterxxx methods.

Filter Event Logic

For an event to successfully pass through an object filter, a cell range filter, or a command filter, it must satisfy the following criteria:

  • It must be a valid object type, have a valid section, row, or cell reference, or have a valid command ID.
  • If all filters are True, the event must match at least one filter.
  • If all filters are False, the event must not match any filter.
  • If the filters are a mixture of True and False, the event must match at least one True filter and not match any False filters.

The filter event logic applies within a given method, and may not apply across all methods.

GetFilterCommands

This returns an array of command ranges and a True or False value indicating how to filter events for that command range.

Syntax

retVal = object.GetFilterCommands()

ObjectAn expression that returns an Event object.
RetValLong. An array consisting of multiples of three values: command ranges (begin and end) paired with a True or False value specifying how to filter events for that command range.

Remarks

The event filters described in the array returned by the GetFilterCommands method provide developers with a way of ignoring specified events based on command ID. The array returned is the array passed to the SetFilterCommands method for this Event object.

The array that is returned by the GetFilterCommands method can be interpreted in the following manner:

The number of elements in the array is a multiple of three values:

  • The first element contains the beginning command ID of the range (any member of VisUICmds class).
  • The second element contains the end command ID of the range (any member of VisUICmds class).
  • The third element contains a True or False value, which indicates whether you are listening to events for that command range (True to listen to events; False to exclude events).

For details about how to combine filter events, see Filter Event Logic.

For details about defining event filters using command IDs, see the SetFilterCommands method.

GetFilterObjects

This returns an array of object types and a True or False value indicating how to filter events for that object.

Syntax

retVal = object.GetFilterObjects()

ObjectRequired. An expression that returns an Event object.
RetValLong. An array consisting of multiples of two values: object types paired with a True or False value specifying how to filter events for that object.

Remarks

The event filters described in the array returned by the GetFilterObjects method provide developers with a way of ignoring specified events based on object type. The array returned is an array of all objects filterable for this event object.

The array that the GetFilterObjects method returns can be interpreted in the following manner.

The number of elements in the array is a multiple of two values:

  • The first element contains an object type (one of visTypePage, visTypeGroup, visTypeShape, visTypeForeignObject, visTypeGuide, or visTypeDoc).
  • The second element contains a True or False value, which indicates whether you are listening to events for that object (True to listen to events; False to exclude events).

For details about how to combine filter events, see Filter Event Logic.

For details about defining event filters using object types, see the SetFilterObjects method.

GetFilterSRC

This returns an array of cell ranges and a True or False value indicating how to filter events for that range.

Syntax

retVal = object.GetFilterSRC()

objectRequired. An expression that returns an Event object.
retValInteger. An array consisting of multiples of seven values: cell ranges (beginning section, row, cell and ending section, row, cell) paired with a True or False value specifying how to filter events for that range.

Remarks

The event filters described in the array returned by the GetFilterSRC method provide developers with a way of ignoring specified events based on object type. The array returned is the array passed to the SetFilterSRC method for this Event object.

The array that the GetFilterSRC method returns can be interpreted in the following manner.

The number of elements in the array is a multiple of seven values:

  • The first three elements describe the section, row, and cell of the beginning cell in the range.
  • The next three elements describe the section, row, and cell of the end cell in the range.
  • The last element contains a True or False value, which indicates whether you want to receive events for the specified range of cells (True to listen to events; False to exclude events).

For details about how to combine filter events, see Filter Event Logic.

For details about defining event filters using cell ranges, see the SetFilterSRC method.

SetFilterCommands

This specifies an array of command ranges and a True or False value indicating how to filter events for each command range.

Syntax

object.SetFilterCommands commands

ObjectRequired. An expression that returns an Event object.
commandsRequired Long. An array consisting of multiples of two values: command ranges (begin and end) paired with a True or False value specifying how to filter events for each command range.

Remarks

When an Event object created with the AddAdvise method is added to the EventList collection of a source object, the default behavior is that all occurrences of that event are passed to the event sink. The SetFilterCommands method provides a way of ignoring selected events based on command ID.

The commands argument passed to SetFilterCommands is an array defined in the following way.

The number of elements in commands is a multiple of three values:

  • The first element contains the beginning command ID of the range (any member of VisUICmds class).
    Note   Not all commands are defined with a constant. To get the command ID for a Menu, MenuItem, ToolbarItem, or AccelItem object, you can use the CmdNum property.
  • The second element contains the end command ID of the range (any member of VisUICmds class).
  • The third element contains a True or False value, which indicates whether you are listening to events for that command range (True to listen to events; False to exclude events).

For example, use the following argument to set up an array that blocks out a single command:

Dim cmdArray (1 * 3) As Long
   'Ignore the layout command
   cmdArray(1) = visCmdLayoutDynamic
   cmdArray(2) = visCmdLayoutDynamic
   cmdArray(3) = False
'Or, to set up an array that listens only to the Send to Back command:
Dim cmdArray (3 * 3) As Long
   ' Pay attention to the Send To Back command
   cmdArray(1) = visCmdObjectSendToBack
   cmdArray(2) = visCmdObjectSendToBack
   cmdArray(3) = True
'Ignore any command IDs before the Send To Back command
   commands(4) = visCmdCMDFIRST
   commands(5) = visCmdObjectSendToBack - 1
   cmdArray(6) = False
'Ignore any command IDs after the Send To Back command
   commands(4) = visCmdObjectSendToBack + 1
   commands(5) = visCmdCMDLAST
   commands(6) = False 

For details about how to combine filter events, see Filter Event Logic.

For details about retrieving event filters using command IDs, see the GetFilterCommands method.

SetFilterObjects

This specifies an array of object types and a True or False value indicating how to filter events for each object.

Syntax

object.SetFilterObjects objects

objectRequired. An expression that returns an Event object.
objectsRequired Long. An array consisting of multiples of two values: object types paired with a True or False value specifying how to filter events for each object type.

Remarks

When an Event object created with the AddAdvise method is added to the EventList collection of a source object, the default behavior is that all occurrences of that event are passed to the event sink. The SetFilterObjects method provides a way to ignore selected events based on object type.

The objects argument passed to SetFilterObjects is an array defined in the following manner.

The number of elements in the array is a multiple of two values:

  • The first element contains an object type (one of visTypePage, visTypeGroup, visTypeShape, visTypeForeignObject, visTypeGuide, or visTypeDoc).
  • The second element contains a True or False value, which indicates whether you are listening to events for that object (True to listen to events; False to exclude events).

For example, if you want to listen only to events sourced by a shape or guide, you can pass an array like this:

Dim objArray (2 * 2) As Long
   objArray(1) = visTypeShape
   objArray(2) = True
   objArray(3) = visTypeGuide
   objArray(4) = True

For details about how to combine filter events, see Filter Event Logic.

For details about retrieving event filters using object types, see the GetFilterObjects method.

SetFilterSRC

This specifies an array of cell ranges and a True or False value indicating how to filter events for each cell range.

Syntax

object.SetFilterSRC SRCStream

objectRequired. An expression that returns an Event object.
SRCStreamRequired Integer. An array consisting of multiples of seven values: cell ranges (beginning section, row, cell and ending section, row, cell) paired with a True or False value specifying how to filter events for each range.

Remarks

When an Event object created with the AddAdvise method is added to the EventList collection of a source object, the default behavior is that all occurrences of that event are passed to the event sink. The SetFilterSRC method provides a way to ignore selected events based on a range of cells.

The SRCStream argument passed to SetFilterSRC is an array defined in the following manner:

The number of elements in the array is a multiple of seven values:

  • The first three elements describe the section, row, and cell of the beginning cell in the range.
  • The next three elements describe the section, row, and cell of the end cell in the range.
  • The last element contains a True or False value, which indicates whether you are listening to events for that cell range (True to listen to events; False to exclude events).

For example, use the following argument if you want to listen for any changes in the Value cells of the Custom Property section:

Dim srcArray (1 * 7) As Long
   srcArray(1) = visSectionProp
   srcArray(2) = visRowProp
   srcArray(3) = visCustPropsValue
   srcArray(4) = visSectionProp
   srcArray(5) = visRowLast
   srcArray(6) = visCustPropsValue
   srcArray(7) = True

For details about how to combine filter events, see Filter Event Logic.

For details about defining event filters using cell ranges, see the GetFilterSRC method.

Event Filter Resources

  • Visio 2002: Event Filters Sample demonstrates how to filter events. Download here.
  • Developing Microsoft Visio Solutions (2002) has a chapter titled "Filtering Your Event Object" that demonstrates how to create an event sink, get and set objects, and filter events that are passed to the event sink. Watch for this on the MSDN Visio Developer Center.
  • 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).
Show: