Visio Insights
The official blog of the Microsoft Visio product team

  • Visio Insights

    Online SDK Documentation for Visio and Visio Services

    • 6 Comments

    Visio 2010 SDK Developer Documentation

    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.

    • Automation Reference: Provides an overview of Automation in Visio. It includes information about the Visio Object Model, the Visio type library, and extending the functionality of Visio by using macros, add-ons, and COM (Component Object Model) add-ins. A sample Visual Basic for Applications (VBA) macro is also provided. This reference provides details on Visio objects, properties, methods, and events.
    • Save as Web Reference: Provides an overview of using the Save as Web API with Visio 2010. Details about the Save as Web methods, objects, enums, and properties are provided. The reference also provides a Microsoft Visual Basic example of using the Save as Web Object Model.
    • ShapeSheet Reference: Provides an overview of the ShapeSheet spreadsheet in Visio. The reference includes information about working with formulas, strings, date and time values, units of measure, and information about common ShapeSheet tasks, such as adding and deleting ShapeSheet sections and referencing cells from formulas. It also includes details about each section, row, and cell in a ShapeSheet, and details about ShapeSheet functions.
    • Viewer Reference: Provides an overview of the API for Microsoft Visio 2010 Viewer, which is an ActiveX control that lets you open, view, or print Visio drawings, even if you do not have Visio 2010.
    • XML Schema Reference: Provides an overview of XML for Visio. Detailed information is provided for the XML for Visio schema, inheritance, working with sheets and formulas, geometry, text, loading XML files created outside Visio, round-tripping XML data, embedding custom XML data, units of measure, and errors and warning messages.

    Visio Services Developer Documentation in the Microsoft SharePoint 2010 SDK

    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.

    • Visio Services ECMAScript API: The ECMAScript object model in Visio Services gives you programmatic access to Visio drawings displayed in the Visio Web Access Web Part. We commonly refer to this API as the Visio Services JavaScript Mashup API. The Microsoft SharePoint SDK contains an overview article outlining the various API members, a detailed API member reference for the Vwa namespace , a technical article explaining how to embed code into web part pages as well as some samples showing best practices for programming against the Visio Web Access Web Part.
    • Visio Custom Data Providers: Custom Data Providers permit you to programmatically refresh data derived from custom data sources in Visio 2010 Web drawings hosted on a Microsoft SharePoint Server 2010 site. The Microsoft SharePoint SDK contains an overview article as well as a detailed API member reference for the Microsoft.Office.Visio.Server namespace: these can be used together to build your own custom Visio Services data providers.

    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.

  • Visio Insights

    Visio 2010 is Available Today!

    • 8 Comments

    image

    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.

  • Visio Insights

    Visio Services Capacity Planning White Paper

    • 0 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.

  • Visio Insights

    More Details About Visio Services Custom Data Providers

    • 0 Comments

    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.

    As usual, please comment on the blog if you have any questions or comments to share.

  • Visio Insights

    Visualizing Operations Manager Data in Visio Services

    • 4 Comments

    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.

    image

    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.

    image 

    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!

  • Visio Insights

    Visio 2010 Now Available for Businesses

    • 0 Comments

    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:

    Get Microsoft Silverlight

    Get Microsoft Silverlight

    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.

  • Visio Insights

    Visio 2010 SDK and Visio 2010 Viewer available for download

    • 1 Comments

    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!

  • Visio Insights

    Visio 2010 – Changes from Beta to RTM

    • 5 Comments

    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.

     

    Including all 6 drawing tools on the Home tab

    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.

    Drawing Tools

     

    Entry point to Line dialog from Line dropdown menu

    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.

    Line Options

     

    Changes to Save to SharePoint user interface

    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.

    Save to SharePoint

     

    Formatting overrides are preserved when pasting a shape into a themed document

    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.

     

    Support for context menu customization through RibbonX

    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.

     

    Summary

    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.

  • Visio Insights

    Visio 2010 Release to Manufacturing

    • 4 Comments

    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.

    Ease of Use

    Process Management

    Visio Services

    Office Fluent User Interface

    Visio Application Enhancements

    Diagramming Improvements

    Technical Reference

    Flowcharting

    Structured Diagrams

    SharePoint Server 2010 Integration

    Technical Reference

    Diagram Publishing, Rendering and Data Refresh

    Technical Reference

    As always, please continue to let us know what you think or want to hear more about.

  • Visio Insights

    Visio 2010 Editions

    • 34 Comments

    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!)

    image image image
    Visio Standard 2010
    Simplify complexity with a diverse set of intuitive and professional tools for diagramming.
    Visio Professional 2010
    Bring your diagrams to life with dynamic, data-driven visuals that are connected to real-time data and can be easily shared online with anyone.
    Visio Premium 2010
    Improve consistency and accuracy across your organization with advanced diagramming and new process management tools.

     

     

     

    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.

    Which edition is right for you?

    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:

    • Visio Standard 2010 brings a brand new look with the incorporation of the Office Fluent User Interface and the redesigned Shapes Window. New features like Quick Shapes, Auto Align & Space, and easy insertion and deletion of shapes make creating and maintaining diagrams even easier. With the new containers and callouts, it’s easy to organize diagrams and make them look great. In addition to the new features that work with all diagram types, the improved cross-functional flowcharting template included in Visio Standard 2010 is designed to be simple, scalable, and reliable.
    • Visio Professional 2010 builds on top of Visio Standard 2010’s great diagramming features by allowing you to connect your diagrams to data and to publish them to Visio Services. With Visio Services, you can view refreshable data-driven diagrams in SharePoint, even if you don’t have Visio installed. The Professional edition also includes advanced diagram templates like Detailed Network diagrams, Engineering diagrams, Wireframe diagrams, and Software and Database diagrams.
    • Visio Premium 2010 includes all the features of Visio Professional 2010 and adds advanced process management features like new diagram templates for SharePoint workflows, Business Process Modeling Notation (BPMN), and Six Sigma. SharePoint workflow diagrams can be exported into SharePoint Designer 2010 and further customized. The Subprocess feature allows you to break up your processes into manageable and reusable pieces. With diagram Validation, you can ensure that your diagrams are properly constructed. Visio Premium 2010 integrates with SharePoint Server 2010 to provide a process repository for centralized storage of process documents.

    The main functionality differences between the three editions are summarized in the table below:

     

     

    Visio Standard 2010

    Visio Professional 2010

    Visio Premium 2010

    Ease of Use Features

    • Microsoft Office Fluent UI
    • Quick Shapes and Mini Toolbar
    • Page Auto Size
    • Auto Align & Space
    • Dynamic Grid
    • Improved Cross-Functional Flowchart

    And too many more to list!

    image image image

    Visio Services and Data Features

    • Publishing to Visio Services*
    • Data Link functionality
    • Data Graphics
    • Data Graphics Legend
      image image

    Advanced Diagram Templates

    • Detailed Network Diagrams
    • Engineering Diagrams
    • Software and Database Diagrams
    • Wireframe Diagram template
    • ITIL Diagram template
    • Website mapping and documentation diagrams
    • Building architecture and service diagrams
      image image

    Advanced Process Management Features

    • SharePoint® Workflow Template
    • BPMN Template
    • Six Sigma Template
    • Diagram Validation
    • Subprocess
    • Validation and Validation API
        image

    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.

  • Visio Insights

    Improved CAD Support in Visio 2010

    • 12 Comments

    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.

  • Visio Insights

    Visio 2010 Release Dates

    • 0 Comments

    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.

    • For businesses, Visio 2010 and the rest of the Office 2010 products will be available worldwide on May 12th.
    • For consumers, Office 2010 and Visio 2010 will be available online and on retail shelves this June. Until then, you can get the Visio 2010 Beta here

    Office 2010 Technology Guarantee

    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:

    • Purchase Office 2007 (or Visio 2007), or a new PC with Office 2007, and activate it between March 5, 2010 and September 30, 2010.
    • Have, or create a Windows Live ID.
    • Redeem your Tech Guarantee before October 31, 2010 by visiting www.office.com/techg .

    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.

  • Visio Insights

    Visio Services: Details for Administrators

    • 0 Comments

    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.

    image

    Overview

    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.

    Extensibility

    There are several ways in which you can build on top of Visio diagrams with Visio Services:

    • Visio web drawings can be used as the basis for visual mash-ups. You can build code free mashups using Web Part Connections , or you can use the JavaScript API to create custom mashups.
    • Visio Services supports OLEDB or ODBC data sources. The driver for the data source must be installed on every application server that is running Visio Services, and it must be a trusted data provider. When using Visio client to create the Web Drawing that contains the data connection to the data source, the machine used must also have the driver installed.
    • You can write custom data providers to connect to any data source. Custom data providers need to be implemented as .NET assemblies that accept connection strings and return data as ADO.NET data sets. Look for a blog post next week with more information about custom data providers!

    Service Administration

    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.

    Connecting to Data

    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:

    • Microsoft SQL Server
    • Excel Services (Excel workbooks stored on a SharePoint Server 2010 that is running Excel Services)
    • SharePoint lists
    • OLEDB or ODBC connections
    • Custom Data Providers implemented as .NET Framework assemblies

    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.

    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.

    Documentation

    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.

  • Visio Insights

    New Visio 2010 API for Configuring Raster Export

    • 4 Comments

    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:

    image

    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:

    Methods

    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.

     

    Properties

    Name

    Description

    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.

    Example

    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"

    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.

  • Visio Insights

    User Interface Extensibility in Visio 2010

    • 3 Comments

    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.

    clip_image001

    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:

    clip_image003

    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.

    clip_image005

    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

    Do try implementing your own Visio ribbon and send us feedback through the Send a Smile feedback tool or comment on this post!

  • Visio Insights

    The Visio Services JavaScript Mashup API

    • 11 Comments

    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.

    Overview of the Visio Services JavaScript Mashup API

    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:

    • Interacting with web page elements that don’t expose web part connections.
    • Creating visual markup on the Visio drawing canvas.
    • Writing custom handlers for mouse events within the drawing.
    • Exposing diagram data, such as shape name and shape data, to your solution.
    • Combining data from inside and outside a diagram to build dynamic composite mashups.

    Objects

    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.

    image 

    Events

    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:

    image

    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.

    Getting Started

    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. Create a drawing in Visio and publish it to SharePoint document library as a VDW file.
    2. Create a .JS file in any JavaScript editor and copy paste the following contents into it. Once you're done save it to the same document library as the drawing in step #1.
         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>
    3. Edit the SharePoint page that will host the mash-up and add a Visio Web Access web part and configure it to load the web drawing published in step #1.
    4. On the same page, add a Content Editor Web Part and configure it to load the .JS file you created in step #2. This process is similar to step 3, however the Content Editor web part is in the Media and Content category of SharePoint web part picker and you need to set the "URL" property of the web part.
    5. Get out of page edit mode. Check the bottom left corner of your browser. If there is no JavaScript error, move to step 8. If there is however, you need to update the second line of the code snippet above which reads “var webPartElementID = "WebPartWPQ3";” with the ID that SharePoint gave to the Visio Web Access web part.
    6. Open the SharePoint web part page in source mode (in IE, right click and “View Source”) and search for class="VisioWebAccess",then back track to the immediate parent <div> tag and look for an attribute of the form id="WebPartWPQ?".
    7. Once you have this ID, replace it in the JS file and save it back to the document library
    8. Reload your mash-up page.

    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.

    Example #1: Overlays on hover

    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.

    image

    Key JavaScript API Capabilities Used in this Solution

    Capability In this example…
    Creating dynamic visual markup on the Visio drawing canvas. Product pictures take up a lot of screen real-estate -- you can't show all of them on the drawing without hiding the floor plan. Using overlays let you "fade them in" and "fade them out" as needed.
    Writing custom handlers for mouse events within the drawing. The fade-in and fade-out feature discussed above requires you to handle the onmouseenter and onmouseleave events.
    Combining data from inside and outside a diagram to build dynamic composite mashups The best-selling product on a shelf changes daily and is stored in the document. The product is stored outside the diagram. The mash-up must be able to pull these two sources of visual data into one diagram.

    Code

    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: }

    Getting this to work

    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:

    1. There are shapes in the drawing with the shape data whose label is "Best Seller" and whose value is "product?" (where ? is A, B etc...).
    2. You have bitmap images of these products, named productA.jpg etc... stored in the same directory as the .JS file. They should be 50 pixels wide and 70 pixels high.

    Example Scenario #2: Search and Highlighting...

    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.

    clip_image002

    Key JavaScript API Capabilities Used in this Solution

    Capability In this example…
    Interacting with web page elements that don’t expose web part connections. The search text box in this solution is not a SharePoint web part.
    Exposing diagram data, such as shape name and shape data to your solutions. The solution searches on data within the drawing.
    Combining data form inside and outside a diagram to build dynamic composite mashups Search text (data from outside the document) changes throughout a session, diagram markup must do so at the same rate.

    Code

    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();    
      35:         
      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;
      51:             }
      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:         }
      64:     
      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!");
      67:     }
      68: }

    Getting this to work

    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.

    Example #3: Workflow Visualization

    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.

    image

    As you can see, the integration between the Visio published diagram and the overlays is pretty seamless!

    More information to come…

    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.

    Try it out

    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.

    Appendix – API Reference

    Object

    Description

    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:

     

    image

     

    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:

    image

    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 Insights

    No Code Mashups with Visio Services and Web Part Connections

    • 6 Comments

    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.

    Filtering a Data Connected Diagram

    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:

    list filtering better 1 

    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:

    list filtering better 2

    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.

    Master/Detail View with Two Visio Web Access Web Parts

    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.

    master detail better 1

    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:

    master detail better 2

    Setting Up a Web Part Connection

    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.

    setup wpc 1

    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:

    setup wpc 2

    The following set of instructions show you how to setup the example described above with your own diagram:

    1. Publish your Visio diagram to Visio services (For detailed instructions, see this post)
    2. Create a new web part page and add the Visio Web Access web part. Choose the diagram you want to display. (For detailed instructions on this, see this post)
    3. Create a new custom list in SharePoint and add a new column called “Shapes to Highlight”. For column type, choose “Single line of text”.
    4. Create a new item in your list for each group of shapes you want to highlight. In the “Shapes to Highlight” field, enter a comma delimited list of the names of the shapes you want to highlight, with no spaces. E.g. “Process.1,Process.3,Process.4”.
      • You can find shape names by using the “Shape Information Pane” in the Visio Web Access web part. Selecting a shape will show you it’s shape name in the title of the pane
      • connect wpc 
    5. On the web part page, add the list view web part for the list that you created. The name of the list should show up as a web part.
    6. In the corner of the Visio Web Access Web Part, click the arrow to open the Visio Web Access Web Part Menu.
    7. Click Edit Web Part.
    8. In Edit Mode, click the arrow to open the Visio Web Access Web Part Menu again, point to Connections, choose “Get Shapes to Highlight From”, and then choose the list web part you added to the page in step 5.
      • connecting web parts
    9. The configure connection dialog will pop up, asking you to map a field from the “Provider” web part to a field in the “Consumer” web part. Visio Web Access is the consumer web part because it is receiving a list of shape names from the list view web part. Choose “Shape Names” for the consumer field, and “Shapes to Highlight” for the provider field (this is the column you created in step 3).
      • connect wpc2
    10. Click finish. Now your two web parts are connected, and when you select a row in your list web part, Visio will highlight the shapes that are specified in that row.

    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.

    Connection Options

    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.

    Send Shape Data To

    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:

    • Shape name
    • Shape ID
    • URL of the Web drawing
    • Name of the page that the selected shape is on.

    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.

    send shape data

    Get Web Drawing URL and Page Name From

    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:

    • Web Drawing URL: a URL for a web drawing (*.VDW file)
    • Page Name: a page name to load, e.g. “Page-1”

    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.

    Get Shapes to Highlight From

    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:

    • Shape Names: A comma-delimited list of names of shapes without spaces, e.g. “Process1,Process2,Decision3”
    • Highlight Color: A hexadecimal color code, e.g. “FF00FF”

    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.

    Get Filter Results From

    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.

    Get Shape to View From

    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:

    • Shape Name: the name of the shape to center the view on
    • Zoom Level: the zoom percentage to use

    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.

    Try it out!

    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:

    • Highlighting shapes in a process diagram based on owner. Use a list that identifies the owners and the shape names associated with it.
    • Create preset views of a large diagram, so users can select from a list. You might try using an InfoPath form as the provider web part.
    • Create a repository of Visio documents on one page using a document library. When users select a document, the Visio Web Access web part can display it.
    • Use a Visio diagram to drive Excel parameters or opening a related Excel spreadsheet in Excel Web Access.
    • Use a Visio diagram to pre-populate an InfoPath form.

    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.

  • Visio Insights

    Container, List and Callout API in Visio 2010

    • 4 Comments

    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.

     

    Structured Diagram API Overview

    Here are the key objects, properties and methods in the Structured Diagrams API:

    image

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

     

    Enabling Structured Diagram Behaviors in Solutions

    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:

    Enum Value Description
    visServiceAll -1 All diagram services
    visServiceVersion140 7 Diagram services that exist in Visio 2010
    visServiceNone 0 No diagram services (default)
    visServiceAutoSizePage 1 AutoSize page behaviors
    visServiceStructureBasic 2 Behaviors that maintain existing Structured Diagram relationships but do not create new relationships
    visServiceStructureFull 4 Structured Diagram behaviors that match the behaviors in the user interface

    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.

     

    Common Tasks with the Structured Diagram API

    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.

    Add a container to the page

    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

    Add a shape to a container

    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

    Find the containers on a page

    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

    Get the shapes in a container

    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

    Reorder a list

    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

    Add a callout to the page

    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

    Get the target shape for a callout

    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

    Structured Diagram Events

    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

    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.

     

    Feedback

    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.

  • Visio Insights

    SharePoint Workflow Authoring in Visio Premium 2010 (Part 2)

    • 11 Comments

    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:

    • Importing a workflow from SharePoint Designer
    • Customizing workflow visualization in Visio for presentation
    • Publishing Visio diagram visualization for workflow status tracking on SharePoint server

    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:

    clip_image002

    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:

    clip_image004

    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:

    clip_image006

    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:

    clip_image008

    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:

    clip_image010

    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:

    clip_image012

    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!

  • Visio Insights

    The Point Along Path ShapeSheet Functions in Visio 2010

    • 4 Comments

    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:

    Function/Syntax

    Description

    ANGLEALONGPATH(section,travel [,segment]) Returns the angle of the tangent to the path at a given point.
    DISTTOPATH(section,x,y) Returns the shortest distance from the point represented by the specified coordinates to a point on the path.
    NEARESTPOINTONPATH(section,x,y) Returns the percentage of the distance along the path of the point that is nearest to the specified coordinates, as a value between 0 and 1.
    PATHLENGTH(section[,segment]) Returns the length of the path that is defined in the specified Geometry section.
    PATHSEGMENT(section,travel) Returns the 1-based segment number at the specified percentage mark along the specified path.
    POINTALONGPATH(section,travel[,offset][,segment]) Returns the coordinates of a point on, or offset from, the path.
    SEGMENTCOUNT(pathRef) Returns the number of line segments that make up the path.

    In the above functions:

    • Arguments in brackets [ ] are optional
    • Section always refers to a Geometry path. The correct way to reference a geometry path section is to enter the section reference followed by “.Path” (for example, Sheet.1!Geometry2.Path)
    • Travel is a measure of the position along the path between the beginning and the end points, defined as a percentage. It is always represented by a number between 0 and 1, where 0 represents the beginning point, and 1 represents the end point
    • Segment is a 1-based index of a line segment in the path that corresponds to a row in the geometry section.

    To give you an idea of what you can do with these functions, we'll explore three examples.

    Adorning a Connector

    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:

    triangle

    To create this adornment, you only need a few ShapeSheet formulas:

    • First, make sure that the adornment shape will be ignored by the Visio routing engine. To do this, select the shape, and click "Behavior" from the Developer tab. In the ensuing dialog, click on the "Placement" tab, and ensure that placement behavior is set to "Do not lay out and route around".
    • Create a user cell in the adornment shape (we'll call it User.ConnectorGluePoint, and use the POINTALONGPATH() function and reference the connector that the shape will adorn:
      • POINTALONGPATH(Dynamic connector.23!Geometry1.Path,0.5)
      • This returns a point in local coordinates to the connector
    • Create another user cell, User.PageCoord, and use the LOCTOPAR() function to translate the local coordinates to page coordinates:
      • LOCTOPAR(User.ConnectorGluePoint,Dynamic connector.23!User.msvThemeColors,User.msvThemeColors)
      • The LOCTOPAR function needs cell references for the source and destination of the translation. Here we arbitrarily use User.msvThemeColors because the property exists in both the source and destination.
    • Now, set PinX,PinY, and Angle cells on the adornment shape accordingly (found in the Shape Transform section):
      • PinX: GUARD(PNTX(User.PageCoord))
      • PinY: GUARD(PNTY(User.PageCoord))
      • Angle: ANGLEALONGPATH(Dynamic connector.23!Geometry1.Path,0.5)-PI()/2
        • We subtract PI/2 because we’re using a triangle and the point is not aligned with the 0 angle. The ANGLEALONGPATH() function returns the tangent angle to the specified point on the path.

    Finding the Nearest Point on a Path

    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:

    nearest point

    Here’s how we setup the triangle to do this:

    • Create a user cell in the triangle shape to store the point of the circle shape (we’ll call it User.LocalPoint) Use the following formula to transform the LocPin point of the circle into local coordinates relative to the curve:
      • LOCTOLOC(PNT(Circle!LocPinX,Circle!LocPinY),Circle!Height,ArcLine!Height)
      • We use the PNT function to turn the LocPinX and LocPinY into a point
    • Create another user cell in the triangle (we’ll call it User.Travel) to store the percentage along the path (the travel) that is nearest to the circle. Use the following formula:
      • NEARESTPOINTONPATH(ArcLine!Geometry1.Path,PNTX(User.LocalPoint),PNTY(User.LocalPoint))
      • This returns the percentage along ArcLine!Geometry1.Path that has the nearest point to the center of the circle shape
    • Create another user cell (we’ll call it User.ArcGluePoint) to store the point along the path of the arc that is closest to the circle. Use the following formula:
      • POINTALONGPATH(Sheet.1!Geometry1.Path,User.Travel)
      • This will return the point on the arc where the triangle should be glued, in local coordinates relative to the arc.

    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.

    Curved Timelines

    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:
    curvy 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:

    • Placing text or adornments at fixed distances from the beginning or end of a connector
    • Detecting whether a point is inside or outside a closed path
    • Calculating the lengths of curved paths in a diagram
    • Drawing a line that terminates on a complex path

    As usual, please tell us what you think by using the Send a Smile feedback tool or by commenting on this post.

  • Visio Insights

    Custom Containers, Lists and Callouts in Visio 2010

    • 7 Comments

    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.

    SD Content examples

     

    Structured Diagrams

    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.

    msvStructureType

     

    Container Shape Details

    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.

    Cell Name Description
    User.msvSDContainerMargin Distance between container boundary and member shapes
    User.msvSDContainerResize Automatic resize behavior for shape (0 = No automatic resize; 1 = Expand as needed; 2 = Always fit to contents)
    User.msvSDContainerStyle 1-based index value for the current visual style of the container
    User.msvSDContainerStyleCount Total number of visual styles supported by the container
    User.msvSDHeadingStyle 1-based index value for the current visual style of the container heading
    User.msvSDHeadingStyleCount Total number of visual styles supported by the container heading
    User.msvSDContainerLocked Boolean value that prevents membership changes in the container
    User.msvSDContainerRequiredCategories Semi-colon delimited list of category names. Other shapes must have at least one matching name to be allowed as container members.
    User.msvSDContainerExcludedCategories Semi-colon delimited list of category names. Other shapes with at least one matching name are disallowed as container members.
    User.msvSDContainerNoHighlight Boolean value that suppresses the container highlighting when member shapes are selected or added to container
    User.msvSDContainerNoRibbon Boolean value that hides the Container Tools contextual tab in the Ribbon for this container
    User.msvSDContainerHeadingEdge String designating where the interior of the container is from the perspective of the container heading. Must be either “Left”, “Right”, “Top” or “Bottom”.
    User.msvSDMembersOnHiddenLayer Boolean value that determines whether Visio severs container relationships when the container or member is placed on a hidden layer.  If True, Visio allows relationships to exist on the hidden layer.  If False, Visio severs the relationships.

    Creating a visual style

    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.

    msvSDContainerStyle

    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.

    Controlling container membership

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

    Creating a heading sub-shape

    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.

    Showing custom shapes in the Insert Container gallery

    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.

     

    List Shape Details

    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.

    Cell Name Description
    User.msvSDListAlignment Determines how member shapes are aligned in list (0 = Left; 1 = Center; 2 = Right for vertical lists.  0 = Top; 1 = Middle; 2 = Bottom for horizontal lists.)
    User.msvSDListDirection Direction that list arranges member shapes (0 = Left to Right; 1 = Right to Left; 2 = Top to Bottom; 3 = Bottom to Top)
    User.msvSDListSpacing Distance between list members
    User.msvSDListItemMaster Name or UniqueID of master shape to instance on Insert commands.  Value must be placed inside a USE() function.
    User.msvSDListNoReorder Boolean value that prevents reordering of members.  The list must also be locked via User.msvSDContainerLocked = True for setting to have any effect.
    User.msvSDListRequiredCategories Semi-colon delimited list of category names. Other shapes must have at least one matching name to be allowed as list members.
    User.msvSDListExcludedCategories Semi-colon delimited list of category names. Other shapes with at least one matching name are disallowed as list members.

    Specifying a shape to insert into lists

    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)

    Controlling list membership

    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.

     

    Callout Shape Details

    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.

    Cell Name Description
    User.msvSDCalloutNoHighlight Boolean value that suppresses the highlighting on the callout target shape
    User.msvSDTargetIntersection Location in page coordinates of the intersection between the geometric boundary of the target shape and a virtual line drawn from the center of the callout to the center of the target shape. This is a read-only cell set by Visio.

    Showing custom callout shapes in the Insert Callout gallery

    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.

     

    Summary

    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.

  • Visio Insights

    The Diagram Validation API

    • 2 Comments

    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.

    Validation API overview

    The key objects, methods and properties for validation are shown below.

    Validation API

    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.

    Key validation objects and properties

    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.

    ValidationRuleSet

    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.

    Property Description
    Description Specifies the description of the rule set.
    Enabled Determines whether the rule set is active or inactive. Only rules belonging to active rule sets are checked when validation is triggered. By default, rule sets are enabled.
    Name Specifies the name of the rule set that appears in the UI. By default, it is the same as NameU.
    NameU Specifies the universal name of the rule set.
    Rules Itemizes the rules in the rule set.
    RuleSetFlags Determines whether the rule set appears in the UI. By default, rule sets are visible through the UI.

    ValidationRule

    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.

    Property Description
    Category Represents the text displayed in the Category column of the Issues window.
    Description Specifies the description of the rule that appears in the Issues window.
    FilterExpression Specifies the logical expression that determines whether the validation rule should be applied to a target object.
    Ignored Determines whether the validation rule is currently ignored. By default, rules are not ignored.
    NameU Specifies the universal name of the rule.
    RuleSet Returns the rule set that contains the rule.
    TargetType Determines the target type of the rule. A rule can target documents, pages, or shapes.
    TestExpression Specifies the logical expression that determines whether the target object satisfies the rule.

    ValidationIssue

    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.

    Property Description
    Ignored Determines whether the issue is currently ignored.
    Rule Specifies the rule that generated the issue.
    TargetPage Specifies the page that is associated with the issue.
    TargetPageID Specifies the ID of the page that is associated with the validation issue.
    TargetShape Specifies the shape that is associated with the validation issue.

    Validation methods for adding rule sets and rules

    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.

    ValidationRuleSets.Add(NameU)

    Adds a new, empty ValidationRuleSet object to the ValidationRuleSets collection of the document.

    • NameU: The universal name to assign to the new validation rule set.

    ValidationRules.Add(NameU)

    Adds a new, empty ValidationRule object to the ValidationRules collection of the document.

     

    Example

    The following VBA code adds a rule set and a rule that targets a shape to the active document.

     

      Set vsoDocument = Visio.Activedocument
       
      'Add a validation rule set to the document
      Set vsoValidationRuleSet = vsoDocument.Validation.RuleSets.Add("Connectivity")
      vsoValidationRuleSet.Description = "Verify that shapes are correctly connected in the document."
      vsoValidationRuleSet.Enabled = True
      vsoValidationRuleSet.RuleSetFlags = Visio.VisRuleSetFlags.visRuleSetDefault
       
      'Add a validation rule to the document
      Set vsoValidationRule = vsoValidationRuleSet.Rules.Add(“Unglued2DShape”)
      vsoValidationRule.Category = "Shapes"
      vsoValidationRule.Description = "This 2-dimensional shape is not connected to any other shape."
      vsoValidationRule.Ignored = False
      vsoValidationRule.TargetType = Visio.VisRuleTargets.visRuleTargetShape
       
      'The validation function Is1D() returns a Boolean value indicating whether the shape is
      '1D (True) or 2D (False)
      vsoValidationRule.FilterExpression = "NOT(Is1D())"
       
      'The validation function GLUEDSHAPES returns a set of shapes glued to the shape.
      'It takes as input one parameter indicating the direction of the glue.
      'The direction values are equivalent to members of VisGluedShapesFlags:
      '0 = visGluedShapesAll1D and 3 = visGluedShapesAll2D
      'The validation function AGGCOUNT takes a set of shapes as its input, and returns
      'the number of shapes in the set.
      vsoValidationRule.TestExpression = "AGGCOUNT(GLUEDSHAPES(0)) + AGGCOUNT(GLUEDSHAPES(3)) > 0"

    Validation methods for managing issues

    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.

    ValidationRule.AddIssue([TargetPage],[TargetShape])

    Creates a new validation issue that is based on the validation rule, and adds it to the document.

    • TargetPage(Optional): The page that either has the issue or has the shape with the issue.
    • TargetShape(Optional): The shape that has the issue.

    ValidationIssue.Delete()

    Deletes the ValidationIssue object from the document.

     

    Example

    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.

      'Add a custom issue to the vsoValidationRule validation rule and associate it with
      'shape vsoShape on page vsoPage
      Set vsoValidationIssue = vsoValidationRule.AddIssue(vsoPage, vsoShape)
      vsoValidationIssue.Ignored = False

    Using the API to validate a document

    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.

    Validation.Validate([RuleSet As ValidationRuleSet], [Flags As VisValidationFlags])

    Validates the specified validation rule set.

    • RuleSet (Optional): The rule set to validate across the entire document.
    • Flags (Optional): Whether to open the Issues window after validation.

     

    Example

    The following VBA code validates all rule sets in the document and launches the Issues window.

      'Validate the document
      Call Visio.Activedocument.Validation.Validate(, Visio.VisValidationFlags.visValidationDefault)

    Defining ValidationRule.FilterExpression and ValidationRule.TestExpression

    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.

    Function Description
    Role() Returns an integer indicating the shape role: {Element = 0, Connector = 1, Container = 2, Callout = 4}.
    OnLayer(LayerName) Returns a Boolean indicating whether the shape is a member of the specified layer. Returns a Boolean indicating whether layer exists on page if called on a Page.
    ConnectedShapes(Direction) Returns the set of shapes, matching the Direction criteria, connected to the shape.
    GluedShapes(Direction) Returns the set of shapes, matching the Direction criteria, glued to the shape.
    ContainerMembers() Returns the set of shapes that are members of the container / list shape.
    ListMembers() Returns the set of shapes that are members of the list shape.
    Callouts() Returns the set of shapes that are callouts on the shape.
    ParentContainers() Returns the set of containers that the shape belongs to.
    ShapesOnPage() Returns the set of top-level shapes on page. If no page specifier precedes the function, the shape’s containing page is assumed.
    AggCount(Set) Counts the number of shapes in a set.
    FilterSet(Set,FilterExpression) Returns the subset of shapes in a set that match an expression.
    OnBoundaryOf() Returns the set of containers such that the shape is on the boundary of these containers.

    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.

    Feedback welcome!

    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.

  • Visio Insights

    New ShapeSheet Cells and Functions in Visio 2010

    • 2 Comments

    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.

    New Cells

    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:

    Section Cell
    Page Layout AvoidPageBreaks
    Page Properties DrawingResizeType

    New ShapeSheet cells in Visio 2010:

    Section Cell
    Shape Layout DisplayLevel
    Actions FlyoutChild
    Geometry NoQuickDrag
    Shape Layout Relationships

    Recall that you can view the PageSheet for a page or the ShapeSheet for a shape using the Developer tab.

    image 

    AvoidPageBreaks cell

    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.

    image

     DrawingResizeType cell

    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.

    image

    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.

    DisplayLevel cell

    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.

    image   image   image
    Start with these shapes, with the given DisplayLevel values   After pressing Bring to Front on the blue shape   After pressing Bring to Front on the blue shape again

    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.

    FlyoutChild cell

    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.

     image image

    If the value of FlyoutChild for B and C is TRUE, then those items appears in a flyout menu under A.

    image 

    NoQuickDrag cell

    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.

    Relationships cell

    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.

    Value Meaning
    1 Shapes that are members of this container
    2 Shapes that are members of this list
    3 Callouts that are associated with this shape
    4 Containers that this shape is a member of
    5 List that this list item is a member of
    6 Shape associated with this callout
    7 Container on the left boundary edge of which this shape sits
    8 Container on the right boundary edge of which this shape sits
    9 Container on the top boundary edge of which this shape sits
    10 Container on the bottom boundary edge of which this shape sits
    11 List that this list overlaps

    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.

    New Functions

    We also added ShapeSheet functions that enable new developer scenarios, particularly for integrating with new Visio 2010 features.

    Containers and Lists

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

    Function Description
    CALLOUTTARGETREF() Returns a Sheet reference to the target shape that this callout is associated with
    CONTAINERSHEETREF(index, category) Returns a Sheet reference to the container shape that this shape is a member of
    -- The 1-based Index parameter specifies which parent container to return, where the topmost container is ordered first
    -- If category is specified, the container must have that category in order to be returned
    LISTSHEETREF() Returns a Sheet reference to the list container shape that this shape is a member of

    The following functions return the number of associated shapes.

    Function Description
    CALLOUTCOUNT() Returns the number of callout shapes associated with the shape
    CONTAINERCOUNT() Returns the number of containers the shape is a member of
    CONTAINERMEMBERCOUNT() Returns the number of member shapes in the container shape
    LISTMEMBERCOUNT() Returns the number of member shapes in the list container shape

    The following functions  

    Function Description
    HASCATEGORY(string) Returns TRUE if the specified string is found in the shape's categories list
    LISTORDER() Returns the 1-based order for the shape within a list

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

    image 

    Geometry Paths

    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.

    Function Description
    ANGLEALONGPATH(section, percent, segment) Returns the tangent angle of a point on the path defined in a geometry section
    DISTTOPATH(section, x, y) Returns the shortest distance from the specified coordinates to a point on the path defined in a geometry section
    NEARESTPOINTONPATH(section, x, y) Returns the point along the path defined in a geometry section that is nearest the specified coordinates
    PATHLENGTH(section, segment) Returns the length of the path defined in a geometry section
    PATHSEGMENT(section, percent) Returns the 1-based segment number containing a point on the path defined in a geometry section
    POINTALONGPATH(section, percent, [offset], [segment]) Returns the coordinates of a point on or offset from the path defined in a geometry section
    SEGMENTCOUNT(section, percent) Returns the number of line segments that make up the path defined in a geometry section

    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.

    Miscellaneous

    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.

    Function Description
    BOUNDINGBOXDIST(index) Returns the measurement for the part of the shape's bounding box specified by the Index enumeration
    BOUNDINGBOXRECT(index) Returns the coordinate of an edge of the shape's bounding box specified by the Index enumeration
    IS1D() Returns TRUE if the shape is one-dimensional
    SHEETREF() Returns a Sheet reference for the specified shape
    IFERROR(expression, altExpression) Returns the evaluated result of the expression if it is not an error; otherwise returns the evaluated result of the alternate expression
    MSOSHADE(color, deltaLum) Modifies the color by decreasing its luminosity by the amount specified
    MSOTINT(color, deltaLum) Modifies the color by increasing its luminosity by the amount specified
    VERSION() Returns an integer value matching the current version of the Visio application

     

    Index enumeration for BOUNDINGBOXDIST:

    Value Meaning
    0 Width
    1 Height
    2 Left edge to shape pin
    3 Shape pin to right edge
    4 Shape pin to top edge
    5 Bottom edge to shape pin
    6 Center of bounding box to PinX
    7 Center of bounding box to PinY

    Index enumeration for BOUNDINGBOXRECT:

    Value Meaning
    0 Left edge
    1 Right edge
    2 Top edge
    3 Bottom edge

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

    • DATA1, DATA2, DATA3
    • ID
    • MASTERNAME
    • NAME
    • PAGENAME, BKGPAGENAME
    • PAGENUMBER, BKGPAGENUMBER
    • TYPE, TYPEDESC

    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.

  • Visio Insights

    ShapeSheet Formula AutoComplete & Other Improvements

    • 1 Comments

    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:

    image

    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.

    ShapeSheet Formula AutoComplete

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

    image

    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.

    image

    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.

    image

    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.

    image

    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.

    image

    ShapeSheet Formula AutoComplete is available in the following textboxes, dialogs and windows throughout Visio 2010:

    • In a ShapeSheet cell
    • In the ShapeSheet formula edit bar
    • In the new “Edit Formula” dialog which you can launch from the ShapeSheet contextual tab
    • In the “Insert Field” dialog, when typing in a custom ShapeSheet formula
    • In the “Edit Data Graphics” dialog, wherever you have the opportunity to add a custom ShapeSheet formula.

    The ShapeShee Formula AutoComplete feature can be toggled off through one of these entry points:

    • Toggling the relevant option in the “Visio Options”>“Advanced” dialog.
    • Toggling the value of the Software\Policies\Microsoft\Office\14.0\Visio\Application\EnableFormulaAutoComplete registry key.
    • Toggling the value of Application.Settings.EnableFormulaAutoComplete API property.

    ShapeSheet Contextual Tab

    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.

    image

    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

    Insert

    Adds a row to the optional section you have currently selected.

     

    Delete

    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.

    image

    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.

    Also…

    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.

    Try it out!

    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.

  • Visio Insights

    Updates Regarding the Visio Viewer

    • 8 Comments

    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:

    1. If you can, we recommend that you install the Visio 2010 (Beta) viewer; this version of the viewer has all the functionality of the previous viewers, includes all the required security fixes, and has a product quality that is very close to ship. This build of the viewer can then easily be upgraded to the RTM build of the Viewer when it’s released.
    2. If you can’t or don’t want to download the Visio 2010 (Beta) viewer, you must update your existing viewer by following the steps in the order described below:
      1. If you’re using Viewer 2002 or Viewer 2003, uninstall it and install Visio 2007 Viewer.
      2. Install Visio Viewer 2007 SP1
      3. Install Visio Viewer 2007 SP2
      4. Install the security update KB973709

    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.

Page 2 of 8 (181 items) 12345»