The Visio team is pleased to announce that the online version of the Visio 2010 SDK documentation is now available here. This documentation, which also shipped with the Visio SDK download, is intended to help developers working with the Visio APIs, ShapeSheet and XML. It contains the following Visio developer references.
For Visio Services developers, documentation is available online as well as offline via the Microsoft SharePoint 2010 SDK. This documentation is divided into Visio Services in SharePoint Server overview articles and Visio Services Class Library technical information, and covers the following topics.
As always, we enjoy hearing your feedback about Visio, the Visio SDK and our documentation. Please feel free to post any questions or suggestions to our blog.
If you’ve been reading the blog over the past few months, you’ve seen how excited our team is about Visio 2010. Today we are happy to announce that Visio 2010 (and the rest of Office 2010) is available in retail stores and online today. Thanks to everyone who participated in the Technical Preview program, downloaded the Beta, and gave us feedback through the blog or send-a-smile tool. You can get a free trial of Visio 2010 or Office 2010 and purchase them at www.office.com today!
The Visio Team can answer any questions you have about Visio 2010—just post them in the comments.
The Visio Team recently released the Visio Services 2010 performance and capacity planning white paper. This white paper addresses the impact of SharePoint farm topology on Visio Services. It also explores how various service settings can affect latency and throughput. The white paper examines both typical and high stress conditions, which should help you better scale your deployments based on the number of users you need to support and their expected usage.
As usual, please comment on the blog if you have any questions or comments to share.
As part of the SharePoint SDK, the Visio team has published more documentation about creating Custom Data Providers. As you may recall, Visio drawings can connect to a variety of data sources, including Microsoft Excel files, SharePoint lists, SQL databases, and any other ODBC-compatible data source. In you want to connect to a different data source, you can create a custom data provider. With a few lines of code, your custom data provider can connect to data from a variety of data sources such as XML files, Web services, OLAP cubes etc…
This white paper outlines all the steps required to create, configure and install a custom data provider. The complete object model reference of custom data providers is also available.
We enjoy seeing the innovative solutions that are implemented on the Visio platform. Now, with Visio 2010 and Visio Services, we’re starting to see some great new solutions that weren’t possible before. A good example is the Visio 2010 add-in for System Center Operations Manager 2007 R2. This add-in, which was originally released for Visio 2007, lets you generate a data-linked Visio diagram from Microsoft System Center Operations Manager. Visio’s data graphics are used to show the health of applications, services, and infrastructure monitored by Operations Manager. For instance, the status of a database server can be shown with an icon on the shape or by changing the shape’s color.
The diagram can be customized in Visio to show the information in a variety of contexts, such as a network topology, datacenter floor plan, rack diagram, or map.
The latest version of the add-in has been updated to work with Visio 2010 and allows the diagram to be viewed in SharePoint using Visio Services. The diagram remains connected to the Operations Manager data, and the data graphics will update as status changes occur. In this way, it can be used as a live dashboard that is viewable in a browser without requiring the Visio client.
In short, this add-in demonstrates how Visio Services opens up new scenarios for visualizing real-time data in the browser and how Visio developers and partners can build powerful new solutions that take advantage of Visio Services.
Please continue to let us know what you think and comment on our blog!
Earlier this morning, Stephen Elop, President of Microsoft’s Business Division formally kicked off the launch of Office 2010, SharePoint 2010, Visio 2010, and Project 2010. The virtual launch event showed off a bunch of demos, customer testimonials, and interviews with Microsoft product managers. You can still see the virtual launch events over at http://www.the2010event.com.
Visio 2010 and the rest of the Office products are now available to all of our business customers, and we’re very excited to reach this milestone. If you’re not a business customer, the Office suite of products will show up in retail stores in June.
With the virtual launch event today, we’re making ourselves available for questions about Visio 2010. If you have any questions about Visio, post a comment on this post, or send us a question through Twitter @msvisio . You can also use the contact form here to send us your questions. Check out the videos below highlighting the Visio 2010 launch:
Over the past 10 months, we’ve highlighted all the areas of innovation in Visio 2010. In fact, the Visio 2010 Beta has had over 500,000 downloads! Thank you to everyone who provided feedback through this blog and the Send-A-Smile tool. We’ve heard some great things from our beta users: 92% of surveyed Beta users feel that Visio 2010 is an improvement over previous versions. 84% would recommend the Visio 2010 Beta to a friend or colleague.
If you haven’t tried the Visio 2010 Beta yet, it’s still available for download. In June, the RTM version of the Visio 2010 Premium Trial will be available for download as well.
We hope to continue to hear your feedback as you try out our final release and continue to use the Beta.
For more information about Visio 2010, customer case studies, and a ton of other Visio resources, be sure to check out Visio Tool Box.
Along with the Visio 2010 Release to Manufacturing, we are also pleased to announce that the Visio 2010 SDK and Visio 2010 Viewer are now available for download.
The Microsoft Visio 2010 Software Development Kit (SDK) contains developer documentation, sample applications, and other tools to help developers create custom solutions for Visio 2010. Since the release of the Visio Beta SDK, we have made a number of improvements to the SDK: most notably, we have updated the documentation in the SDK and included a new sample application based on Microsoft Office development tools in Microsoft Visual Studio 2010. The Visio SDK Documentation and the Visio Code Samples Library now both contain updated 2010 content. The latter includes sample code for Fluent UI (a.k.a. Ribbon) extensibility, diagram validation, container membership, diagram creation and traversal using the Connectivity API, and saving to Visio Services.
The new sample application was added to the Visio SDK due to popular demand: developers wanted an example of deploying a VSTO add-in using ClickOnce installation. Our new sample demonstrates how to use new Visual Studio 2010 functionality to install Visio template and stencil files, as part of a Visio add-in deployment, using a "ClickOnce" post-deployment action. After installation, the custom template associated with the add-in is displayed in the Office BackStage View and the add-in is triggered when a new diagram is created from the template. The add-in itself simply drops a shape from a custom stencil onto the drawing page when it is triggered. This basic example can be used by developers to create more complex VSTO add-ins based on their own requirements.
Microsoft Visio 2010 Viewer allows anyone to view Visio diagrams (.vsd, .vss, .vst, .vdx, .vsx and .vtx files created with Visio 5.0 through Visio 2010) inside their Microsoft Internet Explorer (versions 5 through 8) Web browser. By using Microsoft Visio 2010 Viewer, Visio users can freely distribute Visio drawings and diagrams to team members, partners, customers, or others, even if the recipients do not have Visio installed on their computers. Internet Explorer also allows recipients to print the portion of the Visio drawing displayed in the browser window. Visio Viewer is implemented as an ActiveX control that loads and renders Visio drawings inside Internet Explorer.
We are very excited to release these two free Visio downloads to make it easier to develop Visio solutions and view Visio diagrams. Please continue to let us know what you think and comment on our blog!
As mentioned in the last post, Visio 2010 has reached the Release to Manufacturing milestone. The product team has spent the last several months incorporating your feedback from the Beta and refining the product. A large community of customers, partners, and MVPs has contributed to this effort. More than 500,000 people have downloaded the Visio 2010 Beta release, and the feedback has been very positive. People have commented on the blog, sent e-mail, submitted Send-A-Smile reports, logged crash reports, and contacted Product Support to provide feedback on the product.
This post describes some of the more visible changes you will find between Beta and RTM. Overall very little is different in the user interface for RTM. The bulk of the work has been targeted at improving reliability (fixing bugs), performance, and security.
Quite a few people commented on the reduced set of drawing tools on the Home tab as compared with the Drawing Tools toolbar in previous releases. Users of the Beta did not know or did not want to go to the Developer tab for the complete set of tools. You can find all six tools on the Home tab for RTM.
At the bottom of the Fill and Shadow dropdown menus in the Home tab are commands to open a formatting dialog for more properties. A similar command is missing for the Line dropdown menu in the Beta. This command has been added for RTM for better consistency across the formatting features.
There are a number of small changes in the Backstage view to make saving files to SharePoint more understandable. First the name of the tab for publishing and sharing files has changed from “Share” to “Save & Send”. Then in the Save to SharePoint place, the option for selecting whether to publish as a Drawing (*.vsd) or Web Drawing (*.vdw) has changed from “Save Drawing As” to “File Types”. Finally the command button has changed from “Save to SharePoint” to “Save As”. The intent is to use familiar terms to describe the actions for saving a document. Also “Save As” makes it clearer that the command will present the Save As dialog to confirm all the settings before saving.
If you apply formatting to a shape (e.g., fill color or pattern) and then copy it to a different page in a themed document, the formatting will be preserved as long as the theme on the destination page is the same as on the source page.
RibbonX is the extensibility framework for the Office Fluent UI. RibbonX provides customization of the Ribbon, the Backstage view, and context menus. Visio 2010 Beta did not support context menu customization, but support has been added for RTM for most of Visio’s context menus. More information on RibbonX extensibility in Office 2010 is available in this blog post.
These are the more visible changes for Visio 2010 RTM from the Beta. There are many more improvements behind the scenes to make Visio 2010 a fast, secure, and reliable release. Thank you for all the Beta feedback. We hope you will try out the final version of Visio 2010 as it becomes available in the coming weeks. Please continue to let us know what you think or want to hear more about.
Today Microsoft announced that Microsoft Office 2010, SharePoint Server 2010, Project 2010 and Visio 2010 have released to manufacturing! As noted last month, Visio 2010 and the rest of the other Office 2010 products will be available to businesses worldwide on May 12th and to consumers online and on retail shelves this June. Many thanks to everyone who provided product feedback on our blog and through our Send a Smile tool in our Visio 2010 Beta. Your feedback has helped us ensure a high quality product as well as provided us feature input for future consideration. We hope to continue hearing from you after you install our final release.
Over the last nine months, we have had an opportunity to cover the features of Visio 2010 over nearly 60 postings with information for users, shapes developers, IT professionals and developers. If you have recently started reading our blog or if you just want an easy reference to what we’ve already covered, below is a summary of the articles we’ve posted to date, organized by our main areas of investment for this release.
Office Fluent User Interface
Visio Application Enhancements
Diagramming Improvements
Technical Reference
Flowcharting
Structured Diagrams
SharePoint Server 2010 Integration
Diagram Publishing, Rendering and Data Refresh
As always, please continue to let us know what you think or want to hear more about.
As we get ready for next month’s launch of Visio® 2010, we’re ready to announce that Visio 2010 will be available in three different editions. This post explains the differences between the three editions (and also gives you a sneak peak of what our boxes will look like!)
Visio 2007 users will note the introduction of the new edition, Visio Premium 2010. Visio Premium 2010 is our highest offering. If you’re using the Visio 2010 Technical Preview or the Visio 2010 Beta right now, you’re using the “Premium” edition.
Many of the improvements and new features we’ve added to Visio 2010 are available across all editions, but Professional and Premium contain some additional functionality:
The main functionality differences between the three editions are summarized in the table below:
And too many more to list!
As usual, please comment on the blog if you have any questions about the differences between Visio 2010 editions.
Edited on 9/14/2010: Removed "Publish to Process Repository" from the "Advanced Process Management Features" row. This feature is available in all editions.
Some of the earliest adopters of Visio were engineers and others who created technical drawings, and they loved the combination of power and simplicity that Visio provides. One of the most ubiquitous applications used by engineers is Autodesk’s AutoCAD, and Visio supports AutoCAD files by providing basic CAD integration features for import, conversion, and export.
While we made significant CAD improvements in Visio 2007, we did not provide support for newer AutoCAD file formats. This meant that Visio 2007 users required saving their CAD files in older formats in order to open them in Visio.
Now in Visio 2010, we’ve addressed this issue by adding the ability to read the latest AutoCAD file formats while providing the same CAD functionality as Visio 2007.
To learn about Visio CAD support, we recommend reading our past blog posts about Visio 2007 linked below:
Please comment on the blog to let us know what you think.
Last week on the Office Engineering Blog, Microsoft confirmed the release dates for Visio 2010, Office 2010, SharePoint 2010, and Project 2010.
We’re happy to announce that Visio 2010 and the rest of the Office suite will release to manufacturing (RTM) next month.
Consumers who purchase and activate Office 2007 or Visio 2007 will be able to download corresponding Office 2010 or Visio 2010 products at no additional cost when they become available in June 2010.
All you need to be eligible for this program – Office 2010 Technology Guarantee – is the following:
For more information about the Office 2010 Technology Guarantee, and to sign up for an e-mail reminder when Office 2010 is available, visit www.office.com/techg.
As always, let us know in the comments if you have any questions or topics you’d like to see us discuss here in the future.
In previous posts we've introduced Visio Services and shown you how you can publish your Visio diagrams to SharePoint. We've also given you a quick introduction on how to install and configure Visio Services. In this post, we'll cover more details for IT Administrators about running Visio Services in SharePoint 2010. This post contains lots of links to detailed documentation on TechNet as well as other blog posts.
Visio Services is implemented as a service application in SharePoint Server 2010. The service allows users to share and view Microsoft Visio Web drawings (*.vdw files). The service also enables viewing of data-connected web drawings, and the underlying data and drawing can be updated from various data sources. Drawings can be embedded in SharePoint pages using the Visio Web Access web part.
There are several ways in which you can build on top of Visio diagrams with Visio Services:
Because Visio Services is implemented as a service application, managing the service is simple through both SharePoint Central Administration and Windows PowerShell.
For detailed information about common administrative tasks, see the Visio Services Operations Guide.
Visio Services maintains a few performance and caching settings, as well as a list of trusted data providers. For more details, see this article that explains the various service settings.
Visio Services supports connecting to various data sources. Administrators need to understand how their organizations will use data with Visio Services and plan appropriately. The Visio Services Planning Guide will help you understand the implications of data connected web drawings.
By default, Visio Services supports connecting to the following data sources:
Administrators have the ability to control what data sources the service is allowed to connect to by managing the Trusted Data Providers.
Connecting a web drawing to SharePoint lists and Excel Services does not require any additional configuration.
To connect web drawings to external data sources (like SQL or an OLEDB data source), the administrator must setup an unattended service account with the Secure Store Service. The unattended account is a low-privilege domain account that is used by Visio Services when connecting to external data sources. The credentials for this account must be stored in a Secure Store target application, and Visio Services must know the name of this target application. For more information about the unattended account and the security implications of connecting to external data, and other authentication methods, see this article on Visio Services security.
Visio Services gives administrators a significant level of fine-grained control for the processing and displaying of Visio Web Drawings and what data sources they can connect to. This article on planning Visio Services security details the security implications that you should consider when deploying Visio Services.
The following is a list of resources that are available on TechNet for administrators planning to deploy Visio Services:
The following is a list of posts on this blog that contain more information about Visio Services:
We hope this overview and set of links will make it easy for IT administrators to deploy and use Visio Services. Let us know what you think by commenting on the blog or using Send a Smile.
When we talk to developers to get their feedback on the Visio development platform, a common request we hear is the ability, through the API, to control the settings used when exporting a diagram as a raster image in the PNG, JPG, BMP, or TIFF format. Typically, they want to automate the export of the pages in a document as images for use in a web page or other application that requires certain settings. In this post, we’ll talk about the additions to the Visio 2010 object model that let developers configure each of these raster export settings.
When you save a diagram in one of the raster formats, a dialog box appears to let you configure various settings, such as the color format, resolution, or size of the image. For example, this is the dialog for the PNG format:
Until now, there hasn’t been a way to automate the settings in this dialog via the API. In Visio 2010, we’ve enhanced the object model to make it possible to drive these settings programmatically using a set of new methods and properties on the ApplicationSettings object. You can use the methods to get and set the raster-export resolution and size, and you can use the properties to get and set raster export attributes such as data format, data compression, color reduction, color format, background color, transparency, and quality. You can use these methods and properties with the existing Page.Export and Selection.Export methods to export a diagram in a raster file format.
Here is the complete list of new raster export methods and properties on ApplicationSettings:
Name
Description
GetRasterExportResolution
Returns the raster export resolution settings.
GetRasterExportSize
Gets the raster export size.
SetRasterExportResolution
Specifies the raster export resolution settings.
SetRasterExportSize
Sets the raster export size.
RasterExportBackgroundColor
Determines the background color that is applied to the exported image.
RasterExportColorFormat
Determines the color format that is applied to the exported image.
RasterExportColorReduction
Determines the color reduction that is applied to the exported image.
RasterExportDataCompression
Determines the data compression algorithm that is applied to the exported image (BMP, TIFF).
RasterExportDataFormat
Determines whether the exported image is interlaced or non-interlaced (PNG, GIF).
RasterExportFlip
Determines the flip that is applied to the exported image.
RasterExportOperation
Determines the export operation that is applied to the exported image (JPG only).
RasterExportQuality
Determines the export quality that is applied to the exported image (JPG only).
RasterExportRotation
Determines the rotation that is applied to the exported image.
RasterExportTransparencyColor
Determines the transparency color that is applied to the exported image (PNG, GIF).
RasterExportUseTransparencyColor
Determines whether Visio applies, to the exported image, the transparency color that is specified in the RasterExportTransparencyColor property (PNG, GIF).
For more details on these methods and properties, such as their parameters and constants, see the Visio Developer Reference in the Visio 2010 Beta.
This VBA code executes the settings in the PNG Output Options dialog box as shown above and exports the diagram as a PNG:
'Set the export resolution to the printer resolution at 600 x 600 pixels/inch Application.Settings.SetRasterExportResolution visRasterUsePrinterResolution, 600#, 600#, visRasterPixelsPerInch 'Set the export size to custom 8 x 5 inches Application.Settings.SetRasterExportSize visRasterFitToCustomSize, 8#, 5#, visRasterInch 'Set the data format to Interlace Application.Settings.RasterExportDataFormat = visRasterInterlace 'Set the color format to 24-bit color Application.Settings.RasterExportColorFormat = visRaster24Bit 'Rotate the image to the left Application.Settings.RasterExportRotation = visRasterRotateLeft 'Don’t flip the image Application.Settings.RasterExportFlip = visRasterNoFlip 'Set the background color Application.Settings.RasterExportBackgroundColor = 14798527 'Set the transparency color Application.Settings.RasterExportTransparencyColor = 13269045 'Use the transparency color Application.Settings.RasterExportUseTransparencyColor = True 'Export the active page as a PNG to the specified path Application.ActiveWindow.Page.Export "<drive>:\<path>\Network Diagram.png"
'Set the export resolution to the printer resolution at 600 x 600 pixels/inch Application.Settings.SetRasterExportResolution visRasterUsePrinterResolution, 600#, 600#, visRasterPixelsPerInch
'Set the export size to custom 8 x 5 inches Application.Settings.SetRasterExportSize visRasterFitToCustomSize, 8#, 5#, visRasterInch
'Set the data format to Interlace Application.Settings.RasterExportDataFormat = visRasterInterlace
'Set the color format to 24-bit color Application.Settings.RasterExportColorFormat = visRaster24Bit
'Rotate the image to the left Application.Settings.RasterExportRotation = visRasterRotateLeft
'Don’t flip the image Application.Settings.RasterExportFlip = visRasterNoFlip
'Set the background color Application.Settings.RasterExportBackgroundColor = 14798527
'Set the transparency color Application.Settings.RasterExportTransparencyColor = 13269045
'Use the transparency color Application.Settings.RasterExportUseTransparencyColor = True
'Export the active page as a PNG to the specified path Application.ActiveWindow.Page.Export "<drive>:\<path>\Network Diagram.png"
We hope these additions to the API for raster export open up some new possibilities for Visio developers, or at least make it easier and more efficient to build automated solutions. Let us know what you think by commenting on the blog or using Send a Smile.
When Office 2007 was introduced, a new UI paradigm was adopted, and so was a new UI extensibility model, the RibbonX (Ribbon extensibility) model. RibbonX is a XML markup that allows developers to customize the Office UI. It enables 3rd party developers and solution providers to build custom tabs and groups on top of the Ribbon, and target scenarios unique to and optimized for their customers. As Visio 2010 adopts the Fluent UI, Visio developers now also have the opportunity to utilize this platform to build and customize Fluent UI to offer users a more discoverable and instructive UI experience.
Existing Visio Solutions
There are two existing mechanisms for UI extensibility in Visio: CommandBar and UIObject. Both would still work in Visio 2010: Visio 2010 automatically creates a new tab called “Add-Ins” with groups for these existing menu commands and toolbar commands and requires no extra work from developers. Here, as an example, we see a top-level menu item called Process Analysis.
In the Ribbon, this menu becomes a drop-down control that opens to show the menu commands. This automatically-generated tab and its controls require zero-effort for your solutions to migrate to the next release of Visio.
Although the migration to ribbon can be zero-effort, this really is an ideal opportunity for solution developers to re-think their UI from a Ribbon perspective. The Ribbon provides contextually-relevant commands, and presents them in a way that is more results-oriented. Your UI can integrate more seamlessly with the rest of Visio, and look more like Office. Here is an example of how Visio 2010 reconfigured the Gantt Chart UI, allowing users to more easily discover commands and learn about them through controls of varying sizes, big icons and super tooltips:
Note, if you are using UIObject in your solution, we especially recommend upgrading to the ribbon. UIObject is a legacy Visio-specific model for defining UI and it may become deprecated in the future.
RibbonX for Different Types of Add-in Technologies
Depending on what add-in technology you were using, Visio provides a number of ways to import Fluent UI controls through RibbonX and improve users’ experience. Here is how you achieve that for each type of add-in technology.
If you’re developing a Visual Studio Tools for Office (VSTO) add-in, you will have access to a visual Ribbon designer that provides a graphical construction environment, similar to other Visual Studio designers. Alternatively, you can specify your UI using RibbonX. Your add-in merely provides an override called CreateRibbonExtensibilityObject that returns an instance of your ribbon object. One-line, very simple to do.
If you’re writing a shared COM add-in, in your Connect class (the class that implements IDTExtensibility), define an override called GetCustomUI that returns your RibbonX XML as a string. GetCustomUI is the single interface through which the Fluent UI communicates with a COM add-in. Two-to-three lines, still very simple to do.
VSLs, or legacy Visio add-ons, may also use RibbonX. You add the RibbonX XML to your add-on’s resources. Your add-on defines the GetCustomUI callback and notifies the Visio Application that it has RibbonX XML by calling RegisterRibbonX.
For VBA, you simply provide the contents of a RibbonX XML as a string directly to Visio through the CustomUI property.
RibbonX and Visio XML file format
The Visio XML file format (*.vdx) may also contain RibbonX. The RibbonX markup is stored inside a new element in the Visio XML schema, called, unsurprisingly, RibbonX. The customUI element is the top-level wrapper element in the RibbonX schema.
Since you can define custom UI directly in the Visio XML file, you have all the benefits of being able to read and write the file without Visio being present. For example, this enables an entire class of server-side scenarios where the server can not only manipulate diagram content, but can also make changes to custom UI in the document.
Developing with Visual Studio 2010
The recommended Visual Studio version to develop for Visio 2010 is Visual Studio 2010, which is currently available as Release Candidate. Visual Studio 2010 offers a friendly design environment with the Ribbon Designer, where developers can easily drag and drop ribbon groups and controls onto a graphical design canvas. Also, a Visio 2010 VSTO template is available for you to easily create a Visio add-in project. Multi-project deployment packages, post-deployment actions, and removing PIA dependencies are all benefits from using VS 2010. For more information on what’s new in VS 2010, see this MSDN article.
Conclusion
With Visio 2010 and the UI extensibility model available, you now have the opportunity to utilize our more intuitive attractive drawing surface to broaden your user base. We highly recommend moving existing solutions to the Fluent UI. It is worth the work to get rid of the old menu bars, and help your users realize the full capability of your solution by making it easier to use. For new and old solution developers alike, Visual Studio 2010 allows a great way to easily develop Fluent UI for Visio 2010 as well.
To get more details about UI extensibility for Office 2010 applications, here are some helpful links:
Microsoft Office 2010 Engineering blog
UI Extensibility in Office 2010- Including details on customizing Office Menu and Backstage View
MSDN documentation
Office Development in Visual Studio 2010 How to setup the Ribbon Visual Designer Ribbon best practices
Office Development in Visual Studio 2010
How to setup the Ribbon Visual Designer
Ribbon best practices
Do try implementing your own Visio ribbon and send us feedback through the Send a Smile feedback tool or comment on this post!
Last week, we took a look at how to create interactive mashups with Visio diagrams without writing any code. If you need more flexibility in creating rich diagram mashups than offered out of the box by web part connections, you can use the Visio Services JavaScript Mashup API.
In this post we'll review the breadth of possibilities by the Visio Services Mashup API and show you how to get started coding with a few simple examples.
In a nutshell, the Visio Services JavaScript Mashup API enables developers to access and manipulate the Visio web drawing, its pages and shapes. Some key scenarios enabled by the Mashup API are:
The class diagram below summarizes the available objects in the API. Notice that related class members are collected into functional groups – each group is discussed in more detail in the API in the appendix of this article.
Like many JavaScript APIs, it's important to note that the Visio Services JavaScript API is event-based. To program against the Visio Web Access web part, you must catch the events it exposes by writing event handler functions. The diagram below is the state chart of VwaControl events:
Typically, when the onApplicationLoad event fires you'll want to get a reference to the vwaControl object and set-up handlers for ondiagramcomplete. Note that vwaControl is the only valid object in the object model until ondiagramcomplete fires. Then, when the ondiagramcomplete event fires you'll want to get a reference to the currently loaded page and set-up handlers for the various mouse events.
Now that you understand the object and event model of the API, let's get started coding. Before you can interact programmatically with a Visio Web drawing you must add a Visio Web Access web part to a web part page, load a VDW file into it and add a Content Editor Web part to the page to contain your JavaScript.
To do so, assuming you have "Contribute", "Design" or "Full Control" permissions to a page in SharePoint Server 2010, you should:
1: <script language="javascript">
2: // A hook into AJAX's Sys.Application.load event, raised after all scripts
3: // have been loaded and the objects in the application have been created
4: // and initialized.
5: Sys.Application.add_load(onApplicationLoad)
6:
7: // Global variables for the application
8: var webPartElementID = "WebPartWPQ3"; //Change this to the appropriate web part ID.
9: var vwaControl;
10: var vwaPage;
11: var vwaShapes;
12:
13: // Function Name: onApplicationLoad()
14: // Parameters: None
15: // Description: This function handles the AJAX's Sys.Application.load event
16: // When this event fires the function captures references to
17: // the Visio Web Access web part object and registers
18: // the following Visio Web Access specific event handlers:
19: //
20: // 1. diagramcomplete: raised when the request for a web
21: // drawing page finishes.
22: function onApplicationLoad() {
23: try{
24: vwaControl= new Vwa.VwaControl(webPartElementID)
25: vwaControl.addHandler("diagramcomplete", onDiagramComplete);
26: }
27: catch(err){
28: }
29: }
30:
31: // Function Name: onDiagramComplete
32: // Parameters: None
33: // Description: This function handles the onDiagramComplete event which is
34: // raised when a request for a web drawing page completes.
35: // When the event fires, this function captures references
36: // to script's global variables such as the current page, the
37: // collection of shapes on the page. It also sets the page zoom to
38: // "fit page to view" to give a full view of the page to
39: // users and registers the following Visio Web Access specific
40: // event handlers:
41: //
42: // 1. shapemouseleave: raised when the mouse enters a shape.
43: //
44: // 2. shapemouseenter: raised when the mouse leaves a shape.
45: //
46: // 3. shapeselectionchanged: raised when the active selection
47: // is changed from one shape
48: // to another.
49: function onDiagramComplete() {
50: try {
51: vwaPage = vwaControl.getActivePage();
52: vwaPage.setZoom(-1);
53: vwaShapes = vwaPage.getShapes();
54: vwaControl.addHandler(“shapeselectionchanged”, onShapeSelectionChanged);
55: vwaControl.addHandler(“shapemouseenter” , onShapeMouseEnter);
56: vwaControl.addHandler(“shapemouseleave”, onShapeMouseLeave);
57: }
58: catch(err) {
59: }
60: }
61:
62: // Put the sample code discussed later in the blog below...
63: </script>
Tada! You have the basics of a mash-up. That said, it doesn't do much except get references to a few basic objects and setup some event handlers. The next section gives you a few useful examples that build on this base.
In this example we will explore how to create an overlay that appears when a user hovers over a shape. In this scenario, the manager of a grocery store visualizes sales data on a floor plan of his store: sales figures are represented as colors on a store shelf. Now, let’s say we want to show a picture of the best-selling product of the day on each shelf as a user hovers his mouse over a shelf. This product changes daily and is calculated at night by running database queries; this data is then exposed through shape data when the drawing is refreshed.
To solve this problem, you'll want to draw an overlay on the shape when the mouse enters the shape, and remove the overlay when the mouse leaves the shape. Let's take a look at one possible implementation:
1: // Function Name: shapeMouseEnter
2: // Parameters:
3: // source -- a reference to the base HTML element of the vwaControl.
4: // args -- the shape ID of the shape the mouse entered.
5: // Description:
6: // On entering a shelf shape (a shape that contains a "Best Seller" shape
7: // data), this function extracts that shape data then overlays the
8: // corresponding image on the shape.
9: shapeMouseEnter = function(source, args)
10: {
11: //Get the name of the shape that was just entered
12: var shape = vwaShapes.getItemById(args);
13:
14: //Determine the best seller for that shelf. This information is stored in a shape data //named “Best Seller” item that updates over time.
15: var bestSeller;
16: var shapeData = shape.getShapeData();
17: for (var j=0; j<shapeData.length; j++) {
18: if (shapeData[j].label = "Best Seller") {
19: bestSeller = shapeData[j].value;
20: }
21: }
22:
23: //Depending on which shape this is, draw the correct overlay.
24: switch(bestSeller)
25: {
26: case "productA":
27: shape.addOverlay(
28: "myOverlay" ,
29: "<Image Source=\"productA.jpg\" Width=\"50\" Height=\"70\"><\/Image>",
30: vwaVerticalAlignment.Top,
31: vwaHorizontalAlignment.Left,
32: shape.getBounds().width,
33: shape.getBounds().height);
34: break;
35:
36: //If the best seller is product B, then display an overlay with product B.
37: case "productB":
38: shape.addOverlay(
39: "myOverlay" ,
40: "<Image Source=\"productB.jpg\" Width=\"50\" Height=\"70\"><\/Image>",
41: vwaVerticalAlignment.Top,
42: vwaHorizontalAlignment.Left,
43: shape.getBounds().width,
44: shape.getBounds().height);
45: break;
46:
47: //You can add more cases below as needed for different shelves.
48:
49: default:
50: }
51: }
52:
53: // Function Name: shapeMouseLeave
54: // Parameters:
55: // source -- a reference to the base HTML element of the vwaControl.
56: // args -- the shape ID of the shape the mouse just left.
57: // Description:
58: // On leaving a shelf shape (a shape that contains a "Best Seller" shape
59: // data), this function removes the existing overlay on that shape.
60: shapeMouseLeave = function(source, args)
61: {
62: //Get the name of the shape that was just entered
63: var shape = vwaShapes.getItemById(args)
64:
65: //And remove the overlay
66: shape.removeOverlay("myOverlay");
67: }
To add this to your solution, copy/paste the above code presented in the earlier “Getting Started”. Note that this code makes the following assumptions:
In this second example, the scenario is a network diagram mashup that allows a network administrator to find computers in a network diagram that have a particular string and to highlight them; this is useful when looking at a computer topology to quickly spot computers that meet a particular spec, or contain a particular set of characters in their name. We are effectively “scraping” the diagram to find shapes that contain a particular piece of text in either shape text or shape data.
To solve this problem, the algorithm iterates through all the shapes on the page and does a string compare against the name/shape data of that shape and highlight the shapes that contain that string. One implementation of this scenario is detailed below:
1: // Creates the user interface for this code sample which consists of a
2: // text box to enter the find-text and a button to trigger the
3: // find operation.
4: document.write("Find text:");
5: document.write("<BR><input type=\"text\" id=\"findText\"><\/input>");
6: document.write("<BR><Button id=\"findButton\" type=\"button\""+
7: "onClick=\"find()\">Find<\/Button>");
8:
9: // Function Name: find
10: // Parameters: None
11: // Description: This function iterates through vwaShapes and highlights
12: // the shapes who's name, shape data or shape hyperlinks
13: // contains the find-text. The search is case insensitive.
14: function find() {
15: // Iterate through the collection of shapes on the page, if either the
16: // shape name, shape data or shape hyperlinks contain the find-text,
17: // highlight it and jump back to the "shapeContainsFindText:" label
18: // to process the next shape.
19:
20: shapeContainsFindText:
21: for (var i=0; i<vwaShapes.getCount(); i++) {
22: // Extract the find-text from the text box and covert it to lower case.
23: var findText = document.getElementById('findText').value.toLowerCase();
24:
25: // Get a reference to the shape at index "i" of the shape collection
26: // and remove existing highlights.
27: var shape = vwaShapes.getItemAtIndex(i);
28: shape.removeHighlight();
29:
30: // Get a reference to the shape name, shape data and shape hyperlinks
31: // collections.
32: var shapeName = shape.getName();
33: var shapeData = shape.getShapeData();
34: var shapeHyperlinks = shape.getHyperlinks();
36: // Highlight the shape if the find text is found within the shape name
37: // and return to the top of the loop to process the next shape.
38: if(shapeName.toLowerCase().indexOf(findText) != -1) {
39: shape.addHighlight(2,"#00FF00");
40: continue shapeContainsFindText;
41: }
42:
43: // If the shape name did not contain the find-text, search through the
44: // the shape's shape data values for the find-text. If the find-text
45: // is found highlight the shape and return to the top of the loop to
46: // process the next shape.
47: for (var j=0; j<shapeData.length; j++) {
48: if (shapeData[j].value.toLowerCase().indexOf(findText) !=-1) {
49: shape.addHighlight(2,"#00FF00");
50: continue shapeContainsFindText;
52: }
53:
54: // If the shape name or shape data did not contain the find-text,
55: // search through the shape's hyperlinks for the find-text. If the
56: // find-text is found, highlight the shape and return to the top of
57: // the loop to process the next shape.
58: for (var j=0; j<shapeHyperlinks.length; j++) {
59: if (shapeHyperLinks[j].value.toLowerCase().indexOf(findText) !=-1) {
60: shape.addHighlight(2,"#00FF00");
61: continue shapeContainsFindText;
62: }
63: }
65: // If the text hasn't been found in the web drawing, then warn the user.
66: alert("Text not found in this web drawing!");
68: }
To add this to your solution, copy/paste the above code presented in the earlier “Getting Started” section. Note that using the code above, the find text box and button will appear in the place of the Content Editor web part.
For our third example, we’d like to highlight an in-house use of the Visio Services JavaScript OM, namely the new SharePoint workflow visualization feature in SharePoint 2010. In a nutshell, using this feature, you can now create a workflow using Visio/SharePoint Designer and visualize the progress of an instance of that workflow in SharePoint.
The progress visualization is in fact an example of using the Visio mash-up to overlay data on an existing diagram. The SharePoint workflow team used the JavaScript API to overlay workflow instance data in the context of the workflow diagram. Taking a look at the picture below, all the visuals and the text highlighted in the green box are not actually part of the published diagram but are actually drawn over the workflow shape at run-time using the mash-up API. As the data changes during the lifetime of a workflow, so will the overlay.
As you can see, the integration between the Visio published diagram and the overlays is pretty seamless!
We’re in the process of developing a full MSDN reference for the JavaScript Mashup API, including samples and an overview document. We’ll make sure to announce this on the blog when it’s made publicly available. Please note that the contents of this blog entry are preliminary and may change by the time Visio Services 2010 is officially released.
We hope this blog post has given you enough to get started building your own JavaScript solutions. Feel free to share your thoughts either through send-a-smile or by commenting on this blog post.
Object
Vwa.VwaControl
The VwaControl object represents an instance of the Visio Web Access (VWA) web part. It has the following functional groups:
· Web part properties: using getVersion() and getDisplayMode() you can access web part properties such as the web part's version and its rendering technology (Silverlight or raster).
· Drawing-level: using getDiagramUrl()/setDiagramUrl(string diagramUrl) in tandem with openDiagram()* you can assign which diagram to display in the web part and then load it. External data connections in a drawing can be refreshed using refreshDiagram()*.
· Page-level: using getAllPageIds() in tandem with setActivePage(string pageId)* you can iterate through all the pages in a drawing. You can retrieve a reference to a particular page by using getActivePage().
· Events: using addHandler(string eventName, function functionName), removeHandler(string eventName, function functionName), clearHandlers() you can manage user interaction with the drawing by adding and removing event handlers to events such as:
o diagramcomplete – fired when a drawing finishes loading.
o shapeselectionchange – fired when a new shape is selected.
o shapemouseenter – fired when the mouse enters a shape's outline.
o shapemouseleave – fired when the mouse exits a shape's outline.
More details about the API's event model seciton.
· Errors: using displayCustomMessage(string HTML)and hideCustomMessage() you can show and hide and your applications' custom HTML error message pages.
* These methods are asynchronous which means that they trigger a non-blocking call back to Visio Services to replace the page currently displayed with another one. These operations have the side effect of making the current VwaControl object invalid which effectively stops you from coding against the OM after these statements. The best way to follow-up such calls is to create a handler for diagramcomplete, which fires when the VwaControl has finished loading the new page, and to put your code in that event handler. More details about the API's event model section.
Page
The Page object represents the active Web drawing page currently displayed in the web part. It has the following functional groups:
· Page: using getId() and getSize() you can access properties of the currently displayed page such as its page id and its size in pixels
· View: using getPosition()/setPosition(int x, int y) and getZoom()/setZoom(double zoom%) you can change the zoom center and zoom percentage of the web part's viewport. You can also use centerViewonShape(string shapeID) to focus the view on a particular shape and isShapeInView(string shapeID) to determine if a shape is in the current view.
· Shapes: using getSelectedShape() and setSelectedShape(string shapeID) you can change the currently selected shape. You can also get a reference to the collection of shapes in the currently displayed page by using getShapes().
ShapeCollection
The ShapeCollection object represents the collection of shape objects on the currently displayed page. It has the following functional groups:
· Shapes: using getCount() in tandem with getItemAtIndex(int index) you can easily iterate through all the shapes on a page; the array is 0 based. You can also use getItemByName(string shapeName), getItemById(string shapeId) or getItemByGuid(string shapeGuid) to index into the page’s shape collection using different Visio shape identifiers.
Shape
The Shape object represents a single shape on the active Web drawing page. It has the following functional groups:
· Shape Properties: using getName(), getId() & getGuid() you can access the shape's various Visio identifiers such as shape name, Id and Guid. You can also access a shape's meta-data by using getHyperlinks(), getShapeData() and getBounds().
· Markup: using addHighlight(integer width, string color), removeHighlight(), addOverlay(string overlayID, string content, Vwa.VerticalAlignment vPos, Vwa.HorizontalAlignment hPos, integer overlayHeight, integer overlayWidth), addPredefinedOverlay(Vwa.OverlayType overlayType, string overlayID, string content, [Vwa.VerticalAlignment vPos], [Vwa.HorizontalAlignment hPos], [integer overlayHeight], [integer overlayWidth]) and removeOverlay(string overlayID) you can manage shape markup.
Highlighting a shape draws a colored rectangle around the bounding box of the Shape as seen below:
A shape overlay is a way of adorning a particular shape with a developer visual. An example of this concept is a pushpin icon that is placed on top of a map in an online mapping application. With this set of functions, you can tag a Visio shape with your own overlay to bring attention to it:
Using the various arguments of addOverlay() and addPredefined() overlay you can configure the contents, size of the overlay as well as its alignment relative to the bounding box of the shape. Each shape may have more than one overlay; these overlays cannot however have the same developer-defined overlayID.
Note that when the underlying drawing is rendered in PNG, overlays be either HTML or an image. If the diagram is rendered in Silverlight, the overlay can be XAML or an image.
Visio Services allows you to view Visio diagrams in SharePoint, and the Visio Web Access web part allows you to embed those diagrams on a web part page. This post examines how you can turn those diagrams into interactive mashups without having to write any code.
SharePoint allows you to display multiple types of information on the same page by using multiple web parts. With web part connections, changes in one web part can drive changes in another web part. By connecting the Visio Web Access web part to other web parts, you can setup interactive mashups that would otherwise require use of the JavaScript API. The Visio Services JavaScript API will be detailed in a future blog post.
This post will show you a few examples of mashups with Visio Services and web part connections, and then it will explain how you can create your own mashups. We’ll finish off by detailing all the web part connection options available and some ideas for you to explore.
In our first example, we use web part connections to visually filter a Visio diagram using a SharePoint list. Visio Services allows you to display dynamic data connected diagrams. If your diagrams are using SharePoint lists as a data source, you can use the list view web part to filter the Visio diagram. As you apply filters to the list, the shapes in the Visio diagram corresponding to the rows in your list view are highlighted.
Below is a screenshot of a network diagram embedded on a web part page. The data is coming from a SharePoint list, and the list view web part is placed next to the Visio Web Access web part, showing some of the data in that list:
When you apply filters to the list, Visio Web Access highlights the shapes that correspond to the rows remaining in the list. So if you want to highlight all the servers that are from a specific manufacturer, or are running a specific operating system, it’s easy to do so. Here’s a screenshot of what happens when you choose to filter and only show servers from one manufacturer:
Notice that there are fewer rows in the list view web part, and that some of the shapes in the Visio Web Access web part are now highlighted with a red border.
You can easily apply multiple filters and clear them to focus your attention on a specific set of shapes. Using this method of visually filtering a diagram, you can look for trends in your data connected diagrams by highlighting a subset of your shapes.
You can also connect two Visio Web Access web parts on the same page to create a master detail view. When you click on a shape in the “master” web part, the “detail” web part displays related information. This is especially useful if you have a complicated process diagram that has several sub-processes, or anytime you want to show detail without losing high-level context.
The image below shows a web part page with two Visio Web Access web parts. The top web part is showing the high level process, and the bottom web part is showing more detail.
Notice in the above image that “Phase 1” is selected. When you click on a different phase in the top web part, the bottom web part updates to show you more information. This is what clicking on Phase 3 results in:
To show you how to setup a web part connection with Visio Web Access, let’s take a detailed look at a third scenario. In addition to being able to highlight shapes based on filters, you can also highlight shapes by setting up a list that contains the names of the shapes you want to highlight. This gives you more flexibility without needing to use the API. The picture below illustrates this. The list on the right contains 3 rows. Each row contains a column with a list of shapes. When you select a row, the corresponding shapes are highlighted.
Notice in the above picture that the first row in the list is selected, and the corresponding shapes are highlighted. Also notice that the second column in the list contains a comma-delimited list of shape names, e.g. “Process,Process.34,Process.70,Process.134”. You can easily hide this column from the view, but it is included here to illustrate the example.
When you change the selected row, different shapes are highlighted:
The following set of instructions show you how to setup the example described above with your own diagram:
You can also setup this connection using SharePoint Designer (SPD). The experience is very similar to the one described above. In the example above, we showed you how to map a field from the consumer web part to the provider web part. Some web part connection actions allow you to specify multiple fields or parameters. To map multiple fields, you should use SPD.
The examples above illustrated a few things you can do with web part connections and Visio Web Access. The list below details the five different connection options supported by Visio Web Access. Some connection actions allow you to specify multiple fields or parameters.
This connection action was used in the Master/Detail example above.
This connection action allows you to send shape data to another web part. When a shape is selected in the Web diagram, data from that shape is sent as a row. By default, the following shape data items are always sent:
To specify additional shape data items to send, open the Web Part tool pane. Type the labels of the shape data items as a comma-delimited list in the box labeled Expose the following shape data items to web part connections.
This connection action was also used in the Master/Detail example above.
This connection action allows you to load a web drawing or switch the displayed page. It takes two parameters:
Visio Web Access will load the web diagram at the specified URL, and switch to the page name specified. If no URL is specified, and only a page name, then it will switch to that page on the diagram that is currently open. If no page name is specified, then the default page will be loaded at the specified URL.
This connection action was used in the highlighting shapes example above.
This connection allows you to highlight shapes in a diagram. It takes two parameters:
When the connected web part sends a shape name or a list of names, Visio Web Access highlights those shapes with the specified highlight color. If no color is specified, a default color is used.
This connection action was used in the “filtering a diagram” example above.
This connection action allows you to “filter” a Visio diagram that is connected to a SharePoint list. The connected web part must contain a SharePoint list that is being used as a data source in the diagram. When the SharePoint list is filtered, the diagram highlights the shapes that correspond to visible results in the filtered SharePoint list. The diagram must be connected to the SharePoint list that the connected Web Part is displaying. For more info on how to create a data connected diagram, see this video.
This connection action allows you to change the view and zoom of the diagram displayed in the Visio Web Access web part. It takes two parameters:
When the connected web part sends a shape name, the Visio Web Access web part centers the view on the specified shape with the zoom level. If no zoom level is sent, then the current zoom percentage is used. You might use this if you have a large diagram and you want to create pre-defined views. For example, if you have a large floor plan, you might setup pre-defined views for different areas of the building.
We’ve shown three examples here of how you can use Visio diagrams and web part connections to create mashups. Here are some other ideas you might try creating yourself:
Web part connections allows end-users, pro-users, and developers to create quick mashups that would otherwise require writing code. We’re interested in hearing what you think of this functionality, please use the Send a Smile feedback tool or leave a comment below.
This post examines the programmability features for Containers, Lists and Callouts in Visio 2010. It supplements an earlier post that describes how these special shapes are constructed and how they can be customized. Collectively these shapes are known as Structured Diagram elements, and the part of the Visio API that manages these elements is known as the Structured Diagram API. This API enables developers to use Structured Diagram elements in their solutions. Developers can identify the relationships between these elements and other shapes, they can add or change the relationships with other shapes, and they can detect when the user makes changes to the relationships with other shapes.
Here are the key objects, properties and methods in the Structured Diagrams API:
There are two new objects in the API. ContainerProperties is an extension of the Shape object. It encapsulates the special properties and behaviors of containers and lists. RelatedShapePairEvent is an object used with the Structured Diagram API events, where Visio can describe a relationship being formed or broken between two shapes. The remaining parts of the API are additions to existing Visio objects.
Note that lists are just another type of container as far as the API is concerned. Therefore, lists use all the same objects, properties and methods as containers; and lists have a few additional properties and methods as well (those with “List” in their name).
Visio 2010 introduces a new feature called Diagram Services that manages what diagramming behaviors are enabled in the document. There are diagram services that control the behavior of Auto Size Page and diagram services that control the behaviors of Containers, Lists and Callouts. These services are turned on and off at the document level. When a service is off, changes made in the diagram through automation will not trigger the diagramming behaviors related to that service. (Changes made through the user interface are not subject to the diagram service state.)
For example, the Auto Size Page feature will normally grow the page size if a shape is placed outside the page boundary. However, when a shape is placed outside the page via automation, the Auto Size Page feature will only respond if the Auto Size Page diagram service is enabled. Similarly, dropping a shape on top of a container will normally make it a member of the container and cause the container to resize to fit it. However, when the shape is dropped via automation, the Containers feature will only respond if the Structured Diagram service is enabled.
The reason Visio 2010 includes this capability is that solutions may not always want these diagramming behaviors to get triggered while they are manipulating shapes in the diagram. This may especially be true for existing solutions that have no knowledge of the new Visio 2010 behaviors and have expectations that shapes respond in ways consistent with Visio 2007. In order for existing solutions to work as originally designed, all diagram services in Visio 2010 are disabled by default. Solutions must opt the document in to the new diagramming behaviors. Note that diagram service states apply to automation properties and methods that existed in Visio 2007. When a new Visio 2010 automation method is explicitly invoked by a solution - such as any of the examples below – the service state is ignored. The presumption is that the solution wants the Visio 2010 behavior associated with that method.
Diagram service states are checked or changed using the Document.DiagramServicesEnabled property. The value of this property is a mask of all the services currently enabled. Available services and values are listed in the table below. It is possible for a solution to opt into just one service, all the services supported in Visio 2010, or even all existing and future services.
VisDiagramServices values:
There are two services for Structured Diagram behaviors. The StructureBasic service maintains relationships but will not form new ones. This might be appropriate for a solution that wants to respect the user’s usage of Containers, Lists and Callouts but does not want the solution itself to inadvertently form relationships when shapes are moved around the page. The StructureFull service maintains relationships and will form new relationships as well. This matches the behaviors that are triggered in the user interface. If both services are enabled, then Visio uses the StructureFull set of behaviors.
Let’s look at some typical Structured Diagram tasks to explore the API in greater detail. For a complete list of the special flags that can be passed into the methods, look at the Object Browser within the VBA editor in Visio.
Containers can be added to a page by calling the traditional Page.Drop method, which will add the shape at coordinates you specify without affecting the membership of existing shapes on the page. However, there is a new Page method – Page.DropContainer - that will not only drop the container but will also size it around a set of shapes and make those shapes members of the container. This is the behavior in the UI when using Insert > Container when a selection exists. DropContainer needs an object for the container shape. If you want to use one of the shapes in the Insert Container gallery, you can use the GetBuiltInStencilFile method to retrieve the hidden stencil where these containers are stored.
Dim vsoDoc1 As Visio.Document Set vsoDoc1 = Application.Documents.OpenEx(Application.GetBuiltInStencilFile(visBuiltInStencilContainers, visMSUS), visOpenHidden) Application.ActivePage.DropContainer vsoDoc1.Masters.ItemU("Container 1"), Application.ActiveWindow.Selection vsoDoc1.Close
Shapes are added to a container by moving or dropping them onto the container (if the StructureFull diagram service is enabled). Shapes can be explicitly added to a container using the AddMember method. This is useful when the shape already overlaps the container and is not yet a member. It is also helpful if you want to force the container to expand to encompass the new member.
vsoContainerShape.ContainerProperties.AddMember vsoShape, visMemberAddExpandContainer
To discover what containers exist in a document, Visio provides a direct way to get the set of containers in a selection or on a page. The GetContainers method returns an array of Shape IDs for the containers. Containers nested within other containers can be included or excluded using flags.
For Each containerID In vsoPage.GetContainers(visContainerIncludeNested) Set vsoContainerShape = vsoPage.Shapes.ItemFromID(containerID) '... Next
Solutions can identify the members of a container using the GetMemberShapes method, which returns an array of Shape IDs for the member shapes. The flags allow certain kinds of member shapes to be filtered out of the array returned.
For Each memberID In vsoContainerShape.ContainerProperties.GetMemberShapes(visContainerFlagsDefault) Set vsoShape = vsoPage.Shapes.ItemFromID(memberID) '... Next
Every member of a list is placed in a specific position, and that ordinal value can be retrieved with the ContainerProperties.GetListMemberPosition method. To reorder a member, you can call the ContainerProperties.ReorderListMember method. Both methods use 1 to indicate the first position in the list.
vsoListShape.ContainerProperties.ReorderListMember vsoShape, 2
Callouts can be added to a page by calling the traditional Page.Drop method, which will add the shape at coordinates you specify. However, there is a new Page method – Page.DropCallout - that will not only drop the callout but will associate it with a target shape and position it near the target shape. This is the behavior in the UI when using Insert > Callout when a selection exists. As with DropContainer, DropCallout needs an object for the callout shape. If you want to use one of the shapes in the Insert Callout gallery, you can use the GetBuiltInStencilFile method to retrieve the hidden stencil where these containers are stored.
Dim vsoDoc1 As Visio.Document Set vsoDoc1 = Application.Documents.OpenEx(Application.GetBuiltInStencilFile(visBuiltInStencilCallouts, visMSUS), visOpenHidden) Application.ActivePage.DropCallout vsoDoc1.Masters.ItemU("Callout 1"), vsoTargetShape vsoDoc1.Close
A shape can have multiple callouts, but a callout can have only one target shape at a time. The Shape.CalloutsAssociated property returns an array of callout shape IDs. You can get or set the target shape of a callout using the Shape.CalloutTarget property.
Set vsoShape = vsoCalloutShape.CalloutTarget
In addition to manipulating the containers, lists and callouts in a document, you can also respond to user actions that relate to these shapes. Containers, lists and callouts work by establishing relationships with other shapes. Visio fires an event whenever one of these relationships is formed or broken. For example, adding a shape to a container forms a new relationship between the shape and the container.
When a relationship event fires, Visio specifies the details in a RelatedShapePairEvent object. The FromShapeID property of this object indicates the container, list or callout involved in the relationship. The ToShapeID property indicates the other shape involved in the relationship. Thus when adding a shape to a container, the ToShapeID would refer to the new member shape, and when associating a callout with a target shape, the ToShapeID would refer to the target shape.
The following events are available for Application, Documents, Pages and Page event lists:
ContainerRelationshipAdded ContainerRelationshipDeleted CalloutRelationshipAdded CalloutRelationshipDeleted
ContainerRelationshipAdded
ContainerRelationshipDeleted
CalloutRelationshipAdded
CalloutRelationshipDeleted
Also the ShapeChanged event will now fire when members of a list shape are reordered. The event passes the list shape as an argument and includes the string “/ListReorder” in the EventInfo argument.
The Structured Diagrams feature set – Containers, Lists and Callouts – offers both end users and developers significant new diagramming capabilities in Visio 2010. We’re interested to hear what developers think of this API functionality, so please use the Send a Smile feedback tool or leave a comment below.
Workflow design often takes a lot of communication and collaboration. Business stakeholders may send IT professionals business flowcharts to further automate as workflows. On the flip-side, once the IT professional has implemented the workflow, he/she may want to store the workflow as a Visio diagram so that all stakeholders are clear on what is being implemented. Such diagrams can also serve as copies that can be archived for auditing purposes.
Such collaboration is made easier with the workflow export and import capabilities in Visio Premium 2010. Export (as described in an earlier blog post) enables business stakeholders to pass flowcharts as business requirements to IT Professionals. With import, IT professionals can document their workflows visually. In this post, we will walk through the following:
First, let’s discuss the workflow import capabilities in Visio 2010.
From SharePoint Designer 2010 to Visio 2010
With SharePoint Designer 2010, an IT professional can author an executable SharePoint workflow that publishes directly to SharePoint server. Such a workflow may look like the following:
Before a workflow is ready for execution, it can be exported as a Visio diagram for Business Analyst or all process stakeholders to review before publishing. To do so, simply use the Export to Visio command in SharePoint Designer 2010, and a Workflow Visio Interchange (*.vwi) file will be saved out:
To visualize this workflow in Visio 2010, import the workflow file by going to New->Microsoft SharePoint Workflow, then go to the Process tab-> Import Workflow:
From there, the workflow is visualized in Visio, and the IT Professionals or Business Stakeholders are free to edit and enhance the diagram just the same way as any flowchart using features such as Themes or Auto Align & Space for presentation purposes:
The workflow visualization is now ready to be archived or presented to a wider audience.
Publishing Visio Visualization from SharePoint Designer 2010
We have discussed how workflows can be imported or exported between Visio Premium 2010 and SharePoint Designer 2010. Now let’s talk about how you can also show the status of a workflow being executed directly on SharePoint. SharePoint Designer 2010 supports publishing the visualization straight to the SharePoint Server along with the executable workflow. To do so, simply enable visualization by going to the workflow settings page, and ensure that the checkbox “Workflow Visualization” is checked:
When visualization is published from SharePoint Designer 2010, the status of the workflow execution is also shown as part of the Visio diagram. For example, as shown in the diagram below, not only are there icons indicating tasks “in progress” or “completed”, people assigned to the Tasks are also displayed clearly within the Task shapes:
The workflow is not only being executed, but users can now easily track progress of the workflow through visualization!
Try out our Beta!
We are very excited to bring you this new functionality and it is avaible for you to try out in the public beta. Do try it out and send us feedback through the Send a Smile feedback tool or comment on this post!
In a previous blog post about new ShapeSheet functions, we introduced a set of new functions called the Point Along Path functions. These functions allow interactions with geometry paths of shapes. This post provides more detail about these new functions.
The following functions open up a broad set of shape interactions for shape and solution developers:
In the above functions:
To give you an idea of what you can do with these functions, we'll explore three examples.
We've seen shape developers create connector adornments to convey additional information. With the Point Along Path functions, this is now easier than ever to do.
Here's a simple triangle shape that sits at the midpoint of the connector, and changes direction with the connector. It works with curved and right angle connectors:
To create this adornment, you only need a few ShapeSheet formulas:
You can use the NEARESTPOINTONPATH() function to find the coordinates of a point along a path that is closest to a given point. In the picture below, the triangle shape is showing the nearest point along the path to the center of the circular shape:
Here’s how we setup the triangle to do this:
Just like the example above, you then need to transform the local coordinates, and set the PinX and PinY of the triangle so that its glued to the arc.
The above two examples illustrate how you can use the Point Along Path functions. As an application of the same concepts above, we built a curved timeline:
As you change the curve of the timeline, the milestone shapes stay attached to the curve, which allows you to create a great looking visual.
The main difference between this example and the previous one is that we’ve introduced a mechanism for automatically attaching adornments to the arc geometry. Here we turned the arc shape into a custom container to give the milestone shapes a universal reference. Since they are members of the container, we use the CONTAINERSHEETREF() function to reference the geometry of the arc. When you make multiple copies of the milestone shape, their reference to the timeline arc geometry is preserved as long as they are members of the container. (For more info on custom containers, see our previous post ).
To place the milestones accurately on the timeline arc, we used the POINTALONGPATH() function. Each timeline shape stores its own date. The timeline arc contains the “begin” and “end” dates of the timeline.
The attached VSD file includes the curved timeline, and the other two examples, so you can take a look at the formulas and play around with them.
We think these new functions will open up a new set of scenarios for shape developers. Some things you might try to create with them are:
As usual, please tell us what you think by using the Send a Smile feedback tool or by commenting on this post.
In previous posts we introduced you to Containers and some of their special capabilities. We also introduced Lists through their use in Cross-functional Flowchart, Data Graphic Legends and Wireframe shapes. Finally we introduced Callouts as annotations on Visio diagrams. Containers, Lists and Callouts can be used in a wide variety of diagram types. This article explains how shape designers can go beyond the built-in shapes and create their own custom content.
Collectively Containers, Lists and Callouts are referred to as Structured Diagram elements. They establish relationships with other shapes and those relationships define special behaviors. For example, shapes placed into a list are automatically arranged adjacent to one another; a callout shape moves whenever its target shape is moved. Structured Diagram elements are shapes themselves, and thus the special behaviors are defined through their ShapeSheet cells and values.
To designate any shape as a Container, List or Callout you only need to add one User-defined cell called User.msvStructureType. For the value enter “Container”, “List” or “Callout” as desired. This setting tells Visio that the shape is a Structured Diagram element and adds many of the Structured Diagrams behaviors to the shape. In the image below, a rectangle shape is transformed into a container shape by adding the User.msvStructureType cell and setting it to “Container”. However, there are additional settings available to customize the appearance and behavior of your shape, described in the rest of the article.
Any shape with User.msvStructureType = “Container” is treated by Visio as a Container. The following ShapeSheet cells define additional container properties, several of which can be configured in the Container Tools contextual tab in the Ribbon.
If you are creating a container shape from scratch, you will notice that by default the container does not have any Container Style or Heading Style available in the Container Tools tab. Styles are a way to offer different looks for your container through some combination of geometry and formatting changes. The container shape can define multiple visual styles using the User.msvSDContainerStyle, User.msvSDContainerStyleCount, User.msvSDHeadingStyle and User.msvSDHeadingStyleCount cells (in short, the “Style” cells and the “Count” cells). Use the Count cells to tell Visio how many styles your shape supports for the overall container or for the heading. Then determine what ShapeSheet cells should be set for each style. Put formulas in each of these cells that depend on the value of the Style cells. Visio will check the style count and populate the ribbon galleries with each style defined by the container shape. When the user chooses a new style from the gallery, Visio puts that style index back into the Style cells to update the look of the container.
The container shapes in Visio 2010 vary in complexity. The containers in the Insert Container gallery have many visual styles and lots of formulas to change the appearance of the shapes. There are some simpler examples in the Wireframe shapes, which define just a few styles each.
Visio 2010 introduces the concept of Shape Categories to refine the membership behaviors of containers. This is the mechanism used by features such as Cross-functional Flowchart and Data Graphic Legends to ensure that only the right kinds of shapes participate in the list and container behaviors. A container shape can restrict membership by defining a required or excluded shape category. For this to work, a prospective member shape must have a User-defined cell User.msvShapeCategories in its ShapeSheet. The prospective shape lists one or more category names in a semi-colon delimited string. To only allow a specific category of member shape, a container can set that name in its User.msvSDContainerRequiredCategories cell. To allow most shapes as members but specifically exclude a category, a container can set that name in its User.msvSDContainerExcludedCategories cell. (Prospective shapes with no categories defined will not be allowed in a container with required categories, and they will always be allowed in a container with excluded categories.)
The heading of a container is simply the container shape’s text for basic containers. However, it is possible to achieve more sophisticated visual styles if the heading becomes its own shape. For this construction the container becomes a group and the heading is added as a sub-shape of the group. The primary benefit is that Visio can account for the heading sub-shape in sizing and layout operations to avoid putting member shapes on top of the heading. To designate a sub-shape as a heading for the container, add the cell User.msvStructureType to the sub-shape and give it the value “Heading”. Also you should properly set the User.msvSDContainerHeadingEdge cell in the sub-shape. These cells helps Visio understand how the heading is positioned relative to the interior of the container. For example, if the heading is near the left edge of the container then the correct value for the cell is “Right” (regardless of the heading’s angle). The interior of the container is on the right side of the heading.
Visio provides several built-in container shapes in the Insert Container gallery located on the Insert tab of the ribbon. It is possible to override this set of shapes by creating a specially named stencil with other container shapes. Create a stencil named _CONTAIN.vss and place it in the user’s My Shapes folder.
Any shape with User.msvStructureType = “List” is treated by Visio as a List. Note that Lists are also considered to be Containers. They simply have the additional capability of ordering and arranging their member shapes. All of the previously mentioned Container cells apply to list shapes. The following ShapeSheet cells define additional list properties.
There are several ways to add a shape to a list: dragging and dropping the shape, clicking the blue insertion arrow that appears near the list edge or right-clicking an existing member and inserting a shape. Clicking the insertion arrow and right-clicking to insert both use the User.msvSDListItemMaster cell to determine what shape to add to the list. The name of the shape is placed in quotes inside a USE() function, such as USE(“Member shape”). It is also possible to automatically populate the list with some member shapes when the list is first dropped on the page. To do this put the following formula in the EventDrop cell of the list, repeating the DOCMD(2270) once for each member to be added:
IF(LISTMEMBERCOUNT()=0,DOCMD(2270)+DOCMD(2270)+DOCMD(2270),0)
Lists have their own cells to govern list membership. Use the User.msvSDListRequiredCategories and User.msvSDListExcludedCategories cells to restrict what shapes can become list members. Because lists are also containers, it is possible for shapes to become container members of the list. The standard User.msvSDContainerRequiredCategories and User.msvSDContainerExcludedCategories cells determine this behavior. By default Visio will attempt to add a shape to a list as a list member, but if that fails it may try to add it as a container member. You should manage both sets of cells to ensure the right results.
Any shape with User.msvStructureType = “Callout” is treated by Visio as a Callout. Callout shapes must also have a control handle with the Controls row named Controls.Association. Visio manages the relationship with the callout’s target shape through this row in the ShapeSheet. The following ShapeSheet cells define additional callout properties.
Visio provides several built-in callout shapes in the Insert Callout gallery located on the Insert tab of the ribbon. It is possible to override this set of shapes by creating a specially named stencil with other callout shapes. Create a stencil named _CALLOUT.vss and place it in the user’s My Shapes folder.
This post gives shape designers the detailed information needed to create their own Containers, Lists and Callouts. Please tell us what you think by using the Send a Smile feedback tool or by commenting on this post.
Diagram Validation is a new Visio 2010 feature that provides a way for users to check their diagrams for common errors and for companies to ensure that employees are following certain diagramming standards. The basics of diagram validation and creating custom validation rules have been previously discussed on this blog. In this post, we focus on the details of using the validation API to create validation rules, trigger validation, and manage validation issues.
Visio provides an extensive Diagram Validation API that allows companies to develop custom validation rules based on their own needs. For example, you can build rules to check that a network diagram includes mandatory components, or that a process diagram complies with company policies. The ability to verify the correctness of a diagram and raise issues to end-users is also crucial for solutions that need a certain diagram structure to work. For example, Visio uses validation for Microsoft SharePoint Workflow diagrams to ensure that SharePoint workflows are structured correctly before exporting them. As a developer, you can leverage Diagram Validation to support diagram verification for the diagram types and the issues that are important to you.
The key objects, methods and properties for validation are shown below.
The validation API is based on three main concepts: rule sets, rules and issues. A validation rule, or simply a rule, represents one type of error that can occur in your diagram. Each rule has some underlying business logic which determines when the rule has been broken. An issue is one case in your diagram where the validation rule has been broken. Depending on your diagram, there may be multiple issues associated with the same rule. For example, if the rule requires that all shapes be labeled, then validation will display an issue for each shape without a label. Rule sets are logical grouping of rules, such as the BPMN and flowchart rule sets.
Rules sets, rules and issues each have corresponding API objects, namely ValidationRuleSet, ValidationRule and ValidationIssue. Below we explain the key properties for each of these objects.
Every rule set has a unique NameU property representing the universal name of the rule set. You should also specify a Description for each rule set. Other properties are set by default, and only need to be modified if a different behavior is desired. The key properties of the ValidationRuleSet object are shown below.
Every rule has a unique NameU property representing the universal name of the rule. You should also specify a Category and Description for each rule set, as these properties are used in the UI. The Category should inform the user about the type of issue, and may be used to identify the rule set that triggered the issue. The Description should be explicit enough to explain the issue so that a user can address it.
The blog post on creating custom validation rules describes two approaches for creating custom validation rules: you can store validation logic in a Visio template, or you can express validation logic in code and deploy this logic as part of a Visio solution. If you decide to store validation logic in a Visio template, the FilterExpression, TestExpression and TargetType are the fundamental properties for detecting and reporting issues during validation. If you decide to write validation logic in code, these fields should be left blank. The FilterExpression, TargetType and TestExpression properties are described in more detail in the section titled Defining ValidationRule.FilterExpression and ValidationRule.TestExpression.
The key properties of the ValidationRule object are shown below.
Every issue has an associated Rule which specifies the description and category that is displayed in Issues window. When a user clicks on an issue in the Issues window, Visio will navigate to the page of the issue (if the issue targets a page or shape) and will select the target shape (if the issue targets a shape).The TargetPage, TargetPageID and TargetShape properties are used determine the page to display and the shape to select. The key properties of the ValidationIssue object are shown below.
Validation methods can be divided into different groups. We will start by describing the first group of methods, which allows developers to add validation rule sets and rules to a document. Typically, these methods are executed once to populate a template or diagram with validation rules. In fact, the rules can be pre-populated in a template, and then the template can be deployed to end-users without any solution code.
For each of the following API methods, we give a brief description on what the method does, along with an explanation of the method’s arguments.
Adds a new, empty ValidationRuleSet object to the ValidationRuleSets collection of the document.
Adds a new, empty ValidationRule object to the ValidationRules collection of the document.
The following VBA code adds a rule set and a rule that targets a shape to the active document.
When you set the TargetType, FilterExpression and TestExpression of a rule, Visio will manage issues associated with the rule for you. For very complex validation rules, it will be easier to omit these properties and write the validation logic in solution code. For this approach, the solution should listen for the appropriate RuleSetValidated event and use its own logic to determine the list of issues to add to the document.
We give a brief description of the two key methods that you will use to manage issues, along with an explanation of the method’s arguments.
Creates a new validation issue that is based on the validation rule, and adds it to the document.
Deletes the ValidationIssue object from the document.
The following VBA code adds an issue to an existing rule. It assumes that vsoValidationRule is a valid Visio.ValidationRule object, vsoShape is a valid Visio.Shape object and vsoPage is a valid Visio.Page object.
If you have a custom solution that needs a certain diagram structure to function properly, you can use the Validation.Validate method to validate the diagram and raise issues to end-users. This method validates a particular validation rule set (if specified) and updates the Validation. LastValidatedDate property. It will also trigger the RuleSetValidated event. It is recommended that you omit the rule set parameter, and validate against all active rule sets. This gives end-users a clear and consistent view of the issues currently in their document.
Validates the specified validation rule set.
The following VBA code validates all rule sets in the document and launches the Issues window.
When you validate a diagram by calling the Validation.Validate method or by clicking Check Diagram on the Process tab, Visio will automatically use any validation logic stored in the document to detect errors. This validation logic is expressed in the ValidationRule.TargetType, ValidationRule.FilterExpression and ValidationRule.TestExpression properties. The FilterExpression and TestExpression should be written as Boolean expressions that can be evaluated on every object of type TargetType. During validation of a rule, for every object of type TargetType, Visio uses the FilterExpression to determine whether the object must satisfy the validation rule. If the filter expression evaluates to True, Visio uses the TestExpression to determine whether to generate an issue for the object. If the filter expression evaluates to False, Visio does not apply the validation rule to the object.
The syntax for the FilterExpression and TestExpression properties are the same as that of a ShapeSheet expression (you can get more details here and here if you're unfamiliar with the ShapeSheet). For example, since NOT(IS1D()) is a valid Boolean expression for the ShapeSheet of a shape, "NOT(Is1D())" is a valid FilterExpression or TestExpression for a validation rule with TargetType = Visio.VisRuleTargets.visRuleTargetShape. In addition to the standard ShapeSheet functions, the following validation functions can be used in a FilterExpression or TestExpression.
The validation expression functions ConnectedShapes and GluedShapes correspond to connectivity API functions with the same names. Similarly, the possible values of the Direction input parameter for ConnectedShapes and GluedShapes correspond to the VisConnectedShapesFlags and VisGluedShapesFlags enumerations, respectively.
We hope that this overview of the validation API provides the necessary details to start writing your own validation rules. We’re interested to hear what developers think of this API functionality, so please use the Send a Smile feedback tool or leave a comment below.
Our previous post introduced the improvements we made to the ShapeSheet window for shape developers. In this post, we will continue with ShapeSheet development and dig deeper to examine the new ShapeSheet cells and functions available in Visio 2010.
A number of new cells were added to both the PageSheet and the ShapeSheet to support new features in Visio 2010 and to expand the possibilities for shape development. We will examine each one in turn.
New PageSheet cells in Visio 2010:
New ShapeSheet cells in Visio 2010:
Recall that you can view the PageSheet for a page or the ShapeSheet for a shape using the Developer tab.
This cell takes a TRUE or FALSE value and determines whether the Auto Align and Space features attempt to avoid placing shapes on page breaks. This corresponds to the Space Shapes > Avoid Page Breaks setting under the Position button on the Home tab.
This cell corresponds to the Page Auto Size feature, which is found on the Design tab. It takes three values. Values 1 and 2 correspond to Auto Size on and off, respectively.
Zero is “undefined,” which is the default state for a document created in Visio 2007 or prior, since this cell doesn’t exist in those versions. This value allows Visio to determine whether Auto Size is enabled for the user. It makes a best guess by looking at the page size relative to common paper sizes and deciding whether the page size appears to have been customized, or left at a default size. If the page is at a default size, Visio enables Auto Size so users can benefit from it; if customized, Visio assumes that a specific page size was chosen for a reason and disables Auto Size. In any case, the user can change the setting by toggling the Auto Size button on the Design tab.
This cell defines “bands” of Z-order and is used to determine the default global Z-order position for a shape when it is added to the page. Visio uses this to place containers behind the shapes they contain, regardless of what order they are added to the page. Shapes with a higher DisplayLevel value are displayed on top of shapes with a lower value. Each value of DisplayLevel, which ranges from –32767 to +32767, defines a band.
As an example, consider a diagram with three masters, each with the DisplayLevel value shown. Regardless of what order shapes with DisplayLevel 10, 20 or 30 are dropped, the 10s will always be behind the 20s and 30s, and so forth. The blue shape shown below is at the bottom of the Z-order and was dropped before the other two shapes at DisplayLevel 10. DisplayLevel bands do not interfere with the Z-order commands on the Home tab – Bring Forward / Send Backward and Bring to Front / Send to Back. Using Bring to Front or Send to Back will initially only move the shape to the front or back of the Z-order for its band. A subsequent use will move it to the global front or back of the Z-order.
Notice the special –32768 value, which means that the shape has been pulled out of its band. Visio stores the previous band in a formula in the DisplayLevel cell so it can be restored. Note that changing the value of the DisplayLevel cell does not change the shape’s Z-order, but the band will be taken into account the next time Visio needs to manipulate the shape’s Z-order.
This cell allows Actions, or custom right-click menu items, to be nested. Any menu item whose FlyoutChild value is TRUE will appear in a flyout menu of the first row above it whose FlyoutChild is FALSE. This allows one level of nesting.
The Actions section below will show the following custom items on the right-click menu.
If the value of FlyoutChild for B and C is TRUE, then those items appears in a flyout menu under A.
This cell allows a shape developer to control how click and drag inside a given geometry section of a shape works. Typically, this picks up and moves a shape. By setting this cell to TRUE, you can create a non-clickable (or non-selectable) filled geometry area that prevents picking up and moving the shape. The container shapes new to Visio 2010 use this cell to allow click and drag to select shapes in the container rather than move the container.
This cell stores the relationships among containers, lists, callouts and shapes. It uses a series of DEPENDSON functions, one for each different type of relationship the object has. Note that changes to this cell will not trigger actual relationship changes; Visio only uses this as a means to store the relationship information. This cell is not intended to be modified by users or shape developers.
The types of relationships are listed below.
A shape named Process that is a member of a container named Container 1 would have a Relationships cell formula of this form: =SUM(DEPENDSON(4,Container 1!SheetRef())). The container’s Relationship cell would look like: =SUM(DEPENDSON(1,Process!SheetRef())).
If the Process shape were pinned to the left edge of the container, its Relationships cell would be: =SUM(DEPENDSON(7,Container 1!SheetRef()),DEPENDSON(4,Container 1!SheetRef())). The container’s cell would remain as listed.
A shape that is a member of two containers would look like: =SUM(DEPENDSON(7),DEPENDSON(4,Container 1!SheetRef(),Container 2!SheetRef())), and so forth.
We also added ShapeSheet functions that enable new developer scenarios, particularly for integrating with new Visio 2010 features.
A number of functions are designed to enable interaction with the new container and list features.
The following functions return a Sheet reference, or a reference to the shape. (Such functions exist in Visio 2007 and previous versions, such as NAME and ID.) This return value can then be used to call another function. For example, CALLOUTTARGETREF()!HASCATEGORY(“Category”).
The following functions return the number of associated shapes.
The following functions
In the example below, the rectangular process shape belongs to a container. It shows the total number of shapes in the container using a text field with the formula CONTAINERSHEETREF(1)!CONTAINERMEMBERCOUNT().
Another set of functions enable detailed interaction with individual geometry paths among different shapes. Each of these functions requires a specific Geometry section to be specified – e.g., PATHSEGMENT(Sheet.1!Geometry2.Path, 0.4). Points on a path are given as a percentage of the distance along the path.
These functions open up a broad set of interesting shape interactions that we’re sure shape and solution developers will love. We will write a more detailed post focusing on these functions soon.
The last group of functions are various helpers that either support the new functions or fill in gaps. The first four operate on a Sheet reference.
Index enumeration for BOUNDINGBOXDIST:
Index enumeration for BOUNDINGBOXRECT:
We also modified the following functions that existed in Visio 2007 and prior versions. You can continue to use these as you have in the past – e.g., NAME() – or you can use them with a Sheet reference, such as Sheet.4!NAME() or CONTAINERSHEETREF(1)!NAME().
We hope you will find these useful in opening new opportunities for shapes and making your shape development tasks easier. As always, we’re interested in your feedback and suggestions via a comment on the blog or using Send a Smile.
In this post, we’ll be covering improvements to the ShapeSheet in Visio 2010 that make it easier for shape developers to create and modify existing Visio shapes.
For those who don’t know, Visio shapes are more complex than they may seem at first; behind each shape is a ShapeSheet (you can get more details here and here if you're unfamiliar with the ShapeSheet). In Visio 2010, you can access a shape's ShapeSheet by selecting the shape in question and clicking the "Show ShapeSheet" button on the Developer tab. If you don’t have the Developer tab up already, learn how to turn it here. Once you’re in ShapeSheet mode you’ll see the following user interface:
As you navigate through the updated ShapeSheet experience you’ll quickly stumble on our improvements. In the ShapeSheet editing window (1 above), Visio 2010 now facilitates user input with a new feature called ShapeSheet Formula AutoComplete. The ShapeSheet user interface has also been simplified considerably by the creation of the ShapeSheet Contextual Tab (2 above) to facilitate common ShapeSheet actions.
Let’s take a deeper look into each improvement.
One key features of the ShapeSheet is that it enables Visio shape developers to create a dependency between one shape property (also known as a ShapeSheet cell) and another through a formula. For example a shape developer can set height = 2 * width.
To this day, to become a proficient shape designer, you had to memorize all 345 cell names, 17 row names, 40 section names and the syntax to 181 ShapeSheet functions – not an easy task! Visio 2010 however makes your life much easier by introducing a new feature called ShapeSheet Formula AutoComplete. This feature helps you compose ShapeSheet formulas by:
1. Providing a context-sensitive list of ShapeSheet formula keywords as you type. All ShapeSheet functions, section names, row names and most** cell names are accessible via ShapeSheet Formula AutoComplete (**Visio doesn’t surface cells in non-named rows such as the “X1” or “Y1” rows in the Geometry section). As you compose a formula in a cell, Visio scrolls a list of keywords that are appropriate for the current context and selects the keyword that most closely matches what you're typing.
Take a look below to see ShapeSheet Formula AutoComplete in action. As you type “P-R-O”, the list of keywords scrolls to the “Prop” section name which also gets selected as Visio’s best guess. After auto-completing the section name by using “.”, Visio replaces the keyword list with one that makes sense in this new context, in this case the shape data item “CostOfShape”.
Also notice that Visio helps you locate the keyword you’re looking for by sorting them alphabetically and tagging them with one of the icons below depending on what type of keyword it is.
2. Providing a quick input mechanism for ShapeSheet formula elements. Once you've typed enough letters to uniquely identify a ShapeSheet keyword, you can simply hit "Enter" or "Tab" to complete the keyword. Depending on context, the ",", ".", "!", “*”, “+”, “-”, “/”, “[”, “(“ and “)” symbols will also do the trick.
3. Providing a definition of the ShapeSheet items. If you're not sure of the definition of a ShapeSheet keyword, a tool tip appears next to the currently selected keyword in the AutoComplete list with a definition for it. For example, below, is a definition for the PATHSEGMENT function, one of the new ShapeSheet functions in Visio 2010.
4. ShapeSheet function parameter browsing. As you compose a ShapeSheet function, the function signature appears above the cell in a tooltip. The bolding in the tooltip changes as you progress through a function’s arguments.
5. ShapeSheet formula parenthesis matching. As you close a parenthesis pair with a ")" character, ShapeSheet Formula AutoComplete will highlight the matching open-parenthesis in red.
ShapeSheet Formula AutoComplete is available in the following textboxes, dialogs and windows throughout Visio 2010:
The ShapeShee Formula AutoComplete feature can be toggled off through one of these entry points:
Apart from ShapeSheet Formula AutoComplete, the ShapeSheet has gotten a facelift thanks to the Fluent UI – all ShapeSheet related commands are now in one place. Take a look at the ShapeSheet contextual tab below.
In more detail:
Chunk
Button
Functionality
View
Formulas
Toggle the “formula” view of the ShapeSheet – all cell formulas are shown.
Values
Toggle the “value” view of the ShapeSheet – all cell results are shown.
Sections
Surfaces the “View Sections” dialog which lets you show or hide ShapeSheet sections.
Style Explorer
Surfaces the “Style Explorer” pane that lets you view and edit styles in the current drawing.
Section
Insert
Adds optional sections of your choice to the currently selected ShapeSheet.
Delete
Deletes the optional section you have currently selected.
Rows
Adds a row to the optional section you have currently selected.
Deletes a row from the optional section you have currently selected.
Editing
Edit Formula
Surfaces the “Edit Formula Dialog”, seen below, which gives you more room to enter long equations as well as the possibility of adding carriage returns to your formulas to improve legibility. As you can see below, ShapeSheet Formula AutoComplete is still active in this dialog.
Note that you can also open this dialog by using the “ctrl+e” key combination.
Shape Data
Adds a ShapeData row to the currently selected ShapeSheet.
Hyperlink
Adds a Hyperlink row to the currently selected ShapeSheet.
Shape Action
Adds an Action Row to the currently selected “Actions” section.
Formula Tracking
Show windows
Toggles the visibility of the “Formula Tracing” window.
Trace Precedents
List in the “formula tracing” window all the cells the currently selected cell depends on.
Trace Dependents
List in the “formula tracing” window all the cells that depend on the the currently selected cell.
Back
Jumps to the previous cell in the formula tracing history.
Forth
Jumps to the next cell in the formula tracing history.
Using the Fluent UI, Visio can now enable and disable interactively the ShapeSheet operations that you can take against a particular cell while you're editing it; this removes some of the right-click menu hunting you may have done in the past.
The final change we’ve made to the ShapeSheet experience in Visio 2010, is to enable shape designers to open one ShapeSheet window per shape instead of re-using the same window for all shapes, the latter behavior being the default in previous releases of Visio.
Download Visio 2010 Beta and start building shapes with the 2010 ShapeSheet -- we're interested in hearing what you think of Visio's new and improved ShapeSheet experience. You can send us your feedback by either commenting on this blog post or sending us information via Send a Smile.
Some of you have recently noticed that your install of the Visio Viewer isn’t working – this is by design and can easily be fixed. Microsoft has recently released Security Bulletin MS09-55 through Windows Update which deactivates Visio Viewers 2002, 2003 and 2007 because of a security issue. With this fix we are retiring Visio Viewer 2002 as well as Visio Viewer 2003. To get your viewer installation back into a working state you have 2 options:
The patching discussed in method #2 can also be done through Windows Update but may involve multiples runs of Windows Updates to download the relevant patches – downloading these patches directly is the most efficient way of getting the Viewer back into action.
If you have more questions about patching your viewer installation, feel free to leave a comment on our blog.