If you’ve dabbled with the VBA project that resides in Visio documents, then you’ve likely stumbled upon the Document object’s DocumentOpened event. This is a great place for running any initialization code that you might require, but there’s a better way…

When you search the events that are fired by the built-in Document object, there are two obvious choices for initialization code that jump out at you: DocumentCreated and DocumenOpened. DocumentCreated fires when a copy of a document is opened (which is what happens by default when you open a Visio template.) DocumentOpened fires, of course, when you open a Visio document.

A better choice, however is RunModeEntered, as we’ll soon see.

The Obvious Startup Events

You can paste the following two subroutines into a Visio document’s VBA project, save the document, then test by opening a copy of the document, or by opening the original version:

Private Sub Document_DocumentCreated(ByVal doc As IVDocument) 

  ' This procedure runs when a Visio document is

  ' created.

  ' Ie: when a copy of a document is opened, or a

  ' template (.vst) is opened. In fact, a .vst file

  ' is simply anormal Visio document that happens

  ' to open a copy as a copy by default. That's the

  ' essential difference between a .vst and a .vsd. 

  Call MsgBox("Document_DocumentCreated") 

End Sub 

Private Sub Document_DocumentOpened(ByVal doc As IVDocument) 

  ' This procedure runs when a Visio document is

  ' opened. 

  Call MsgBox("Document_DocumentOpened") 

End Sub

Enter RunModeEntered

The trouble with the two events we’ve discussed becomes evident when you start to (frequently) test your code. You have to keep closing and opening the documents to test the code! Since the initialization code for open-original vs. open-copy is often identical, it makes sense to use the less-well-known event: RunModeEntered.

Document_RunModeEntered is also an event that hangs off of the Document object, just like the other two events we just talked about. The great thing about RunModeEntered is that it fires when you toggle the VBA Design Mode button. The button shows a little blue triangle with pencil and ruler. The button is a toggle button, and it looks like this:

Design Mode On

Design Mode Off

When design mode is off, VBA code won’t execute, so you can “live in peace” and perform certain operations without having to worry about code executing while you are adjusting controls on Windows forms, or Visio shapes and masters.

You’ll find this button in two places:

• Visio’s Developer toolbar
• VBA’s Standard toolbar

When you toggle the Design Mode button back to “on”, then the Document_RunModeEntered event fires, and any code in this Sub will execute! No more closing and opening your document just to test! You can paste the Sub below into your VBA project and give it a go.

Private Sub Document_RunModeEntered(ByVal doc As IVDocument) 

  ' This procedure runs when a Visio document is

  ' created or opened. It also runs when the VBA

  ' "Design Mode"/ "Exit Design Mode" button is

  ' pressed.

  ' Since this procedure runs when a document is

  ' opened or created, it serves as a more convenient

  ' place for calling your initialization code,

  ' since you can simply click the little blue

  ' triangle from within the VBA editor, or from

  ' Visio's "Developer" toolbar.

  Call MsgBox("Document_RunModeEntered") 

End Sub

RunModeEntered is also convenient for resetting a diagram that “has gone wrong.” Of course, we’d all like to write perfect code, but unfortunately, problems do arise. It may be acceptable to tell your users to “Show the Developer toolbar and toggle the Design Mode button off, then on” to reset the diagram. Not an optimal solution, but perhaps a quicker fix than taking users into the VBA project or other icky possibilities.

RunModeEntered isn’t the only solution. You could just write an initialization subroutine, say “m_init”, and call that from DocumentOpened or DocumentCreated. You can put your cursor inside of this subroutine and press F5 to run the code without having to close and re-open the document. But here agian, RunModeEntered can be more convenient, because you can restart the code from the Visio drawing interface. No Alt+Tab-bing back to VBA.

TODO

Information about persistent events that are stored with the document might top-off this article rather nicely.

Persistent Events are events that are stored in a Visio document, but not as VBA code. They can be used to start add-ons or add-ins on document open/create. There is no easy user-interface for editing these events, so they can only be accessed via code.

Examples include the Org Chart Wizard template, and the Cross-functional Flowchart template, both of which present the users with custom-code dialog boxes on open.

See:

• Document Object > EventList property in the Visio Developer’s Reference help file
• Microsoft Office Visio Persistent Events Tool that is included with the Visio 2007 SDK

Related Posts

1. Combo Box Table of Contents
2. Data Refresh on Open
3. VBA Macro Security
4. Save Time & Simplify Your VBA Code With CallByName
5. LengthIU Bug Workaround Code