Getting a Visio Instance | Developing Microsoft Visio Solutions (Pro-Documentation)

3 4

Any external program that controls Microsoft Visio through Automation must interact with a Visio instance. Depending on the purpose of your program, you might want to run a new Visio instance or use an instance that is already running.

Creating an Application Object

After you declare a Visio object variable for an Application object, you can use the CreateObject function in a Set statement to create the object and assign it to the object variable. You can then use the object variable to control the instance. For example:

 Set appVisio = CreateObject("Visio.Application")

Creating an Application object runs a new Visio instance, even if other instances are already running.

You can also use the CreateObject function to create a Visio instance that is invisible. For example:

 Set appVisio = CreateObject("Visio.InvisibleApp")

You can then use the Application object's Visible property to control whether the instance is visible.

Note

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 earlier than Microsoft Visio 2000.

Getting an Application Object

You can use the GetObject function to retrieve an Application object for a Visio instance that is already running. For example:

 Set appVisio = GetObject(, "Visio.Application")

Notice the comma, which indicates that the first argument to GetObject —a path to a file that is stored on the hard disk—has been omitted. The comma is required, because under some circumstances, GetObject takes a file name as its first argument. To retrieve a Visio instance, however, you must omit the file name argument or an error will occur. For details, see GetObject in your Microsoft Visual Basic documentation.

If more than one Visio instance is running, GetObject returns the active instance. When a program is run as an add-on or by double-clicking a shape, the active instance is the one that the program was run from. Otherwise, it is the instance that was most recently run or brought to the front. If no Visio instance is running, GetObject causes an error.

Releasing an Application Object

An application instance persists until you use the Quit method or a user closes the instance. You might want to include some error handling or use events to handle a user closing the instance, which can occur unexpectedly while your program is running.

Releasing an object in a program does not affect the corresponding object in the Visio instance. For example, releasing an Application object does not close Visio. The Visio application remains open, but your program no longer has access to it.

To release an Application object explicitly, set its object variable to the Visual Basic keyword Nothing. For example:

 Set appVisio = Nothing

Don't release an object until you're finished using it. Once you release the object, the program can no longer refer to the corresponding object in the Visio instance. For example, if you release an Application object, the program can no longer use that variable to manipulate Visio, so it is unable to save or close the document or retrieve other objects from it.

To determine when to release objects from your program, you could write event handlers that release objects in response to events such as BeforeQuit or BeforeDocumentClose. For details on handling events, see Chapter 21, Handling Visio Events.

Note

If you are developing a COM add-in in Visual Basic, you do not need to call CreateObject or GetObject to get the Visio Application object. The Application object will be passed into the OnConnection method of your COM add-in. However, you'll need to save the Application object if you need to use it in your COM add-in. In the OnDisconnection method, you'll need to release the Application object by setting it to Nothing. For more details on implementing COM add-ins, see Chapter 23, Using COM Add-ins in a Visio Solution.

Using the Application Object in a Visual Basic Program: an Example

The following Visual Basic subroutine creates an Application object that runs a Visio instance and creates a drawing by opening a template and stencil. This subroutine follows these steps:

Creates a Visio instance.
Creates a new document based on the Basic Diagram template.
Drops an instance of the Rectangle master from the Basic Shapes stencil on the drawing page.
Sets the text of the rectangle shape on the drawing page to "Hello World!".
Saves the document.
Closes the Visio instance.

 Sub HelloWorld ()       'Instance of Visio       Dim appVisio As Visio.Application       'Documents collection of instance       Dim docsObj As Visio.Documents       'Document to work in       Dim docObj As Visio.Document       'Stencil that contains master       Dim stnObj As Visio.Document       'Master to drop       Dim mastObj As Visio.Master       'Pages collection of document       Dim pagsObj As Visio.Pages       'Page to work in       Dim pagObj As Visio.Page       'Instance of master on page       Dim shpObj As Visio.Shape       'Create an instance of Visio and create a document based on the        'Basic Diagram template. It doesn't matter if an instance of        'Visio is already running;the program will run a new one.       Set appVisio = CreateObject("visio.application")       Set docsObj = appVisio.Documents       'Create a document based on the Basic Diagram template that        'automatically opens the Basic Shapes stencil.       Set docObj = docsObj.Add("Basic Diagram.vst")       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("Basic Shapes.vss")       Set mastObj = stnObj.Masters("Rectangle")       '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 = "Hello World!"       'Save the drawing and quit Visio. The message pauses the program       'so you can see the Visio drawing before the instance closes.       docObj.SaveAs "hello.vsd"       MsgBox "Drawing finished!", , "Hello World!"       appVisio.Quit End Sub

CreateObject is a Visual Basic function that creates an Automation object—in this example, CreateObject runs a new Visio instance and returns an Application object that represents the instance, which is assigned to the variable appVisio. The next six Set statements obtain references to the other objects that the program uses by getting properties of objects obtained earlier. Notice again the progression through the Visio object model from Application object to Documents collection to Document object to Pages collection to the Page object.

Set docObj = docsObj.Add("basic diagram.vst") uses the Add method to open a template and add it to the Documents collection. For details about adding Document objects, see Creating a Visio Document later in this chapter.

The statement appVisio.Quit uses the Quit method to close the Visio instance assigned to appVisio.

Note

This example does not explicitly release any of the objects used in the program by setting them to the Visual Basic keyword Nothing (Set appVisio = Nothing). It is good programming practice to explicitly release objects from your program when you are finished using them.

Working with an Instance's Window Handle

You can exert more control over a Visio instance by getting its window handle. After you get the window handle, you can manage the instance's frame window just as you would manage any other frame window from a Microsoft Windows application. For example, you might minimize the instance while your program is creating a complex drawing to save time repainting the screen.

The Application object's WindowHandle32 property returns the window handle for the main, or frame, window of an instance. You can use HWND with standard Windows API calls to obtain other handles. For example, you can pass the window handle to GetWindowTask to get the Visio task handle.

For details about using Windows API calls, see your Microsoft Visual Basic documentation.

Interacting with Other Programs

While your program is running, you can find out which programs are available to the Visio engine, or install another program by getting the Addons collection of an Application object. This collection contains an Addon object for each program in the folders specified by the Application object's AddonPaths and StartupPaths properties or Addon objects that are added dynamically by other programs.

Note

To get a list with information on all COM add-ins currently registered in Visio, use the COMAddIns property. For details, see Using the COMAddIns Property to Get Information about COM Add-ins in Chapter 23, Using COM Add-ins in a Visio Solution.

By default, the programs represented by Addon objects are listed in the Macros dialog box and on the Macros submenu, along with VBA macros for the document that is open. When Visio is running in developer mode, the programs represented by Addon objects are listed in the Run Add-on dialog box (on the Tools menu, point to Add-ons, and then click Run Add-on) and on the Add-ons submenu.

You can add a program such as an EXE file by using the Add method of the Application object's Addons collection. The newly added program remains in the collection until the Visio instance is closed.

 Set addonsObj = Visio.Application.Addons Set addonObj = addonsObj.Add("c:\temp\myprog.exe")

Get the Name property of an Addon object to find out its name; get its Enabled property to find out whether it can be run. An EXE file is always enabled, but a program in a Visio library might not be. For details, see Chapter 28, Programming Visio with C++.

To run another program, use the Run method of the corresponding Addon object and include any necessary arguments or a null string ( "" ).

For more details about Addon objects, their methods, and their properties, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).