Mark Bukovec
Empire Down Development
September 2003
Applies to:
Microsoft® Office Visio® 2003
Summary: Learn to integrate the Microsoft® Office Visio® 2003 ActiveX® Control, also referred to as the Visio drawing control, into applications. Review best practices and how to use the Visio drawing control programmatically. (24 printed pages)
Contents
Introduction
Understanding the Visio Drawing Control
Scenarios for Using the Visio Drawing Control
Design Best Practices
Getting Started
Integrating the Control with the Host Container
Deployment
Conclusion
Introduction
The Microsoft® Office Visio® 2003 ActiveX® Control (Visio drawing control) offers the full functionality of the Visio application through the rich Visio object model, as an embeddable component. You can drive the Visio drawing control programmatically by events or by code in your hosting application. Alternatively, the Visio drawing control can provide a diagramming environment for application users within the context of your own application's user interface (UI).
In this article, you will learn:
- The features of the Visio drawing control and example use scenarios.
- Best practices for using the Visio drawing control in Visio solutions.
- How to embed the Visio drawing control in a variety of host applications, including Microsoft Windows® Forms, Microsoft Visual Basic® 6.0 forms, Microsoft Office documents, and Microsoft Internet Explorer.
- How to use the properties of the Visio drawing control API.
- How to load Visio documents into the drawing control window and save changes.
- How to get a reference to the Visio Application object in order to work programmatically with the Visio document.
- How to manage the display of the drawing surface.
- How to integrate the control with your host application user interface.
- How to deploy the Visio drawing control with your application.
Understanding the Visio Drawing Control
The Visio drawing control provides the functionality of the Visio application object model in a component. The Visio drawing control can be embedded in host applications developed using Microsoft Visual Studio® .NET 2003, Microsoft Office XP and Microsoft Office 2003 containers such as Microsoft Office Word 2003, Microsoft Internet Explorer 5.0 and later, and other Microsoft ActiveX® control containers. Once added, the Visio drawing control provides a drawing surface for displaying shapes.
The Visio drawing control allows the developer to provide Visio functionality within the context of another application. This new level of integration allows the developer full control over the Visio user interface integration with the host application. The new functionality provides more power than just simply embedding a Visio drawing into an OLE container document, like Word. Using a Visio drawing as an OLE object allows you to view the diagram in the container application, link the OLE object to the actual Visio document to reflect changes, and edit the Visio drawing by activating the Visio application from within the container document.
In the case of in-place OLE activation, you are still working within the Visio user interface. You cannot create your own UI. You can't programmatically access the Visio document using Automation from the containing application. You are also limited to application hosts that implement an OLE container, which rules out technologies such as .NET Windows Forms.
The Visio drawing control, however, provides new functionality to address these scenarios, and allows you to develop new Visio solutions that weren't previously possible, such as those described in the following section of this article, "Scenarios for Using the Visio Drawing Control."
The Visio drawing control is distributed through the Visio product setup. There is also a primary interop assembly available for managed-code access to the Visio drawing control API. If you want to use the control from managed code, you must install the Visio primary interop assemblies. See the Deployment section of this article for details on installing the Visio drawing control and the Visio primary interop assemblies.
Scenarios for Using the Visio Drawing Control
To demonstrate the utility of the Visio drawing control, consider the following customer scenarios.
- A company's facilities department provides an office space-planning application for administrative assistants. A Windows Form hosts the drawing control, which displays an area representing the layout of the office. Next to the drawing control are buttons representing office furniture. When the administrative assistant clicks a button, a shape is dropped on the drawing form, which he can then reposition in the drawing control to see how the furniture arrangement looks in the office.
The Windows Form contains an event handler, written in Visual Basic .NET, which responds to a new shape being added and tracks the furniture selections to generate a purchase order. The administrative assistant can rearrange and remove the furniture selections by deleting shapes in the drawing control. Because the administrative assistant is driving the drawing surface from the form's UI, the user does not have to be familiar with the Visio application.
- A management team is working on a flowchart to map out employee processes. To help collaboration, the team uses Microsoft Office SharePoint™ Portal Server, which provides a central storage point for team documentation and tools for collaborating and sharing documents. The managers aren't familiar with drawing tools and would prefer to enter process steps in a Microsoft Office Excel spreadsheet and have Visio generate the flowchart drawing from that data. Furthermore, they would like to view all their data on the same browser page.
To implement these requirements, the application developer modifies the team page on the SharePoint site by adding a data sheet Web Part that displays the Excel spreadsheet for defining the process steps. Then the developer creates a custom Web Part that hosts the drawing control. The developer links the two Web Parts together and a flowchart is automatically generated inside the drawing control from the process step information in Excel. If a manager wants to modify the flowchart, she edits a row in the data sheet Web Part, and the flowchart shapes are refreshed to reflect the changes. This solution allows the managers to do all their updates within the same browser page and work with the tools they are most comfortable using.
The control lets you build event-driven applications like the ones just described using a variety of host containers. Rather than building a solution that is hosted in the Visio application user interface, you can add the drawing surface component to your existing or planned application. In the case of the Visio drawing control, the application typically reflects the architecture shown in Figure 1.
Figure 1. Application hosting the Visio drawing control
Using the Visio drawing control in your application provides the following benefits:
- The Visio drawing control runs in-process with your application and does not require a separate instance of the Visio application to be running.
- The control displays a single Visio document and single window per instance. You can display multiple documents by embedding multiple control instances within the host application. The Visio drawing control also exposes a method for loading an existing Visio file.
- The control allows user interface integration with the host application. Developers can provide a simplified user interface for users unfamiliar with Visio.
- The host application can access Visio Automation properties and methods through the embedded control instance. This allows the host application to programmatically modify the contained Visio document.
- The control directly exposes Visio Window and Document events.
You can also develop a Visio drawing control solution using managed code. Managed code interoperability is provided through the Visio primary interop assemblies, which provide managed-code access to the Visio drawing control API and the Visio Automation library. Prior to the drawing control, for managed code you could only write a COM add-in or executable using a managed language. With the control, you can execute Visio Automation code directly from the application. This integration allows you to use Windows Forms as an application container and code in managed languages such as Visual Studio C++, Visual.NET C# or Visual Basic .NET.
Design Best Practices
Because the Visio drawing control is a programmable component, you can integrate your Visio solution code directly into the host container application. In previous releases of Visio, a developer writing a solution for the Visio client application needed to package the solution code in a COM add-in, Visio solution library (VSL), out-of-process executable, or in a Visual Basic for Applications (VBA) project in a document.
The Visio control simplifies solution architecture and the development process by allowing programming of the Visio Application object from the hosting application. A developer using the control in a custom application (such as a C# application) or Internet Explorer should program against the Visio object model directly in the host application, without separating the Visio logic into a COM add-in, VSL, or executable. Calling a Visio COM add-in, VSL, or executable from the hosting application unnecessarily complicates the debugging of the Visio integration.
However, if you would like to host the Visio control in a Microsoft Office System application other than Visio, you will have to use a COM add-in. In this case, create a COM add-in for your host application instead of for Visio. For example, if you plan to host your Visio control in a Microsoft Office Word 2003 document, create a Word COM add-in and access the Visio control through the Word add-in. Make sure your COM add-in is targeted at the host since an Office host application will not load a Visio COM add-in for the drawing control.
Working with Control Host Limitations
The Visio drawing control supports many containers, including hosting applications built in Visual Studio. NET 2003, Visual Studio 6.0, Internet Explorer 5.0 or later, ASP.NET, and other ActiveX control containers. However, the Visio control cannot be directly embedded in:
- Another ActiveX control, like the Internet Explorer browser control.
- A Visio document.
- A Microsoft Office InfoPath™ 2003 form.
Note You can embed ActiveX controls into the Visio drawing control (as opposed to the Visio drawing control embedded in another ActiveX control). However, because the Visio drawing control will not execute VBA code in a Visio document, it's better to integrate other ActiveX controls into the host application project instead of the Visio document.
Using the Visio Control with the Internet Explorer Browser Control
Even though you cannot embed the Visio drawing control directly into another ActiveX control, you can still use the Visio drawing control with applications that depend on the Internet Explorer browser control.
Internet Explorer 5.0 or later provides an excellent host container for the Visio drawing control, allowing developers to write script against the Visio object model in Microsoft Visual Basic Scripting Edition (VBScript) or ECMAScript as defined by the specification of the European Computer Manufacturers Association, such as JScript or JavaScript.
To integrate the Visio drawing control with an Internet Explorer browser control-based application, such as the Microsoft Office Project Web Access client, do the following:
- Add a link in your Internet Explorer browser control that launches a new Internet Explorer process with its own window.
- Embed the Visio drawing control in the new Internet Explorer window for the new Internet Explorer process.
- Program against the Visio drawing control using your preferred scripting language.
Using the Visio Control with Microsoft Office InfoPath 2003
While you cannot embed the Visio drawing control directly onto an InfoPath 2003 form, InfoPath provides a solution task pane containing an Internet Explorer window. You can embed the Visio drawing control directly into the InfoPath solution task pane window and use the Document Object Model (DOM) to share data between the Visio drawing and the InfoPath form.
Understanding the Visio Drawing Control's SDI
When designing an application that uses the Visio drawing control, it's important to understand that the Visio control supports a single document in a single window. The control's single document interface (SDI) architecture results in the following considerations when designing the Visio drawing control integration with your application:
- Use multiple instances of the Visio drawing control to display multiple Visio documents in your application. Unlike the Visio client application, which can display multiple documents and windows at a time, the Visio drawing control can only display a single document per instance of the control. If the developer wants to display multiple Visio documents, the developer can embed multiple instances of the control in the application, with each instance loading a separate Visio document.
- Do not depend on VBA for programming logic. VBA is not included with the Visio drawing control. As a result, documents loaded in the Visio drawing control do not execute any VBA code associated with the document. The control's lack of a VBA run-time environment prevents the distribution of legitimate code or malicious macros via documents loaded by the Visio control. It also means that the user of an application hosting the control will never see the Visio application's security dialog box warning about macros in the document.
- Use the Visio ShapeSheet® programmatically. The control does not provide access to the Visio ShapeSheet user interface, which is a separate window in the Visio application. However, the ShapeSheet itself still exists for the Visio shapes and pages in the document loaded in the Visio drawing control. You can still edit ShapeSheet cells for your Visio document in the control using Visio Automation. For example, you can use the Cell object's SRC property to add a double-click action for a Visio shape.
Note When you are programming the ShapeSheet for documents loaded in the control, you will not be able to use the CALLTHIS function, which calls a VBA macro in the document. The Visio drawing control does not execute VBA code, so any use of the CALLTHIS function fails silently. Instead, you can use the mouse events for the Visio Page and Document objects and handle the event response in your custom container application logic. (For more information about mouse events, see Handling Events.) If you are using a COM add-in, you can also use the QUEUEMARKER function to queue a marker event on the double-click event in the ShapeSheet.
Porting Existing Visio Solutions
When you are porting your code from an existing Visio client application solution to the Visio control, include these design considerations in your planning.
- Port VBA code. You must port all existing VBA code into a COM add-in, or more preferably, your host application. You can keep most of your same algorithms and logic, as long as it makes sense working within the control's SDI architecture.
- Port an existing Visio solution COM add-in, executable, or VSL to the container application. While it might be initially easier to simply use an existing COM add-in, executable, or VSL with the host application, it is recommended that you integrate the Visio drawing control programming directly with the host application. By taking the time to port your code from your existing solution to your host application, you'll simplify deployment of your solution, and streamline the development, debugging, and maintenance process over time. You do not need to use a COM add-in unless you are working with the control in another Office container.
- Re-evaluate data storage in shapes. If your current Visio solution stores extensive data in shapes, consider re-architecting data storage out of Visio shapes and into data structures maintained or accessed by the host application. Visio can store as much data as you need, but it often makes more sense to keep Visio as a presentation layer component and use your host application as data storage or access to a data source. If the data is relatively static, though, and used heavily for modifying the appearance and layout of shapes, it makes more sense to store the information in the shape custom properties.
- Think about event integration with the host application. Unlike a Visio client application solution, the Visio drawing surface can respond to both user events and host application events. Consider how you want the drawing surface to respond to events fired by the host application, and how your host application needs to respond to events in the Visio drawing surface.
- Use marker events for COM add-ins. If you must use a COM add-in, you will need a way to notify your COM add-in to respond to a user action in your document. Use the QUEUEMARKER function in the ShapeSheet or a persistent event with the document to queue a marker event to which your COM add-in responds.
Starting New Visio Development
If you are just starting Visio integration with an application, it's best to program directly against the Visio object model in your host application code. In addition to the design advice and implementation guidelines in this document, consult these resources for information on using the Visio object model:
- Microsoft Office Visio Automation Reference Provides technical documentation on the Visio object model.
- Microsoft Office Visio ShapeSheet Reference Provides technical documentation on ShapeSheet cells and functions that you can program through the Visio object model.
- Visio Developer Center on MSDN Provides articles, tutorials, and a software development kit (SDK) for Visio developers of all levels.
Getting Started
This section covers the basic steps for using the Visio drawing control in your application. It describes how to embed the control in a host container, how to load Visio documents into the control window and save changes, and how to get a reference to the Visio Application object so that you can work programmatically with the Visio document.
Creating a Visio Drawing Control Instance
This section details the procedures for creating Visio drawing control instances and setting references for the following containers: Windows Forms, Visual Basic 6.0 form-based applications, Office documents, and Internet Explorer.
Note A developer cannot activate a Visio drawing in the Visio control at design time. Visio drawings in the control activate at run time only.
Creating a Visio Drawing Control Instance in Managed Code
You can easily create a Visio drawing control instance in managed code.
Completing this procedure to add the following assembly references to your project:
- VisioOcx The Visio drawing control primary interop assembly.
- Visio The Visio type library primary interop assembly.
- AxVisOcx An ActiveX control wrapper assembly that allows the control to be embedded within a Windows Form. The Windows Forms ActiveX Control Importer (Aximp.exe) generates this assembly automatically and adds it to your project. This wrapper assembly must be redistributed with the application. Multiple Visio drawing control instances on a form share the same wrapper class derived from the AxHost class.
To add the Visio drawing control to a Windows Form
- In Visual Studio .NET, display the Windows Form in Design mode. Click the Toolbox.
- Right-click inside the Toolbox and choose Add/Remove Items to open the Customize Toolbox dialog box.
- Click the COM Components tab in the Customize Toolbox dialog box. Select Microsoft Visio Drawing Control for the type library, as shown in Figure 2.
Figure 2. Adding the Visio drawing control to the Visual Studio .NET Toolbox
- Click OK. The Visio drawing control is now available in the Toolbox, as shown in Figure 3.
Figure 3. Visio drawing control in the Visual Studio .NET Toolbox
- Add the Visio drawing control to the form either by double-clicking it in the Toolbox or by clicking it and then dragging it to the form.
Creating a Visio Drawing Control Instance in Visual Basic 6.0
You can easily create a Visio drawing control instance using Visual Basic 6.0. Completing this procedure to add a reference to the Visio drawing control type library. If you want to programmatically change the Visio document contained in the drawing control instance, you will need to add a reference to the Microsoft Visio 11.0 Type Library.
To add the Visio drawing control to a Visual Basic 6.0 form
- In Visual Basic 6.0, display the form in Design mode, right-click the Toolbox, and then choose Components.
- On the Controls tab in the Components dialog box, select Microsoft Visio Drawing Control 11.0, as shown in Figure 4.
Figure 4. Adding the Visio drawing control to the Visual Basic 6.0 Toolbox
- Click OK. The Visio drawing control is now available in the Toolbox.
Figure 5. The Visio drawing control in the Visual Basic 6.0 Toolbox
- Add the Visio drawing to the form either by double-clicking it in the Toolbox or by clicking it and then dragging it to the form.
Creating a Visio Drawing Control Instance in Microsoft Office System Application Document
Completing this procedure to add a reference to the Visio drawing control type library. If you want to programmatically change the Visio document contained in the drawing control instance, you will need to add a reference to the Microsoft Visio 11.0 Type Library.
To add the Visio drawing control to an Office application document
- Right-click the Office application's toolbar and choose Control Toolbox.
- On the Control Toolbox toolbar, click the More Controls button, and then select Microsoft Visio Drawing Control, as shown in Figure 6:
Figure 6. Adding the Visio drawing control to the Microsoft Office Word Toolbox
After inserting the Visio drawing control into an Office application document, you can view its properties by right-clicking it and choosing Properties. If you want to access the Visio drawing control programmatically from the document's Visual Basic project, right-click the control and choose View Code.
Creating a Visio Drawing Control Instance in Internet Explorer
To add the Visio drawing control to a Web Form or an HTML page, you will follow the procedure in Creating a Visio Drawing Control Instance in Managed Code, except that you will drag the Visio drawing control to your Web page instead of to a Windows Form. Visual Studio .NET adds the following HTML to the Web page:
Copy Code<OBJECT id="Drawingcontrol1" classid="clsid:E4615FA3-23B0-4976-BD3E-D611DDBE330E" VIEWASTEXT> <OBJECT>
Modifying the values in the Properties window updates the property tags for the Visio drawing control instance. For example, if you modify the Src property, Visual Studio .NET generates a tag similar to the following:
<PARAM NAME="Src" VALUE="C:\\Drawing.vsd">
The Visio drawing control is hosted as a client-side object and supports a limited number of properties for scripting languages such as VBScript. You can script changes to the properties exposed by the Visio drawing control. However, you cannot access the Visio object model using a scripting language, which means you won't be able to programmatically change the Visio document displayed by the control. The user can make changes to the Visio document by clicking the drawing surface.
Note The control will only initialize in the first thread of any given Internet Explorer process. If you would like to use multiple instances of the control in an Internet Explorer-based application, create a new Internet Explorer process for each additional instance of the control and load the HTML page containing the control in the new Internet Explorer process.
Getting a Reference to the Visio Application Object
You can access the Visio object model through the Visio drawing control's API. To get a reference to the Visio Application object, use either the drawing control's Document or Window property.
For example, the following C# code shows how to get a reference to the Visio Application object using the drawing control's Window property:
using Microsoft.Office.Interop.Visio; private Microsoft.Office.Interop.Visio.Application application = null; application = (Microsoft.Office.Interop.Visio.Application) drawingControl.Window.Application;
You can do the same thing using the following Visual Basic 6.0 code:
Dim vsoApplication As Visio.Application Set vsoApplication = DrawingControl.Window.Application
Managing Documents
When the Visio drawing control is loaded, it displays a blank Visio drawing. If you want to display an existing Visio document, the drawing control exposes an Src property for loading a document into the control. You can then use the document's SaveAs method to save any changes.
Loading a Visio Document
Use the Visio drawing control's Src property to load a document into the control. For example, the following C# example shows how to load a Visio drawing:
drawingControl.Src = "C:\\Drawing.vsd";
You can load any Visio file type using the Src property (for example, .vsd, .vdx, .vst, or .svg). The file can be stored locally or on a remote file server.
The Visio control's Src property loads a copy of the file specified in the Src value. To persist the changes in the control's document, you must save the Visio document using the SaveAs method. Alternatively, you can persist changes in-stream. In both cases, however, you do not modify the original document loaded by the Src property.
Saving a Visio Document to File
The control loads a copy of the file specified by the SRC property. The file loaded through SRC is not opened for read/write operations, and therefore cannot be saved using the Save method. To save changes to the document loaded in the Visio drawing control, call the document's SaveAs method. The following C# example shows how you can use the drawing control Document property to call the SaveAs method:
Visio.Document document = drawingControl.Document;
document.SaveAs("C:\\Drawing.vsd");
You cannot use the SaveAsEx method to save Visio 2003 documents to Visio 2002 format in the Visio ActiveX control. To save a drawing loaded in the Visio drawing control to Visio 2002 format, launch an invisible instance of Visio and call the SaveAsEx method in your Visio application instance, as demonstrated in this Visual Basic 6.0 code that saves a Visio 2003 drawing into the Visio 2003 file format:
Application.Documents(1).SaveAsEx("C:\Documents and Settings" & _
"\myusername\My Documents\Visio2002 file.vsd", visSaveAsWS + _
visSaveAsListInMRU)
Saving a Visio Document in the Control to Stream
Developers may want to persist changes to a drawing in the Visio drawing control without saving the drawing to disk. For example, if a user modifies a Visio document in an embedded control in a Word document, the changes are lost when the user forwards that Word document in an e-mail message. When another user opens the document, the control loads the file specified by the Src property, overwriting any modifications.
To persist changes in-stream to a Visio document in the control
- Load the original document using the Visio control's Src property.
- After the document loads, set the Src property to an empty string.
When the control is activated in its container document after the first initialization, the control displays the last in-stream image rather than the original document specified by the Src property.
Using Blank Documents in the Control
To load a blank drawing in the control when the control is initialized for the first time, set the Src property to an empty string. However, if you want to emulate creating a new blank drawing in the control after loading an existing drawing document, you have three choices:
- Select all and delete all shapes in the drawings. This approach allows the developer to preserve any existing styles in the currently loaded document.
- Load a new, blank document using the Src property.
- Dynamically destroy and reinitialize the Visio drawing control in the document.
Integrating the Control with the Host Container
You can modify the appearance of the Visio drawing control in your application. By default, all Visio toolbars are turned off and the stencil pane is not displayed. You can choose how the drawing control surface appears by displaying scroll bars, rulers, or by changing the window background color.
The drawing control exposes a PageSizingBehavior property that determines how the page is displayed within the drawing control window. You can choose to resize the page in relation to the drawing control's size, or provide a view similar to Visio, showing a portion of the drawing page.
Because the control only supports a single window, you cannot access the ShapeSheet or windows such as icon editor and master and group editing. The page and shape right-click menus are enabled by default. The limited Visio UI for controlling shape behavior reflects the intent of the control to be tightly integrated with the container application. The best approach for allowing users to modify shapes on a document is to use a custom UI. However, if you want to use Visio menus and toolbars, the drawing control does support menu and toolbar merging with the host application.
Most likely, your Visio drawing control application will be event-driven and respond to users clicking buttons or menu items contained in the application. The drawing control also exposes Visio events, so that you can respond to a user clicking within the control itself.
Managing the Drawing Surface Display
You can modify the appearance of the Visio drawing control's surface through the control's Window property. For example, the following C# code hides the drawing control's scroll bars:
drawingControl.Window.ShowScrollBars = (short)_ Visio.VisScrollbarStates.visScrollBarNeither;
This example hides both the horizontal and vertical scroll bars. Other possible values for the VisScrollbarStates enumeration include visScrollBarBoth (display both scroll bars), visScrollBarHoriz (display horizontal scroll bar), and visScrollBarVert (display vertical scroll bar).
By removing parts of the Visio UI, you can make the drawing control look more integrated within your application. The following C# code hides the rulers:
drawingControl.Window.ShowRulers = 0;
You can also change of the color of the window background to suit the color scheme of your application. For example, the following C# code sets the window background color to solid red:
drawingControl.Window.BackgroundColor = (uint) ColorTranslator.ToOle(Color.Red); drawingControl.Window.BackgroundColorGradient = (uint) ColorTranslator.ToOle(Color.Red);
In this example, the ColorTranslator class is used to convert a .NET color type into OLE_COLOR type, which is the how Visio Automation specifies colors.
User Settings for the Visio Control
The Visio drawing control shares the same underlying Application object as the Visio client application. Therefore, if the user changes the application settings for the Visio client application (such as turning the page background blue), the same settings apply to the Visio control when running in the hosting application. The Visio control's HostID property allows you to store different user settings for the control in the registry. To set the HostID property, use a string to indicate the name of the subkey that will be created in the [HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\VisioHosts] key. Although you can use any string for the name of your control's subkey, it's best to use a GUID to ensure uniqueness.
The HostID property can be set at design time in the control Properties window, or programmatically in the host application code.
Page Sizing and Zoom
Use the Visio drawing control's PageSizingBehavior property to resize the page with respect to the control window. The default setting of this property (visNeverResizePages) provides a view similar to that of Visio where a portion of the page is viewable within the window. The following C# code example resizes the page to fit the control:
drawingControl.PageSizingBehavior = Visio.VisPageSizingBehaviors.visResizePages;
When PageSizingBehavior is set to visResizePages, the page's shapes are not resized with respect to the page. Shapes remain located relative to the coordinate system of the Visio page, which has its origin in the lower left corner of the page. Sizing the page to fit within the control hides the page boundaries and is useful in situations where the control is sized to the maximum extent of the drawing surface.
To rescale the entire page, including its shapes, within the drawing control window, set the Zoom property through the control's Window property, as shown in the following C# example:
drawingControl.Window.Zoom = 2.0;
This code magnifies the window's contents by 200%. To take effect, the zoom settings must be made after loading the document using the Src property.
To prevent the user from changing the zoom setting, set the ZoomLock property as shown in the following C# example:
drawingControl.Window.ZoomLock = true;
You can set the extent to which Visio controls the zoom through the VisZoomBehavior property, which can be accessed through the drawing control's Window or Document property. By default, the control uses the current zoom setting for the document. If you want to be able to set the zoom to any level, not just discrete settings such as 50% or 100%, without making any adjustments for the appearance, set the VisZoomBehavior property to the VisZoomVisioExact value, as shown in the following C# example:
drawingControl.Window.ZoomBehavior = Visio.VisZoomBehavior.visZoomVisioExact;
Note You cannot resize the Visio drawing control in a Word document. If you resize the drawing control and save the changes, the control will reset to its default size the next time the Word document is opened.
Shape Search Window Management
You can "turn off" the Visio Shape Search window in the document's stencil pane using the Visio ItemFromID property. To make the Shape Search window invisible in the stencil pane, set the property's Visible property to false, such as:
Windows(1).ItemFromID(Visio.visWinIDShapeSearch).Visible = False
To expose the Shape Search window in the stencil pane, set the same value to True.
Note You can only manage the visibility of the Shape Search window on a per window basis.
Integrating Menus and Toolbars
The best practice when building an application using the Visio drawing control is to implement a custom UI. If you want to display Visio menus and toolbars in your container application, set the drawing control's NegotatiateToolbars and NegotiateMenus properties. The following C# code enables both menu and toolbar merging:
drawingControl.NegotiateMenus = True; drawingControl.NegotiateToolbars = True;
The best practice is to set both of these properties to the same value. The control will not support independent negotiation of toolbars and menus.
The container application must support OLE menu merging in order to display Visio menus or toolbars. For example, you can enable toolbar merging in a Word document. Within the Visual Basic project of the Word document you can programmatically display Visio toolbars. The following example displays the Layout & Routing toolbar.
vsoApplication.CommandBars("Layout & Routing").Visible = True
Important Do not attempt menu and toolbar merging with multiple active instances of the ActiveX control. Multiple instances of the control share a single underlying Visio Application object. You may get unexpected results when trying to do menu merging with a single Application object and multiple active instances of the control.
Important Do not merge menus and toolbars with the Internet Explorer user interface. There are known issues with menu merging in Internet Explorer (see the Microsoft Knowledge Base article 193098, PRB: Unexpected Menu Merging Behavior in Internet Explorer).
Menu and Toolbar Integration for Non-OLE Menu Merging Hosts
If your container does not support OLE menu merging (for example, a Windows Form), you can use the IOleCommandTarget interface to run Visio commands. You can implement your own menu item or toolbar button as demonstrated by the following C# example:
using System.Runtime.InteropServices;
using System;
namespace OleCommandTarget
{
[StructLayout(LayoutKind.Sequential)]
public struct OLECMDTEXT
{
public UInt32 cmdtextf;
public UInt32 cwActual;
public UInt32 cwBuf;
public char rgwz;
}
[StructLayout(LayoutKind.Sequential)]
public struct OLECMD
{
public UInt32 cmdID;
public UInt64 cmdf;
}
[ComImport(), Guid("B722BCCB-4E68-101B-A2BC-00AA00404770"),
InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IOleCommandTarget
{
[PreserveSig()]
int QueryStatus( [In, MarshalAs(UnmanagedType.Struct)] ref Guid
pguidCmdGroup, [MarshalAs(UnmanagedType.U4)] int cCmds,
[In, Out] IntPtr prgCmds, [In, Out] IntPtr pCmdText);
[PreserveSig()]
int Exec(ref Guid pguidCmdGroup, uint nCmdID, uint nCmdExecOpt,
object[] pvaIn, [In, Out, MarshalAs(UnmanagedType.LPArray)]
object[] pvaOut);
}
}
After you have created your menu item, use your IOleCommandTarget interface to apply the appropriate Visio user interface command for that target. The following example enables the Connector tool when a menu item is clicked:
using OleCommandTarget;
private void menuItem_Click(object sender, System.EventArgs eventData)
{
SendCommand();
}
private void SendCommand()
{
const UInt32 VISCMD_DRCONNECTORTOOL =
(UInt32)Visio.VisUICmds.visCmdDRConnectorTool;
IOleCommandTarget commandTarget =
(IOleCommandTarget)axDrawingControl1.GetOcx();
try
{
Guid CLSID_Application = new Guid("{0x00021A20, 0x0000, 0x0000,
{0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}}");
commandTarget.Exec(ref CLSID_Application, VISCMD_DRCONNECTORTOOL,
0, null, null);
}
catch(System.Runtime.InteropServices.COMException ex)
{
MessageBox.Show(ex.ToString());
}
}
Handling Events
For easier use of Visio events, the Visio drawing control object exposes all Visio Window and Document events. This allows developers to access the events directly from the control rather that going through the Visio Document object.
Mouse and keyboard events are commonly used with Visio control programming. You can use mouse events on the Visio drawing control to display custom Windows Forms and update data in your host applications.
If you would like to "lock down" the Visio control's drawing surface and prevent end users from modifying any content directly in the drawing, you can listen for all keyboard and mouse events and "throw them away." If the hosting application "swallows" the mouse and keyboard events, the Visio drawing surface won't respond to the user's typing and mouse-click actions.
Mouse and Keyboard Event Objects
Event objects created by the Visio AddAdvise method offer the best performance. You can use the Visio mouse and keyboard events like any other Visio event with AddAdvise.
The following code sample demonstrates how to capture a mouse event using an event sink in Visual Basic 6.0:
Implements Visio.IVisEventProc
Private Function IVisEventProc_VisEventProc( _
ByVal nEventCode As Integer, _
ByVal pSourceObj As Object, _
ByVal nEventID As Long, _
ByVal nEventSeqNum As Long, _
ByVal pSubjectObj As Object, _
ByVal vMoreInfo As Variant) As Variant
Dim strMessage As String
' Determine if mouse up event fired.
If nEventCode = visEvtCodeMouseUp Then
MsgBox ("MouseUp coordinates (" & pSubjectObj.X & ", " _
& pSubjectObj.Y & ")")
End If
End Function
The following code sample demonstrates how to create an event object for the mouse event using the AddAdvise method.
Private mEventSink As clsEventSink Dim vsoMouseUpEvent As Visio.Event Dim vsoWindowEvents As Visio.EventList Set mEventSink = New clsEventSink Set vsoWindowEvents = DrawingControl1.Window.EventList Set vsoMouseUpEvent = vsoWindowEvents.AddAdvise( _ visEvtCodeMouseUp, mEventSink, "", "Mouse up...")
Delegates for Mouse-Click Events
Although using event objects created with AddAdvise provides the best performance, you can also define a C# delegate in a Windows Form to handle mouse-click events within the drawing control window, as shown here:
this.drawingControl.MouseUpEvent += new AxMicrosoft.Office.Interop.VisOcx.EVisOcx_MouseUpEventHandler( this.drawingControl_MouseUpEvent);
The event handler would then have the following signature:
private void drawingControl_MouseUpEvent( object sender, AxVisOcx.EVisOcx_MouseUpEvent eventData)
Mouse Events for Shapes
Visio mouse events are exposed on Page and Window objects. To locate a particular shape in a page or window on which a user clicks, developers must use the Visio SpatialSearch method. The following C# code passes in the x- and y- coordinates for the click event on the window, sets Visio constants that dictate how to set up the selection object, and defines a small tolerance in which to search around the x- and y- coordinates.
MySelection = Window.SpatialSearch(x, y, visSpatialContainedIn, 0.001, visSpatialFrontToBack)
If the tolerance is set to a very small unit relative to the size of the shape, the selection object returned by the SpatialSearch method will only contain one shape, the one that the end user clicked on in the window.
Deployment
The Visio drawing control is distributed through the Visio product Setup process. Thus there are no additional licensing issues regarding the control itself. An application that hosts the drawing control will not work unless Visio is installed on the computer.
The Visio drawing control is installed as part of the Minimal Install option. If your application is written in managed code and makes use of the Visio primary interop assemblies, you must choose the Typical Install option in order to install the Visio Primary interop assemblies.
First, make sure that the computer has the .NET Framework 1.1 installed; otherwise, the Visio Primary interop assemblies will not be installed. .NET Framework 1.1 is the version that is installed with Visual Studio .NET 2003. For clients running your application, you can also install the free .NET Framework 1.1 Redistributable as part of your application's setup program.
There are a couple options to deploy the Visio control drawing automatically through the Visio product setup:
- Write a Windows Installer setup program and use "silent install" mode for corporate deployment.
- Call the Visio product Windows Installer package (the Visio .msi file) directly.
The following example shows how you can use the Windows Script Host to silently install Visio using the Typical Install option:
Dim WshShell
Set WshShell = CreateObject("WScript.Shell")
WshShell.Exec("setup.exe /qn PIDKEY=<your-key-goes-here> INSTALLLEVEL=20")
To call the Visio product MSI directly, use the following code:
Dim WshShell
Set WshShell = CreateObject("WScript.Shell")
WshShell.Exec("msiexec.exe /qn /i <path_to_the_msi>" & _
"PIDKEY=<your-key-goes-here> INSTALLLEVEL=20")
Conclusion
The Visio drawing control allows developers to extend custom applications and solutions with the rich drawing functionality of Visio. By providing programmability for the control and access to the full Visio object model, the Visio component can be driven by either user drawing actions or events and data in the host application. The advantages of solutions using the Visio drawing control are:
- Custom application users do not require knowledge of the Visio user interface to create drawings. Your application UI can drive drawing creation and abstract away Visio-specific tasks from the user.
- Visio solution developers have a wider range of application hosts and choice of development tools. The Visio drawing control can be hosted inside any ActiveX container. By using the Visio Primary interop assemblies, you can also develop solutions using the Visio drawing control in managed code.
- Providing direct access to the Visio programming model makes solutions using the Visio drawing control simpler to develop and debug than solutions that involve COM add-ins or VSLs.
来源：https://www.cnblogs.com/ant-boss/archive/2007/10/25/937716.html