MustFlushScopeBeginning event

   Example   

Occurs before the Microsoft Visio instance is forced to flush its event queue.

Version added

5.0

Syntax

Private Sub object_MustFlushScopeBeginning(ByVal app As IVApplication)

Remarks

This event, along with the MustFlushScopeEnded event, can be used to identify whether or not an event is being fired because Visio is forced to flush its event queue.

Visio maintains a queue of pending events that it attempts to fire at discrete moments when it is able to process arbitrary requests (callbacks) from event handlers.

Occasionally, Visio is forced to flush its event queue when it is not prepared to handle arbitrary requests. When this occurs, Visio first fires a MustFlushScopeBeginning event, then it fires the events that are presently in its event queue. After firing all pending events, Visio fires the MustFlushScopeEnded event.

After Visio has fired the MustFlushScopeBeginning event, client programs should not invoke Visio methods that have side effects until the MustFlushScopeEnded event is received. A client can perform arbitrary queries of Visio objects when Visio is between the MustFlushScopeBeginning event and MustFlushScopeEnded event, but operations that cause side effects may fail.

Visio performs a forced flush of its event queue immediately prior to firing a before event such as BeforeDocumentClose or BeforeShapeDelete because queued events may apply to objects that are about to close or be deleted. Using the BeforeDocumentClose event as an example, there can be queued events that apply to a shape object in the document that is being closed. So, before the document closes, Visio fires all the events in its event queue.

Events are fired in the following sequence when a shape is deleted:

1. MustFlushScopeBeginning event
   Client should not invoke methods with side effects.

2. There are zero (0) or more events in the event queue.

3. BeforeShapeDelete event
   Shape viable, but Visio is going to delete it.

4. MustFlushScopeEnded event
   Client can resume invoking methods with side effects.

5. ShapesDeleted event
   Shape has been deleted.

6. NoEventsPending event
   No events remain to be fired.

An event is fired both before (BeforeShapeDeleted event) and after (ShapesDeleted event) the shape is deleted. If a program monitoring these events requires that additional shapes be deleted in response to the initial shape delete, it should do so in the ShapesDeleted event handler, not the BeforeShapeDeleted event handler. The BeforeShapeDeleted event is inside the scope of the MustFlushScopeBeginning event and the MustFlushScopeEnded event, while the ShapesDeleted event is not.

Note The sequence number of a MustFlushScopeBeginning event may be higher than the sequence number of events the client sees after it has received the MustFlushScopeBeginning event because Visio assigns sequence numbers to events as they occur. Any events that were queued when the forced flush began have a lower sequence number than the MustFlushScopeBeginning event, even though the MustFlushScopeBeginning event fires first.

If you're using Microsoft Visual Basic or Visual Basic for Applications, the syntax in this topic describes a common, efficient way to handle events.

If you want to create your own Event objects, use the Add or AddAdvise method. To create an Event object that runs an add-on, use the Add method as it applies to the EventList collection. To create an Event object that receives notification, use the AddAdvise method. To find an event code for the event you want to create, see Event codes.