Microsoft KB Archive/829915

= How to use OLE automation in Visio 2003 =

PSS ID Number: 829915

Article Last Modified on 8/11/2004

-

The information in this article applies to:


 * Microsoft Office Visio Professional 2003
 * Microsoft Office Visio Standard 2003

-





For a Microsoft Visio 2002 version of this article, see 309603.



IN THIS TASK

 * INTRODUCTION
 * Overview of automation
 * Getting started
 * Automate Visio 2003
 * Step 1: Add a reference to the Visio 2003 Type Library
 * Step 2: Declare the object variable
 * Step 3: Set the variable
 * Step 4: Use the Visio objects, methods, and properties
 * REFERENCES



INTRODUCTION
This article contains information about how to use Microsoft Visual Basic or Microsoft Visual Basic for Applications (VBA) to automate Microsoft Office Visio 2003 from another Microsoft Office program.

Microsoft provides programming examples for illustration only, without warranty either expressed or implied, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. This article assumes that you are familiar with the programming language that is being demonstrated and the tools that are used to create and debug procedures. Microsoft support professionals can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific requirements. If you have limited programming experience, you may want to contact a Microsoft Certified Partner or the Microsoft fee-based consulting line at (800) 936-5200. For more information about Microsoft Certified Partners, visit the following Microsoft Web site:

http://directory.microsoft.com/resourcedirectory/Solutions.aspx

For additional information about the support options available from Microsoft, visit the following Microsoft Web site:

http://support.microsoft.com/default.aspx?scid=fh;%5BLN%5D;CNTACTMS

back to the top

Overview of automation
Automation (also known as OLE automation) in Visual Basic is the process of controlling one program from another program or an external development tool. You can automate any program that contains a Visual Basic object model. An object model is a hierarchical collection of the program's objects that are available or are exposed to Visual Basic.

For example, the object model for Microsoft Visio contains objects such as the following:
 * Application/global object
 * Document object
 * Page object
 * Master object
 * Selection object
 * Shape object
 * Window object

Each of these objects has a unique set of methods and properties that are required to manipulate the objects in Visual Basic. For example, a Shape object can represent any object on a Visio drawing page that you can select by using the pointer such as a shape, a group, a guide, a control, or an object from another program that is linked, is embedded, or is imported to a Visio drawing.

back to the top

Getting started
The code samples in this article demonstrate how to control Visio 2003 from Microsoft Office Access 2003, Microsoft Office Excel 2003, Microsoft Office PowerPoint 2003, Microsoft Office Word 2003, Microsoft Visual Basic 6.0, or any program that includes a Visual Basic development tool. To automate Visio 2003, follow these four main steps:
 * 1) Add a reference to the Visio 2003 Type Library.
 * 2) Declare a variable as a Visio object type--for example, use Visio.Application or Visio.Documents.
 * 3) Assign the GetObject method or the CreateObject method to the object variable that you declared in step 2.
 * 4) Use the properties, the methods, and the child objects of the Visio object to automate Visio.

back to the top

Automate Visio 2003
The following is an example of how to automate Visio.

Step 1: Add a reference to the Visio 2003 Type Library
To add a reference to the Visio 2003 Type Library by using Access 2003, PowerPoint 2003, Excel 2003 or Word 2003, follow these steps:
 * 1) In Access, PowerPoint, Excel, or Word, on the Tools menu, point to Macros, and then click Visual Basic Editor.
 * 2) On the Tools menu, click References.

Note To add the reference by using either Microsoft Visual Basic.NET or Visual Basic 6.0, on the Project menu, click References.
 * 1) In the Available References list, click to select the Microsoft Visio 11.0 Type Library check box.

When you add the Microsoft Visio 11.0 Type Library reference, your program can access Microsoft Visio Online Help and the Visio object model. Because the references are saved in each project, you have to add the Visio type library reference for each Visual Basic or for a VBA project that you want to use to automate Visio.

back to the top

Step 2: Declare the object variable
To declare a Visio object variable, dimension a variable as a specific Visio object type, such as Visio.Application, Visio.Documents, or Visio.Page.

Explicitly declaring the object type is known as early binding because the controller application connects or binds the object to the Visio application at compile-time instead of at run-time. This gives you access to Visio auto lists and context-sensitive Help, and allows the code to run more efficiently.

For additional information about object binding, click the following article number to view the article in the Microsoft Knowledge Base:

138138 INFO: Late, ID, early binding types possible in VB for Apps

The following sample Visual Basic argument declares the variable AppVisio as an object of type Visio.Application: Dim AppVisio as Visio.Application back to the top

