Volume 3: Programming with the Visio Object Model disclaimer

Lesson 2: Creating an application

Download 0.78 Mb.

Page	33/36
Date	29.01.2017
Size	0.78 Mb.
	#11974

1 ... 28 29 30 31 32 33 34 35 36

Lesson 2: Creating an application

The Office Plan sample provides an example of using the drawing control in a Windows forms application. In this lesson we will explore more properties and features of the drawing control.

Lesson Objectives

After completing this lesson you will be able to:

Identify the features of the Visio drawing control and example use scenarios.
State best practices for using the Visio drawing control in Visio solutions.
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.
Use the properties of the Visio drawing control API.
Load Visio documents into the drawing control window and save changes.
Get a reference to the Visio Application object in order to work programmatically with the Visio document.
Manage the display of the drawing surface.
Integrate the control with your host application user interface.
Deploy the Visio drawing control with your application.

46.Best Practices

Because the Visio drawing control is a programmable component, you can integrate your Visio solution code directly into the host container application. Prior to Visio 2003, 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 Drawing 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.

47.Porting existing code

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.

48.The Controls SDI (single document interface)

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 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 will fail silently. Instead, use mouse events or QUEUEMARKEREVENT as was illustrated in the Office Plan sample program earlier.

49.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

50.Loading a document

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.

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.

Note:

To load a blank drawing into the drawing control when it initializes for the first time, set the Src property to an empty string, but setting the Src property to an empty string after a document has been loaded does not clear the contents of the current document. Instead assign a blank drawing to the Src property or SelectAll and delete to clear the contents from the current document.

51.Saving a document

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.

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.

Note:

Persisting changes in-stream is an unsupported feature of the drawing control, but the technique seems to work reliably.

52.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 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 how Visio Automation specifies colors.

53.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.

54.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.

Each of the other View windows such as Size & Position Window and Shape Data Window are each controlled separately.

55.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).

56.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)

Note:

Examples of using delegates is illustrated in the Office Plan sample from the Visio 2010 SDK.

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.

57.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, 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.

Directory: download
download -> Performance Tuning Guidelines for Windows Server 2008 May 20, 2009 Abstract
download -> Northern England’s set-jetting locations
download -> Bbc archives: Beyond the programme download
download -> Occupational health and safety
download -> Dynatest 3031 lwd light Weight Deflectometer
download -> Forth coming competitive exams
download -> English Olympiad Tasks: 10 th form Аудіювання, 10 клас. Текст
download -> Brush High School Morning Announcements Friday, September 05, 2014 all school
download -> Year 9 The Arts — Music
download -> Years 7 and 8 standard elaborations — Australian Curriculum: Music draft

Download 0.78 Mb.

Share with your friends:

1 ... 28 29 30 31 32 33 34 35 36