Volume 3: Programming with the Visio Object Model disclaimer



Download 0.78 Mb.
Page30/36
Date29.01.2017
Size0.78 Mb.
#11974
1   ...   26   27   28   29   30   31   32   33   ...   36

Lesson 2: Tools


The Visio 2010 SDK comes with a set of tools to aid developers in managing events and publishing solutions. These tools can all be found in the SDK Tools folder. The Event Monitor, Persistent Events tool, and Print ShapeSheet can all be started from the Developer tab in Visio once the SDK is installed. The Solution Publishing tool can be started from the SDK or from the Start menu.
Lesson Objectives

After completing this lesson you will be able to:

  • Use the Event Monitor tool to track events fired in Visio

  • Use the Persistent Events tool to add, edit, or delete persistent events in drawings

  • Use the Print ShapeSheet tool to write the ShapeSheet data to the Clipboard, to a file, or to the printer

  • Use the Publish Components tool to bind stencils, template, drawings, and other files to a Visio solution that you create

37.Event Monitor


The Microsoft® Visio® Event Monitor tool watches for events that are raised in an instance of Visio and logs all events of the types that you specify in the Event Options dialog box. The Event Monitor can help you determine which events to handle in your own solutions.

The Event Monitor uses the AddAdvise method of the EventList collection of the Visio Application object to monitor and report events by the Visio Application object. The Event Monitor reports all events that are sourced by the Application object, except for events that are raised by keystrokes and targeted at an add-on window (the OnKeystrokeMessageForAddon event). For the list of events that the Visio Application object can raise, see the Microsoft Office Visio Automation Reference. (On the Help menu, click Developer Reference.)




Note:

Because the Event Monitor runs in a separate process from Visio, depending on the order in which processes are suspended, the Event Monitor may be suspended before Visio and, hence, may not monitor and report the BeforeSuspend, QueryCancelSuspend, and SuspendCancelled events, even if you include them in the Events to monitor list.

To start the event monitor from Visio choose Developer > Event Montior.

The Event Monitor tool automatically connects to a running instance of Visio, or if Visio isn't already running, the Event Monitor starts a new instance of Visio. When the Event Monitor starts, the log displays the following information:


  • The version of Visio that it has connected to or started

  • The Microsoft Office Visio Type Library version number

  • The process ID of the Visio instance

  • The list of monitored event types and their status; that is, that they are set to be monitored. Event types previously set to be ignored in the Event Options dialog box are not listed at startup.

When all events in the Visio events queue have been processed, Microsoft Visio fires the NoEventsPending event. When Visio has emptied its message queue, Visio fires the VisioIsIdle event. When there has been no activity in Visio for a time, you will see these two events at the bottom of the list in the event window.

When a monitored event fires, the Event Monitor tool displays its name and, depending on the event and your Event Monitor settings, additional data about the event. For example, if you drag a Rectangle shape onto the drawing page, the ShapeAdded event fires. In the log window, the Event Monitor reports the event firing as follows:

21365 | ShapeAdded Rectangle [/doc=1 /page=1 /shape=Sheet.1]

In this log entry:



  • 21365 is the event sequence number, which is determined by the number of events that have fired since Visio was started. Visio gives each event a unique sequence identifier to distinguish between separate firings of the same event, and then passes that number as one of the arguments to the VisEventProc function you write to handle that event.

  • ShapeAdded is the name of the event that fired.

  • Rectangle is the name of the master of the shape that was added.

  • Within the brackets, the Event Monitor tool displays the index number within the Documents collection of the document in which the event fired, the name of the page where the shape was added, and the name of the shape itself. Information within the brackets is displayed only if the Include additional event information box is selected in the Monitor Options dialog box.