Step 3: Set the variable
You can use the following two Visual Basic methods to activate Visio:
 * CreateObject
 * GetObject

The primary difference is that the CreateObject method creates a new instance of Visio, and the GetObject method uses an instance of Visio that is already running. You can also use the GetObject method to set your object variable to a specific Visio document. The following sample argument sets the AppVisio variable to the Visio program by using the CreateObject function: Dim AppVisio as Visio.Application

Set AppVisio = CreateObject(&quot;Visio.Application&quot;) Sometimes, you may want to use an existing Visio instance if Visio is already running, but create a new instance if Visio is not running. To do this, create an error handler that uses the CreateObject method in case the GetObject method fails, as shown in the following sample code: Dim AppVisio As Visio.Application

On Error Resume Next

Set AppVisio = GetObject(, &quot;visio.application&quot;)

If AppVisio Is Nothing Then Set AppVisio = CreateObject(&quot;visio.application&quot;) End If Note You can also use the CreateObject function to create a Visio instance that is invisible. See the following example: Set AppVisio = CreateObject(&quot;Visio.InvisibleApp&quot;) You can then use the Application object's Visible property to control whether the instance is visible.

You can use the InvisibleApp object with only the CreateObject function. Attempts to use it with the GetObject function will fail. The InvisibleApp object is not available in versions of Visio that are earlier than Microsoft Visio 2000.

Step 4: Use the Visio objects, methods, and properties
After you complete steps 1 through 3, you can use the Visio object variable to automate Visio.

The following sample macro uses automation to start Visio, creates a new drawing (document) based on the Basic Diagram template, drops a rectangle, adds some text, saves the drawing, and then quits Visio. Sub AutoVisio

Dim AppVisio As Visio.Application ' Declare an Instance of Visio. Dim docsObj As Visio.Documents    ' Documents collection of instance. Dim DocObj As Visio.Document      ' Document to work in. Dim stnObj As Visio.Document      ' Stencil that contains master. Dim mastObj As Visio.Master       ' Master to drop. Dim pagsObj As Visio.Pages        ' Pages collection of document. Dim pagObj As Visio.Page          ' Page to work in. Dim shpObj As Visio.Shape         ' Instance of master on page.

' Create an instance of Visio and create a document based on the ' Basic Diagram template. It does not matter if an instance of  ' Visio is already running, CreateObject will run a new one. Set AppVisio = CreateObject(&quot;visio.application&quot;)

Set docsObj = AppVisio.Documents

' Create a document based on the Basic Diagram template that ' automatically opens the Basic Shapes stencil. Set DocObj = docsObj.Add(&quot;Basic Diagram.vst&quot;)

Set pagsObj = AppVisio.ActiveDocument.Pages

' A new document always has at least one page, whose index in the ' Pages collection is 1. Set pagObj = pagsObj.Item(1)

Set stnObj = AppVisio.Documents(&quot;Basic Shapes.vss&quot;) Set mastObj = stnObj.Masters(&quot;Rectangle&quot;)

' Drop the rectangle in the approximate middle of the page. ' Coordinates passed with the Drop method are always inches. Set shpObj = pagObj.Drop(mastObj, 4.25, 5.5)

' Set the text of the rectangle. shpObj.Text = &quot;This is some text.&quot;

' Save the drawing and quit Visio. The message pauses the program ' so you can see the Visio drawing before the instance closes. DocObj.SaveAs &quot;MyDrawing.vsd&quot; MsgBox &quot;Drawing finished!&quot;,, &quot;AutoVisio (OLE) Example&quot;

' Quit Visio. AppVisio.Quit

' Clear the variable from memory. Set AppVisio = Nothing

End Sub



Microsoft Visio developer Web site
For additional information about how to automate Visio, visit the following Microsoft Web site:

http://msdn.microsoft.com/office/understanding/visio

Newsgroups
The following peer-to-peer newsgroups are available to help you interact with other users of VBA:

microsoft.public.vb.ole.automation

microsoft.public.visio.developer.vba

Visual Basic Help
For more information about how to use the CreateObject function, in the Visual Basic Editor, on the Help menu, click Microsoft Visual Basic Help, type createobject function in the Search box, and then click Search to view the topics that are returned.

For more information about how to use the GetObject function, in the Visual Basic Editor, on the Help menu, click Microsoft Visual Basic Help, type getobject function in the Search box, and then click Search to view the topics that are returned.

Keywords: kbProgramming kbAutomation KbVBA kbHOWTOmaster KB829915

Technology: kbVisio2003Pro kbVisio2003Search kbVisio2003St kbVisioSearch

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.