Chapter 4. Understanding the Validation API

The Validation API is new in Visio 2010 Premium edition, and provides the opportunity to create diagramming rules. These rules can help eliminate common errors and enable companies to enforce diagramming standards.

In the first chapter, we had an overview of the user interface of the Diagram Validation group on the Process tab, and a quick look at the elements in XML format. In this chapter we will explore the objects, collections, and methods in the Validation API.

Overview of the Validation objects

The Validation object model is accessed from the Visio Document object. The Validation object is only available if the code is running in Visio Premium edition, so you should check the edition, as described previously in Chapter 2.

The Validation object contains two collections, Issues and RuleSets, which leads you to the main areas of the API.

The ShowIgnoredIssues property merely dictates whether or not the Issues window displays ignored issues...

Overview of the Validation objects

The Validation object model is accessed from the Visio Document object. The Validation object is only available if the code is running in Visio Premium edition, so you should check the edition, as described previously in Chapter 2.

The Validation object contains two collections, Issues and RuleSets, which leads you to the main areas of the API.

The ShowIgnoredIssues property merely dictates whether or not the Issues window displays ignored issues. If the user selects to show ignored issues, then they are shown as grayed out.

The following DebugPrintValidation macro will display the detail of the validation object, but notice that you have to delve into the Issues, Issue, and Rule objects to retrieve the count of ignored issues, as displayed in the UI. In fact, an issue can be ignored individually, or by virtue of its rule being marked as ignored.

Public Sub DebugPrintValidation()
Debug.Print "DebugPrintValidation"
Dim ignoredIssues As Integer
With Visio...

The ValidationRuleSets collection

Validation Rules are grouped within ValidationRuleSets. The UI provides the ability to import a rule set from another open Visio document, but the programmer can use the Add(NameU as String) or AddCopy(RuleSet as ValidationRuleSet[, NameU]) methods to create a new one.

You can retrieve a rule set by its index position in the collection, using ValidationRuleSets.Item(index), or by its ID using ValidationRuleSets.ItemFromID(ID). Once you have retrieved a rule set, you can read its Name (which can be edited to be a localized version), NameU, Description (which is displayed as the tooltip in the UI), or check if the RuleSets is enabled for validation.

The RuleSetFlags value determines if the rule set is visible in the Rules to Check drop-down in the UI.

The default value is 0 (VisRuleSetFlags.visRuleSetDefault), but you could change it to 1 (VisRuleSetFlags.visRuleSetHidden) if you do not want it to appear in the Rules to Check menu.

The following macro, EnumerateRuleSets...

The ValidationRules collection

Once you have a rule set you can review, amend, or add to the rules within it. You can add a rule using the ValidationRules.AddRule(NameU as string) method. Note that the NameU is really for use in code, since it is the Description property that is displayed in UI. The NameU must be unique within the Rules collection of the parent ValidationRuleSet.

You can retrieve a rule by its index position in the collection, using ValidationRules.Item(index), or by its ID using ValidationRules.ItemFromID(ID). Once you have retrieved a ValidationRule you can read its NameU and Description, or check if the rule set is ignored for validation.

Public Sub EnumerateRules()
Dim doc As Visio.Document
Dim ruleSet As Visio.ValidationRuleSet
Dim rule As Visio.ValidationRule
Set doc = Visio.ActiveDocument
For Each ruleSet In doc.Validation.RuleSets
If ruleSet.Enabled Then
Debug.Print "EnumerateRules for RuleSet : " & _
ruleSet.nameU & " : Count = " & _
ruleSet.Rules.Count...

ValidationIssues

The ValidationIssues collection stores the issues created by the Validation.Validate([RuleSet as ValidationRuleSet][, Flags as ValidationFlags]) method and by the RuleSet.AddIssue([TargetPage as Page][,TargetShape as Shape]) method. It can be reset using the Clear() method, which will also zero the LastValidatedDate of the parent Validation object.

Most issues are automatically created by the Validate() method, but you can write code to add issues whenever the user clicks Check Diagram against a particular rule set. You would do this by listening to the RuleSetValidated(RuleSet as ValidationRuleSet) event of the Application, Documents, or Document object. This technique is used by the Microsoft SharePoint Workflow template in Visio 2010.

You can enumerate the current issues in a document, and check which rule has been transgressed.

Public Sub EnumerateIssues()
Dim issue As Visio.ValidationIssue
Dim shpName As String
Dim doc As Visio.Document
Set doc = Visio.ActiveDocument...

Summary

In this chapter, we have examined the Validation API, and seen how we can review or create rule sets and rules. We have also seen how rules can be validated to create issues automatically, or how issues can be created in code as the result of custom validation code.

In the next chapter, we are going to start building a Visio VSTO 2010 add-in that we can use to analyze existing rules, or create new ones more easily. We are also going to switch from VBA to using C# in Visual Studio 2010, so that you can have a proper development tool to use.