38.Demo: Use Event Monitor to track actions in Visio


  1. Start the Event Monitor from Visio. It lists the events being monitored and then lists results for each new event as it fires. Note that there are a lot of MouseMove events every time the cursor moves in the Visio window.

  2. From the Event Monitor choose Tools > Event Options. Remove MouseMove from the list. There are still a lot of events firing when the mouse moves.

  3. Stop monitoring MustFlushScopeBeginning, MustFlushScopeEnding, and NoEventsPending. Now it is easier to see some of the other events that fire when an action occurs in Visio.

  4. Add a shape from a stencil.

  5. Copy and paste a shape.

  6. Duplicate a shape.

  7. Draw a shape using one of the drawing tools.

  8. Note that each of these actions causes a ShapeAdded event, but ShapeAdded doesn’t tell you how a shape was added. How can we distinguish between these actions?

  9. Note that there is always an EnterScope event that occurs for each of these actions and within the EnterScope event we can test the command ID that was just executed. Add a shape from stencil is done with command ID 1246 – Drop on Page. Paste a shape is done with command number 1022. Duplicate is 1024. Control drag duplicate is 1184. Drawing shapes with the drawing tools gives unique commands for each tool used. Therefore it is possible to tell exactly how any shape gets created!

Tip:

This is really handy if you want to do something different for shapes added to a drawing, depending on how they are added. Just be sure to test for performance as EnterScope gets called a lot!




  1. Close Visio. Note the message displayed in the monitor.

Connection to Visio has been terminated.

To restart Visio, click Tools, then click Connect to Visio.


  1. From the Event Monitor choose Tools > Connect to Visio. Visio is restarted and monitoring is resumed.



39.About Using the Persistent Events Tool


The Persistent Events tool provides a user interface that enables you to add and modify persistent events in the active Microsoft® ® Visio® Document object's EventList collection.

By persisting events in a document or template, you can make Visio run add-ons in response to user actions, usually when users create a Visio document based on a template or open a Visio document or template. The Persistent Events tool displays the list of events persisted in the active document or template and for each event, shows the add-on that runs when that event fires and any arguments passed to that add-on.

For more information about persistent events in Visio, see the Microsoft Office Visio Developer Reference (on the Help menu, click Developer Reference).

Many solutions that are a part of the Visio product persist events in their templates. For example, the DocumentCreated event is persisted in the Organization Chart template, and when this event fires, its action is to run the Organization Chart add-on.

You can see evidence of this by opening a new or existing organization chart document (drawing) based on the Organization Chart template and then, after making sure that this document is active, opening the Persistent Events tool. In the tool's list of persistent events for the active document, you'll see a row that contains the following data:

DocumentCreated OrgC11 /cmd=DocCreated

On this line, DocumentCreated is the name of the persistent event that fired, OrgC11 is the universal name for the Organization Chart add-on in Microsoft Visio, and /cmd=DocCreated is the argument passed to the add-on by the event. Whenever a new document is created based on the Organization Chart template, the DocumentCreated event fires, calls the OrgC11 add-on, and passes the argument /cmd=DocCreated to the add-on to indicate that DocumentCreated was the event that fired. For add-ons to run and take the appropriate action, they must know which event fired.

When writing an add-on solution, add persistent events that call your add-on in the Event Properties dialog box (which is accessible from the Persistent Events tool). In the Event Properties dialog box, in the Event box, you can select from the following list of persistable events sourced by the document object:



  1. DocumentCreated

  2. DocumentOpened

  3. MasterAdded

  4. BeforeMasterDelete

  5. PageAdded

  6. BeforePageDelete

  7. ShapesDeleted

The Universal name list box is populated with the names of all add-ons in the Add-ons collection of the Visio Application object. To specify the add-on to run when the event fires, either select it from the list, or, for a new add-on, type its name.

Note:

You must first install the new add-on before persisted events will run it.



Note:

If the add-on's name you type doesn't exist, Visio doesn't display an error message; however, you can use the TraceFlags property of the Application object to view errors in the Immediate window.

Optionally, pass an argument to the add-on. When the event you selected in the Event list fires, the value you enter in the Argument box gets passed to the add-on; you can use it to inform the add-on which event called it. This feature is useful if the add-on needs to handle different events differently. For example, you may want your add-on to respond differently if a new document is created than if an existing document is opened.

