Chapter 5. Developing a Validation API Interface

Microsoft Visio 2010 does not provide a user interface to the Validation API that rules developers can use, so this chapter is devoted to building a useful tool to enable the tasks to be performed easily. The tool will enable you to review and amend existing rules, to create new rules, and to even perform tests on rules.

Don't worry if you are not a C# coder, because the completed tool is available from the companion website http://www.visiorules.com. However, I will lead you through the development of this tool in this chapter because it introduces you to using C#, rather than VBA that was used in the previous chapters.

This chapter will also describe how to use this tool, so it should be worth reading through, even if you are not a C# coder. It will cover the following topics:

• The architecture of the tool—a VSTO add-in with a WPF UI

• The ThisAddin class—listening for Visio application events and checking the Visio edition

• Creating the ViewModel...

The architecture of the tool

This tool is developed using Microsoft Visual Studio 2010, using C# and .NET Framework 4. This means that it can be developed as a Visio 2010 Add-in using VSTO 2010. This will make deployment simple using ClickOnce, because once it has been installed it will periodically check to see if there is an updated version available.

I have called the project ValidationExplorer, and it will be extended in later chapters to provide enhanced capabilities.

I decided to use Windows Presentation Foundation (WPF) to create the UI elements wherever possible because it has become my preference over the last few years. Visio is a COM application, therefore the WPF elements have to be hosted within a WinForm control. The effort is worth it though, because of the superior data-binding and UI element flexibility.

Programming in WPF promotes the adoption of a data-driven model, rather than the event-driven model more common in WinForm applications. A programming guide pattern called...

ThisAddin class

The ThisAddin_Startup() event is a good place to test for the correct Visio version and edition, along with checking that the Visio application events are indeed enabled, otherwise this add-in will not work properly anyway.

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
try
{
veApplication.VisioApplication = this.Application;
/* check prereq's */
// check for Visio >= 2010 and Edition >= PRO
if (!this.IsVisio14PremiumInstalled)
{
MessageBox.Show(
"This add-in requires the Premium edition of Visio 2010", "Visio Premium edition required", MessageBoxButton.OK, MessageBoxImage.Exclamation);
return;
}
// events must be enabled
if (!Convert.ToBoolean(Globals.ThisAddIn.Application. EventsEnabled)) // -1 is TRUE, 0 is FALSE, typically anything other than 0 is TRUE
{
if (MessageBox.Show(
"Event are currently disabled, this add-in requires events to be enabled. Would you like to enable events now?",
"Rules Tools", MessageBoxButton.OKCancel, MessageBoxImage...

Creating the ViewModel

I created new classes to mirror the relevant parts of the Visio Type Library objects, and all of the Validation API objects and collections. I prefixed these wrapper classes with VE for ValidationExplorer, which is the project name.

Note

When you select a folder in the Solution Explorer, then select Project, Add Class, and so on, Visual Studio will automatically append the folder name to the namespace of the class.

As the Visio objects are COM objects, you cannot bind to them directly because XAML really needs to bind to dependency objects that can notify the UI of any changes that take place.

Therefore, I created a BaseViewModel abstract class that implements the System.ComponentModel.INotifyPropertyChanged interface, which will notify the client when property values are changed.

All of my wrapper object classes implement this base class. The wrapper collections implement the System.Collections.ObjectModel.ObservableCollection<T> class because this will provide...

Modifying the Visio Fluent UI

The Fluent UI is new in Visio 2010 so, at last, Visio is sharing the same UI objects as the big three in Office (Word, Excel, and PowerPoint). This means that there are a lot more relevant resources available on the Web for developers to refer to. Before Microsoft bought Visio in 1999, the Visio application had its own UIObject API, which provided a programming model for menus, toolbars, the status bar, and accelerator keys. One of the first changes to be made, after the Microsoft acquisition, was the adoption of the Microsoft Office CommandBars API in Visio. This meant that developers could start using the same UI objects as other Office developers. But then the big three Office applications got the new Ribbon in the 2007 version. This is now improved and commonly called the Fluent UI, so even though the legacy UI objects may still be available in the Visio type library, it is recommended that developers get to grips with the Ribbon object.

One of the good...

Creating the Rules Explorer window

The Rules Explorer Window is a Visio anchor window, for which there are many examples available, including some in the Microsoft Visio SDK. The resultant window is a sub-window of the document window, just like a number of other built-in windows like the Drawing Explorer, Shape Data window, and of course, the new Issues window. These windows can float free, anchored to an edge of the drawing window, or merged with other sub-windows.

The following screenshot of Visual Studio shows that the FormExplorer class merely acts as a host for the UserControlExplorer control.

The UserControlExplorer is the WPF control that contains all of the goodies, and contains some code behind.

The Document Outline shows that very little is defined directly within the TreeViewMain element because it calls on templates defined in the Resources.

Self-describing tree views

I wanted the tree view to display the open documents, their rule sets, and the rules within them. This is...

Displaying the rule for a selected issue

The built-in Issues window, which is opened from the Diagram Validation group on the Process tab, provides an existing method for a user to select an issue. Therefore we can synchronize the selected rule in the Rules Explorer whenever an issue is selected. This enables the rules developer to analyze the expressions used.

Actually, the Issues window does not cause any events at all, but it does select the target shape or page whenever an issue is selected in the window.

Thus, we can use the Application.Window_SelectionChanged() event to test if the Issues window is open. If it is, then the selected issue ID is sent into the veApplication.SetSelectedIssue() method.

private void Window_SelectionChanged(Visio.Window Window)
{
//Check the selected Issue
Visio.Window winIssues = Window.Windows.get_ItemFromID( (short)Visio.VisWinTypes.visWinIDValidationIssues);
if (winIssues.Visible == false)
{
selectedIssueID = -1;
veApplication.SetSelectedIssue(Window...

Displaying the issues for the current selection

The Selection Issues button opens a dialog that contains just the issues for the selected page or shapes. If there are multiple issues on the page, or on a shape, then they are grouped together for clarity.

I have already expressed a preference to use WPF where possible. However, the VSTO template, which is a Windows Forms project, hides the WPF window item type from selection if you try to add one. You are only offered the User Control (WPF) to add in the WPF category of installed templates. Fortunately, you can select this option and then make some simple changes to the code to turn a User Control (WPF) into a Window (WPF). In this case, I added a new UserControl (WPF) named WindowIssues. I then edited the XAML of the WindowIssues.xaml file.

From:

<UserControl x:Class="ValidationExplorer.UI.WindowIssues"
…etc
</UserControl>

To:

<Window x:Class="ValidationExplorer.UI.WindowIssues"
…etc
</Window>

Similarly, I edited the WindowIssues...

Summary

In this chapter we started to develop a Visio 2010 Add-In that enables the rules developer to analyze what rules have been transgressed to cause any particular issue. We have provided an interface that allows the rules developer to add, copy, paste, modify, and delete rule sets and rules.

In the next chapter, we are going to extend the add-in to provide an export of rules to XML, and to a report so that the rules can be reviewed. We will provide an import of rule sets from the XML files that we created. Finally, we will also create annotations for issues in Visio so that the diagrams can be viewed with corresponding issues to assist the rules developer in analyzing the reason for failing validation.