You can also use the Persistent Events tool to edit existing persistent events, for example, to change an argument string, or to delete persistent events.


Try it!

  1. Create a new organization chart drawing in Visio.

  2. Start the Persistent Events tool: Developer > Persistent Events. The dialog below is displayed. Note that the DocumentOpened and DocumentCreated events are persisted in the organization chart template.



  1. Add a new persistent event for PageAdded and hook the event to the add-on created in the last section of this module, MyAddon. This add-on displays the command string passed to it. You should see something similar to the dialog below.



Persistent Event information in the Visio object model

Persistent Events can be added, edited, and deleted by using the Visio object model. The Event object has a Persistable property (read-only) and a Persistent property (read-write). Set the Persistent property to True. The Target and TargetArgs properties contain the add-on name and the argument string. The Event property of the Event object contains the event code, e.g., the code for PageAdded is visEvtAdd+visEvtPage.


Note:

There is a known problem that causes an overflow error when working with event codes with values greater than &H8000. To get around the problem pass the event code argument using the hex representation instead of the Visio constants.



Try it!

  1. Open PersistentEvents.vsd from the Samples folder. This drawing was created from an organization chart template so it already has some persistent events in it.

  2. Start the Persistent Events tools and view the existing persistent events.

  3. Run the macro PrintPersistentEvents. This prints the persistent event information from the object model to the Immediate Window. View the code.

  4. Run the macro EditOrAddPersistentEvent. This will edit an existing PageAdded persistent event if it exists or add it if it does not. View the code.

40.Print ShapeSheet


The Microsoft® Visio® Print ShapeSheet tool provides a user interface that lets you print ShapeSheet spreadsheet information for one or more selected shapes, a Visio document, the styles defined in the document, or the current drawing page. You can send the result to the Clipboard, a file, or a printer. You can use the Print ShapeSheet tool to print data from various sections of the ShapeSheet and to search for cell references and dependencies in various formulas.

To start the Print ShapeSheet tool, from Visio choose Developer > Tools > Print ShapeSheet. The Print ShapeSheet dialog is displayed below.




Under Sheet type: choose from: Selected shapes, Document, Styles, Page, and All Shapes. The default choices under Include sections will change depending upon the choice made. Use this section to choose which ShapeSheet sections are to be captured in the output.

Under Send to: choose from File, Clipboard, and Printer.

If there are grouped shapes on the drawing page and you want to print data for individual shapes within groups, select Include group subshapes.

Sample output that was sent to a text file is shown below.



Note that both a cell’s value and it’s formula are included.


41.Publish Component


Beginning with Microsoft Visio 2003, you can publish your add-ons, templates, stencils and other files as components to be integrated with the Visio application. Publishing components is the preferred method of integrating add-ons and other content with Visio. It offers tighter integration with the Visio application, and better performance on add-on discovery.

The publish component functionality enables developers to include a PublishComponent table in the Microsoft Windows Installer file that they create to install content (such as add-ons, templates, stencils, or other files). Each PublishComponent table entry contains information pertaining to how a specific file to be installed should be displayed in the Visio user interface. During installation, these entries are published to the Visio registry. Visio uses this information to display the add-on in its user interface, and install on-demand or repair the file as needed.


Publishing Content





Tip:

The following content is derived from the Visio Insights blog produced by the Visio team at Microsoft. This is a great source of practical “how to” information.

Publishing a piece of content to Visio adds entry points to the user interface side-by-side with content created by Microsoft. For a stencil this translates into a menu entry added to the File > Shapes fly-out menu while for a template this means an entry in Visio’s startup screen (as seen below) and in the File > New fly-out menu.

 

http://officeblogs.net/visio/publish4-080806.png

 

Method #1: Sharing Templates using Path Discovery


The simplest way to publish a template to Visio is to use the Path Discovery method described below:

  1. Copy your template and supporting stencils to a known location on a drive.

  2. Add the location defined in step 1 to Visio’s “Template Paths”; this tells Visio where to find extra content to populate its startup screen.

  3. Restart Visio – your template should appear in the (Other) category.

The advantages of this approach are:

  • It is simple.

  • It is supported across most versions of Visio.

It however has a few drawbacks:

  • Your users may be subjected to potentially long and error prone manual work.

  • Your templates will always end up in the (Other) content category in the startup screen.

  • You don’t have any way of repairing content on a user’s machine if it gets damaged.

  • You cannot control which language of Visio will load your stencils and templates.

  • This approach does not scale well. The Path Discovery publishing method does just that: every time you boot Visio it searches a user’s hard drive for content files – an expensive operation.

Sharing templates through Path Discovery is good for small scale content deployments as well as deployments to older versions of Visio.
Method #2: Sharing using the PublishComponent System

The PublishComponent system introduced in Visio 2003 lets developers use Windows Installer technology for template distribution to register their content with Visio in a rich and robust way. The main advantages of this method are quite interesting:

  • The Windows Installer setup wizard is familiar to users and easy to use.

  • You benefit from Windows Installer repair, install-on-demand and add/remove features.

  • You may choose what language versions of Visio to publish your content to.

  • The approach scales well: Visio only rebuilds its content cache, a moderately expensive operation, when new content is published.

  • The approach is tried and tested since the product publishes its own content this way since the 2003 release.

That said, using the Publish Component system is:

  • A little more complicated than the Path Discovery method.

  • Will only work for Visio 2003 and or later.

To use this method you’ll need Visual Studio .NET or later, the Visio 2003 SDK or later.
Try it!

  1. Create a simple template and stencil that will be added to the published solution. Save the files.

  2. Create a setup project in Visual Studio.

  3. Select the "Application folder" and change its default location property to your target install location. Add your template and their supporting stencils to this location by dragging files into the folders. Your project should look something like the figure below at this point.

http://officeblogs.net/visio/publish2-080806.png

 


  1. Build the project. This will produce an MSI file - a multi-table installation database that is used by windows to coordinate setup.

  2. Install the package as is. Visio will not discover the files the MSI installed.

To notify Visio on the whereabouts of these files, the next thing to do is populate the PublishComponent table of the MSI produced above with registration data. Once installed, this extra information will force Visio to rebuild its content cache and incorporate and display the new templates and stencils.

  1. Start the Solution Publishing Tool that is included with the Visio SDK (a.k.a the publish component tool). This tool may be found in the Start menu entry for the Visio SDK.

  2. On the File menu, select New. It will prompt you for an MSI. Navigate to the one that you've just built.

  3. This will present the Visio Files that are in MSI. You must now, for each entry:

    1. Set the LCID of the language for which you want the templates to be accessible in. Do the same for the supporting stencils.

    2. Set the position in the Visio startup screen hierarchy you want the template to live in. This is defined by separating different levels of the hierarchy by “\” symbols for example: “MyTemplateCategory\MyTemplateSubCategory\MyTemplateName”. Do the same with the supporting stencils, setting their location in the File > Shapes fly-out.

Note:

For VSL files that contain more than one add-on, select the file in the list and click Add Add-on on the Edit menu to specify information about the additional add-ons implemented in the VSL.

To make the changes described above double click on each entry to bring up the “Template Information” dialog seen below, or its counterpart the “Stencil Information” dialog.



http://officeblogs.net/visio/publish3-080806.png 

  1. Press the "!" button in the tools toolbar; this will make modifications to the MSI's Publish Component table.

  2. Install the MSI.

The MSI can now be distributed; Windows Installer and Visio will do the rest. Although we haven’t discussed it here, the same techniques can be used to publish add-ins and help files.





Download 0.78 Mb.

Share with your friends:
1   ...   26   27   28   29   30   31   32   33   ...   36



The database is protected by copyright ©ininet.org 2024
send message
    Main page
implied warranties
content provided