Visio 2010 Developer Training 03 - Programming With The Visio Object Model

Microsoft Visio 2010 Developer
Training
Volume 3: Programming with the Visio Object
Model
1
Microsoft Visio 2010 Developer Training
2010 Microsoft Corporation. All rights reserved.
Volume 3: Programming with the Visio Object Model
DISCLAIMER
Microsoft, Internet Explorer, and Windows are either registered trademarks or trademarks of
Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
THE CONTENTS OF THIS PACKAGE ARE FOR INFORMATIONAL AND TRAINING PURPOSES ONLY AND ARE PROVIDED "AS IS"
WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
No part of the text or software included in this training package may be reproduced or transmitted in
any form or by any means, electronic or mechanical, including photocopying, recording, or any
information storage and retrieval system, without permission from Microsoft. Because Microsoft must
respond to changing market conditions, it should not be interpreted to be a commitment on the part of
Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of
publication. The names of actual companies and products mentioned herein may be the trademarks of
their respective owners.
To obtain authorization for uses other than those specified above, please visit the Microsoft Copyright
Permissions Web page at http://www.microsoft.com/about/legal/permissions
This content is proprietary and confidential, and is intended only for users described in the content
provided in this document. This content and information is provided to you under a Non-Disclosure
Agreement and cannot be distributed. Copying, disclosing all or any portion of the content and/or
information included in this document is strictly prohibited.
2
Table of Contents
VBA Primer .................................................................................................................................................. 10
Event Driven vs. Procedure Based Programming ....................................................................................................11
Visual Basic Editor ...................................................................................................................................................12
Variables ..................................................................................................................................................................15
Dimensioning ...........................................................................................................................................................16
Data Types ...............................................................................................................................................................18
Using Hungarian Notation ...................................................................................................................................20
Manipulating Variables............................................................................................................................................21
Exercise 1 .................................................................................................................................................................23
Other Operations.....................................................................................................................................................25
Exercise 2 .................................................................................................................................................................27
Data type conversions and variable scope ..............................................................................................................29
Exercise3 ..................................................................................................................................................................31
Constants .................................................................................................................................................................33
Control structures....................................................................................................................................................34
Branching Statements .........................................................................................................................................34
Looping Statements ............................................................................................................................................36
Jumping Statements ............................................................................................................................................37
Procedures ..........................................................................................................................................................38
Functions .............................................................................................................................................................38
VBA Primer Conclusion ............................................................................................................................................40
Introduction to Automation........................................................................................................................ 41
Introduction.............................................................................................................................................................43
Automation Basics ...................................................................................................................................................44
Programming a Server's Objects .............................................................................................................................46
VBE Tools Menu ......................................................................................................................................................49
Object Browser ........................................................................................................................................................
3 51

Review: Introduction to Automation.......................................................................................................................52
Automation and Visio Technology .............................................................................................................. 53

Overview .................................................................................................................................................................54
The Visio Object Model ...........................................................................................................................................55
A Sample Visio Program ..........................................................................................................................................58
Getting and Setting Properties ................................................................................................................................60
Invoking Methods ....................................................................................................................................................62
Compound References ............................................................................................................................................64
Lab 3.1: Get the Name of an Open Visio Document................................................................................................65
Coding Issues ...........................................................................................................................................................66
Running Your Program ............................................................................................................................................68
RUNADDON(string) ..............................................................................................................................................70
CALLTHIS ..................................................................................................................................................................72
Where to Find Visio Automation Information .........................................................................................................73
Lab 3.2: Running VB Add-ons ..................................................................................................................................75
Review: Automation and Visio ...............................................................................................................................76
Generating Drawings .................................................................................................................................. 78

Creating a Document ...............................................................................................................................................79
Getting a Reference to the Master ..........................................................................................................................81
Dropping the Master on the Page ...........................................................................................................................82
Adding Text to Shapes .............................................................................................................................................84
Getting Formulas of Shapes and Pages ...................................................................................................................85
Getting a Formula or Its Result ................................................................................................................................87
Setting a Formula ....................................................................................................................................................89
Tips for Positioning Shapes......................................................................................................................................90
Tips for Positioning Shapes (Continued) ..................................................................................................................91
Connecting Shapes ..................................................................................................................................................92
Getting the Cell to Glue ...........................................................................................................................................93
Gluing to the Other Shape .......................................................................................................................................94
4 96
AutoConnect Mode .................................................................................................................................................
Adding Data to Shapes ............................................................................................................................................99

Adding Sections and Rows.....................................................................................................................................100
Lab 3.3: "Hello World" ...........................................................................................................................................101
Review: Generating Visio Drawings ......................................................................................................................102
Getting Data From Drawings..................................................................................................................... 104

Overview ...............................................................................................................................................................105
Iterating Through a Collection ...............................................................................................................................106
Getting Data from Documents ..............................................................................................................................108
Noteworthy Document Properties ........................................................................................................................109
Getting Data from Pages .......................................................................................................................................111
Getting Data from Shapes .....................................................................................................................................112
Getting Data About Connections ...........................................................................................................................113
Connect Object for a Control Handle to a Shape ..................................................................................................115
Connect Object for a 1-D Between 2-D Shapes .....................................................................................................116
More Connectivity API options ..............................................................................................................................118
Getting a Selection Object .....................................................................................................................................124
Working with Windows and Selected Shapes .......................................................................................................126
Getting Cells with CellsSRC ....................................................................................................................................128
Determining Shape Proximity ................................................................................................................................130
SpatialRelation.......................................................................................................................................................131
Lab 3.4: Calculate the Area of a Shape ..................................................................................................................132
Review: Getting Data from Drawings ...................................................................................................................133
Managing Events ....................................................................................................................................... 135

Learning Objective .................................................................................................................................................136
Introduction...........................................................................................................................................................137
Cell Dependencies .................................................................................................................................................138
Force Dependencies with DependsOn ..................................................................................................................139
DependsOn Example .............................................................................................................................................140
SetAtRef ShapeSheet Function ..............................................................................................................................142
5 144
Use the ShapeSheet to Manage Events .................................................................................................................
Use Formulas Over Code .......................................................................................................................................145

Visual Basic for Applications Code Behind Events .................................................................................................146
Supported Events ..................................................................................................................................................147
Hierarchical Event Sets ..........................................................................................................................................148
Built-In Document Events ......................................................................................................................................149
WithEvents Keyword .............................................................................................................................................151
Controls .................................................................................................................................................................153
Query Events .........................................................................................................................................................155
Query Events (Continued)......................................................................................................................................157
Marker Events .......................................................................................................................................................158
Scoping Methods ...................................................................................................................................................160
Lab 3.5: Create a Shape Area Calculator ...............................................................................................................161
Points to Consider .............................................................................................................................................161
Other Considerations ............................................................................................................................................162
Review: Managing Events .....................................................................................................................................164
Automating Data Graphics ........................................................................................................................ 165

Lesson 1: Data Graphics Concepts .........................................................................................................................167
Overview of Objects / Methods / Properties ....................................................................................................167
Creating Data Graphics Masters ........................................................................................................................170
Creating Data Graphics Items ............................................................................................................................173
Managing Data Graphic Masters .......................................................................................................................195
Lesson 2: Related Topics .......................................................................................................................................198
Shape Data Management ..................................................................................................................................198
Lab 3.6: Data Graphics ...........................................................................................................................................204
Exercise 1: Create a Pie Chart data graphic item ..............................................................................................204
Exercise 2: Test the New Pie Chart data graphic item.......................................................................................207
Exercise 3: Add a data bar to the Data Graphic that totals the 9 th, 10th, 11th, and 12th grade slots for a class
section. ..............................................................................................................................................................209
Additional Resources Data Graphics ..................................................................................................................210
Review: Automating Data Graphics ......................................................................................................................
6 212

Managing External Data Sets .................................................................................................................... 214

Lesson 1: Data Link Concepts ................................................................................................................................215
Overview of Objects / Methods / Properties ....................................................................................................215
Data Sources......................................................................................................................................................221
Lesson 2: Managing Data sets ...............................................................................................................................230
Linking data to shapes .......................................................................................................................................231
Managing Refresh .............................................................................................................................................237
Changing data locations ....................................................................................................................................242
Lab 3.7: Data Linking .............................................................................................................................................244
Exercise 1: Connect to an external data set ......................................................................................................245
Exercise 2: Link the Instructor shapes to rows in the Teacher DataRecordset .................................................245
Exercise 3: Drop and link the Section shapes to the rows in the Section DataRecordset .................................246
Exercise 4: Change the external data, refresh the drawing, and manage changes required by the data .........246
Additional Resources External Data ...................................................................................................................247
Review: Managing External Data Sets ..................................................................................................................249
Visio Software Development Kit (SDK) ..................................................................................................... 251

Lesson 1: Setup / Overview ...................................................................................................................................252
Software Requirements for Visio 2010 SDK Tools and Samples .......................................................................253
Documentation .................................................................................................................................................255
Containers .........................................................................................................................................................256
TypeLibs Included ..............................................................................................................................................259
Changes from Visio 2010 SDK............................................................................................................................260
Visual Studio 2005 and 2008 Add-in Wizards....................................................................................................260
Lesson 2: Tools .....................................................................................................................................................267
Event Monitor ...................................................................................................................................................267
Demo: Use Event Monitor to track actions in Visio ..........................................................................................269
About Using the Persistent Events Tool ............................................................................................................270
Print ShapeSheet ...............................................................................................................................................273
Publish Component ...........................................................................................................................................275
7 281
Lab 3.8: Build and run the Visio SDK Flowchart sample ........................................................................................
Exercise 1: Build and run the Flowchart (VB.NET) sample code from the SDK .................................................281
Exercise 2: Code review. ....................................................................................................................................283
Additional Resources - SDK ...................................................................................................................................285
Review: SDK ..........................................................................................................................................................287
Visio Drawing Control ............................................................................................................................... 289

Lesson 1: Concepts ................................................................................................................................................290
Requirements / Containers ...............................................................................................................................290
Demo: Drawing Control .....................................................................................................................................291
Lesson 2: Creating an application ..........................................................................................................................301
Best Practices ....................................................................................................................................................301
Porting existing code .........................................................................................................................................302
The Controls SDI (single document interface) ...................................................................................................303
Getting a reference to the Visio Application Object .........................................................................................304
Loading a document ..........................................................................................................................................304
Saving a document ............................................................................................................................................305
Integrating the control with the host container................................................................................................306
Page sizing and zoom ........................................................................................................................................307
Window management .......................................................................................................................................308
Integrating menus and toolbars ........................................................................................................................309
Handling events .................................................................................................................................................310
Using the Visio Control with the Internet Explorer Browser Control ................................................................312
Lab 3.8: Using the Visio Drawing Control ..............................................................................................................313
Exercise 1: Set the Src property of the document and display the External Data window ...............................314
Exercise 2: Add menus to place and delete Sections ........................................................................................314
Exercise 3: Add SaveAs menu ............................................................................................................................315
Additional Resources Drawing Control ...............................................................................................................316
Review Visio Drawing Control ............................................................................................................................318
Adding the Office Fluent UI to an existing Add-in .................................................................................... 320

Getting started ..................................................................................................................................................321
8 321
Updating References .........................................................................................................................................
Preparing the add-in for Ribbon support ..........................................................................................................321

Creating the Ribbon ..........................................................................................................................................324
Callbacks ............................................................................................................................................................328
Manage Ribbon control state ............................................................................................................................329
CommandBars and Ribbon ................................................................................................................................332
Sample Code......................................................................................................................................................333
9
VBA Primer
This supplement is designed to be a primer for programming with Visual Basic and Visual Basic for
Applications. Upon completion of this supplement, you should be familiar with some basic coding
concepts such as:
Variables
Objects
Methods
Properties
Conditionals
Functions and Procedures
Visual Basic Editor Environment
Events
COM Object Models
Examples and exercises will demonstrate basic coding concepts, and will use the VBA programming
language.
10
10
Event Driven vs. Procedure Based Programming
Visual Basic is a structured programming language derived from the BASIC language. VB is event-driven,
in contrast to some other programming languages and architectures that are procedure-based.
In conventional programming, the sequence of operations for an application is determined by a central
controlling program (e.g., a main procedure). In event-driven programming, the sequence of operations
for an application is determined by the users interaction with the applications interface (forms, menus,
buttons, etc.).
For example, rather than having a main procedure that executes an order entry module followed by a
data verification module followed by an inventory update module, an event-driven application remains
in the background until certain events happen: when a value in a field is modified, a small data
verification program is executed; when the user indicates that the order entry is complete, the inventory
update module is executed, and so on.
Event-driven programming, graphical user interfaces (GUIs), and object-orientation are all related since
forms and the graphical interface objects on the forms serve as the skeleton for the entire application.
To create an event-driven application, the programmer creates small programs and attaches them to
events associated with objects. In this way, the behavior of the application is determined by the
11
interaction of a number of small manageable programs rather than one large program.
11
Visual Basic Editor
There are a number of ways to open the Visual Basic Editor. You can access it from the Tools > Macros
menu or by pressing Alt-F11. You can also add the Developer toolbar to your Visio user interface to
expose the Visual Basic Editor toolbar button.
You will first notice that there are several windows in the VBE: Project, Code, Properties, Immediate, and
others. If you do not see these windows, go to the View menu to turn them on.
12
12
Figure 1: The Visual Basic Editor window
The Project window displays a hierarchical list of the projects and all of the items contained in and
referenced by each of the projects. From the Project window, you can view the code contained in
modules and forms and you can view form objects. From the Properties window, you can view and
modify design time properties for objects in a project. From the Immediate window you can execute
code. This is extremely useful when debugging to view the values of variables and expressions. It can
also be used to set values of variables to test extreme or unusual conditions. To view the value of a
variable or expression, place a question mark (?) before the code. To execute a line of code, enter it into
the Immediate window and press the Enter key.
Demonstration: Visual Basic Editor

1. In the Immediate window of VBE, type:
Msgbox "This is my message."
Press Enter. The code will execute displaying a message box with the text.
2. Create a Visio drawing with a few shapes and select some or all of them.
Return to the Visual Basic for Applications Editor and in the immediate window type:
13
13
?Application.ActiveWindow.Selection.Count
Press enter. The immediate window returns the number of shapes you have selected in the
Visio drawing.
14
14
Variables
A variable is a part of memory that is given a name by a programmer. This part of memory is used to
store important pieces of information that will be used in a program. Variables are containers for
information that you wish to store in your application.
The following code shows three variables, one a string of text, the other an integer, and the last a date:
Dim Capitol as String
Dim NumberOfStates as Integer
Dim IndependenceDay as Date
Capitol = Washington D.C.
NumberOfStates = 50
IndependenceDay = #7/4/1776#
Variables are empty until you put information in them. Variables are stored in memory, and can be
retrieved or replaced with new data at any time during the running of an application.
15
15
Dimensioning
To create a variable in a program, it is good practice to first declare the variable. Declaring a variable is
done by putting the keyword Dim (which stands for Dimension) in front of the variable name, like so:
Dim myFirstVariable as String
Dimensioning a variable sets aside the name and space in memory for the variable. The variable is
empty and contains nothing until the variable is assigned a value. The following example assigns the
variable a value:
myFirstVariable = Some String of Text
The previous example declared the variable explicitly. It is possible to implicitly declare a variable in
your code by simply assigning a value to the variable without declaring it first with the Dim keyword,
like so:
myFirstVariable = Another String of Text
It is generally good practice to explicitly declare all of your variables, to avoid creating unnecessary
variables and to help debug your programs by using Option Explicit.
16

16
Option Explicit
Option Explicit is a line of code that you add to ensure that all your variables are explicitly
declared. If using Option Explicit, an error will be generated if a variable is implicitly declared.
This helps debug your programs because errors will be thrown if you ever misspell a variable name. For
ASP scripts that use VBScript, you can add the line Option Explicit to the first line of your code.
For VBA you can do this by choosing Options from the VBA Tools menu. This displays a tabbed dialog
box. Choose the Editor tab. One of the check boxes on this tab is Require Variable Declaration.
Checking this option causes the keywords Option Explicit to be inserted at the beginning of any
new module or form added to the project. It does not, however, add Option Explicit to already
existing forms and modules. Option Explicit forces any variable name used in code to be
explicitly defined. This is very helpful at design time in catching any mistyped variable names.
17
17
Data Types
In most programming languages, data types are specified for each variable, such as String, Integer, Date,
Boolean, etc. In VBA, you specify the data type when you declare a variable with the As keyword:
Dim BabyFirstWord As String
BabyFirstWord = Googoo
To create concise and fast code, it is recommended to explicitly specify a data type. If you use Option
Explicit it will force all of your variables to have explicit data types. You can of course declare a
variable without specifying a data type. In this case, VB assigns the variable to a special data type called
Variant.
Variants
When you do not specify a data type for a variable, the variable is assigned to the data type called
Variant. The Variant is a special type of variable that can store a value of any type. Depending on the
value and the context VBA will automatically assign the Variant one of the following sub-types: Null,
Numeric, String, Date/Time, Boolean, or Object.
18
18
NULL Data Type

A NULL subtype is an unusual subtype that is used in conjunction with databases. NULL refers to a field
that contains no data. NULL does not mean zero, or even empty. Zero is a valid value, and empty is a
data type that has nothing assigned to it yet. NULL means nothing, no data and no data type.
Numeric Data Types

Numeric Data Types include the following:
Integer Whole numbers within the range of -32,768 to 32,767.

Byte Integers within the range of 0-255
Long Similar to Integer, but supports ranges from -2,147,483,648 to 2,147,483,647
Single A single precision floating point number
Double A double precision floating point number
Currency Accepts numbers up to four decimal places
String Data Type

A string holds textual information or words. String values are usually put in quotes. You cannot perform
mathematical functions on strings, even if numbers are present in the string:
Number1 = 12
Number2 = 14
Number3 = Number1 + Number2
Will Produce 1214
Date/Time Data Types

Date/Time data types store dates and times, and must be enclosed in # characters:
myBirthDate = #5/4/1965#
Boolean Data Types

Boolean data types store values as either TRUE, or FALSE.
Object Data Types

The Object data type stores a reference to an object. Objects will be discussed further a bit later in this
supplement.
19
19
Naming Variables
It is important to establish a good naming convention for your variables. Your naming convention
should be easily understood by another developer who might look at your code later. Some tips for
naming:
NameFirst and NameLast are better than FirstName and LastName because they will
appear together in a search.
Within a procedure or function you may want to prefix your variables with a p_ or f_ type code letter.
Create names with multiple words, capitalizing the first letter of each word.
Using Hungarian Notation

The Hungarian notational convention is to use the first three letters of the variants name to distinguish
the sub-type, as shown in the following table:
Data Type
Prefix
Example
Boolean
bln
blnMember
Byte
byt
bytByte
Date / Time
dat
datToday
Double
dbl
dblDouble
Integer
int
intSalary
Long
lng
lngLong
Object
obj
objConn
Single
sng
sngSingle
String
str
strTextBox
For your applications, you do not have to use the Hungarian notation, but something similar is
recommended.
Note:
Naming conventions and coding style standards evolve over time. Check if your
organization has a defined naming convention and coding standard to use.
20
20
Manipulating Variables
In order for variables to be of any use, you will need to manipulate them in some way. You can
manipulate variables using a number of different operators and by concatenating or converting them.
Assignment Operator
The assignment operator is the equal (=) sign. With it, you can assign a value to variable. The variable
name goes on the left, and the value to be assigned on the right side of the equals sign.
intMyFavoriteNumber = 11
The assignment operator can also be used to assign a new value to a variable, as in the following
mathematically unsound formula:
intMyFavoriteNumber = intMyFavoriteNumber + 1
In the above case, it may look like we are saying 11 = 11 + 1. However, we are simply reassigning a new
value to intMyFavoriteNumber.
Comparison Operators
Comparison Operators are the following:
21

21
Equality: =
Inequality: <>
Less than: <
Greater than: >
Less than or equal to: <=
Greater than or equal to: >=
Arithmetic Operators
You can use the following arithmetic operators to perform mathematical operations on your variables:
Addition: +
Subtraction: Multiplication: *
Division: /
Exponentiation: ^
Negation: Modulus: MOD or \
22
22
Exercise 1
Exercise 1 Variable Manipulation
This exercise will use VBA to declare some variables, assign numbers to them, and then perform some
simple mathematical operations on them.
Exercise
1. Open the VBA window in Visio (Alt-F11).
2. In the VBA window add a new module to the project using the menu Insert > Module. You
can give the new module a name or leave it as the default name.
3. In the Project window, double click the module name. This will display the code window
for the new module.
4. Click in the code window and choose the menu Insert > Procedure. Give the new
procedure a meaningful name such as Excercise1. Set Type to Sub and Scope to Public.
Choose OK to close the dialog.
5. Add the following code to the new aubroutine.
Public Sub Exercise1()
'Dimension the Variables
Dim intNumber1 As Integer
23

23

'Assign them values
intNumber1 = 10
intNumber2 = 20
intNumber3 = intNumber1 + intNumber2
'Display the operations in the Immediate widow
Debug.Print "intNumber1 = " & intNumber1
End Sub
24
24
Other Operations
Logical Operators
The three most common logical operators are:
AND
NOT
OR
These are mostly used in Conditional statements (IF THEN ELSE), which will be discussed shortly.
Concatenating Variables
Often times you will want to combine strings together, a process called concatenation. You concatenate
strings together in VB with the ampersand character (&). The following code combines two strings
together, with a space added in between:
Dim strPeter as String
Dim strPan as String
Dim FullName as String
25
25
strPeter = Peter
strPan = Pan
strFullName = strPeter & & strPan
26
26
Exercise 2
Exercise 2 String Concatenation
This exercise will use VBA to declare some variables as strings, assign values to them, and then
concatenate them.
Exercise
1. Add another subroutine to your coding module. Call it Exercise2.
2. Add the following code to the new subroutine:
'Dimension the Variables
Dim strNameFirst As String
Dim strNameMiddle As String
Dim strNameLast As String
Dim strNameFull As String
'Assign them values
strNameFirst = "Thomas"
strNameMiddle = "Alva"
27

27
strNameLast = "Edison"
strNameFull = strNameFirst & " " & strNameMiddle & _
" " & strNameLast
'Display the results in the Immediate window
Debug.Print "The full name is:" & strNameFull
End Sub
Note:
The underscore character at the end of the statement assigning a value to

strNameFull is a line continuation charater in VBA. It signifies that the code for this
statement wraps to the next line.
28
28
Data type conversions and variable scope
Conversions
Often times you will have to convert values in order to work with them better. This might mean
converting a decimal number into a whole number, or a numerical sequence into a string. You can do
this through several conversion functions that are built into VBA. There are many conversion functions,
and we will not cover all of them in this supplement. We will only look at two functions, CInt and CStr.
The CInt function will convert a number variant into an integer and rounds it to the nearest even
number. The CStr function will convert an integer into a string subtype.
Variable Scope
Variables can be either local or global in scope. The variables we have seen so far have been global in
nature, that is, they are valid for the entire block of code that we have written. Sometimes you may
wish to break your code into functions or procedures, which are blocks of code that you can reuse
throughout your application. In this case, if you declare a variable in a procedure or a function, the
variable is only valid for the time that the procedure or function is executed.
Note:
Global variables must be defined at the top of the module before any subroutines
or functions are defined.
29

29
30
30
Exercise3
Exercise 3 Variable Scope
This exercise will demonstrate local variables that are used in sub-procedures.
Exercise
1. Define the global variable. This must be done outside of any subroutine or function and
must be defined at the top of the module before any subroutines or functions are defined
Dim strFirst as String
2. Add the following code to the module.

Sub Procedure_1()
strFirst = "I'm a string in procedure 1"
Debug.Print "Calling Procedure 1:" & strFirst
End Sub
Sub Procedure_2()
strFirst = "I'm a string in procedure 2"
Debug.Print "Calling Procedure 2:" & strFirst
31

31
End Sub
'Display the results in the Immediate window
Procedure_1
Procedure_2
End Sub
3. To run the code, click within subroutine Exercise3 and choose hit F5. The results are
displayed in the Immediate window.
32
32
Constants
Constants are declared with the Const keyword. Constants are valuable when you want to assign a
value to a variable and have it remain fixed throughout the execution of the code. The syntax for
Constants is as follows:
Public | Private Const name [As type] = Expression
A variable or constant with Public scope is available to all procedures in all modules in a project.
A variable or constant with Private scope is only available to procedures in the module that defines it,
but not to procedures in other modules.
Examples
Define the mathematical constant pi.
Public Const pi As Double = 3.14159
33
33
Control structures
In VBA, control structures are used to determine what should happen, when it should happen, and
under what circumstances it should happen. The three most common control structures are branching
statements, looping statements, and jumping statements.
Branching statements perform a test, and then execute some lines of code but not others.
Looping statements execute a portion of code again and again
Jumping Statements pause the execution of the current code, jump to a different block of code,
and then return back to the original code.
Branching Statements
Branching statements include the familiar If Then conditional, as well as the Select Case statement.
Branching statements test for conditions, and then execute certain blocks of code if the conditions are
TRUE, and different blocks of code if they are FALSE.
If/Then
The If Then conditional is probably the most widely used control structure in programming. The syntax
for an If statement is as follows:
If logical_expression Then
Code to execute if True
Else
Code to execute if False
End If
It is entirely possible to nest If statements, but be careful of doing this too many times as the code can
become unmanageable very fast. To nest If statements, use a skeleton like the following:
If condition_1 Then
Second If Statement
If condition_2 Then
Code if True
Else
34

34
Code if False
End If
Else
Code if condition_1 is False
End If
If you want to have multiple tests in a single If statement, you can use ElseIf. ElseIf will enable you test a
condition multiple times. Use the following skeleton for an ElseIf statement:
If strBreakfast = Sausage Then
Code if True
ElseIf strBreakfast = Donuts Then
Code if True
ElseIf strBreakfast = Green Eggs and Ham Then
Code if True
Else
Code if none of the above are True
End If
Select Case
Select Case is used when you need to make a choice among several different answers. The
following example carries out one of five actions depending on what is contained in the variable
varCurrentMood. There can be multiple lines of code for each Case.
Select Case varCurrentMood
Case "Sad"
'code for Buy Kleenex and Sob
Case "Mad"
'code for Punch the pillow
Case "Happy"
'code for Smile
Case "Homesick"
'code for Write a letter

Case "Irritated"
35
35
'code Smirk
Case Else
'The catch-all phrase for anything that doesn't fit the above.
'None of the above?
Then you must be bored.
Go out and play.
End Select
Looping Statements
Looping statements perform the same action over and over again. There are two main looping
structures, For Next, For Each Next, and Do While.
For Next
Typically the For Next statement is used when the number of required loops is known, or is stored
in a variable. Here is the syntax:
For varCounter = X to Y
Code to execute here
Next
varCounter is a variable that the script uses to keep track of the current count. You could name it
whatever you want. X and Y can be either numbers, or can be variable names that store numbers. X
signifies the starting number to set the counter to, and Y is the end number of loops to perform.
Dim DateStart As Date
Dim DateEnd As Date
Dim NumberOfDays As Integer
Dim varCounter As Integer
DateStart = #7/1/2002#
DateEnd = #7/15/2002#
NumberOfDays = DateEnd - DateStart
For varCounter = 0 To NumberOfDays
'Code to execute here
36

36
Next
For Each Next

The For Each Next statement is used for looping through items that are in an array or a
collection. The syntax is as follows:
For Each Item In varVariable
Next
varVariable can either be the name of an array, or a collection of objects.
Do While
The Do While statement is used when you are not sure of the number of loops to perform. On
each loop a test is performed, and as long as the condition is met the loop will continue to occur. The
syntax is as follows:
Do While varVariable1 < varVariable2
varVariable1 = varVariable1 + 1
Loop
Typically, the value of varVariable1 will change within the loop. In the example it is incremented by 1
each time through the loop. At some point it will become bigger than the value in varVariable2 and the
loop will end.
Jumping Statements
Jumping Statements are useful when you need reusable chunks of code that need to be called at specific
moments. These are essentially mini-programs that force the main program to jump from the main
body of code, run through the commands of the mini-program, and then return to the main body of
code. There are two types of jumping statements:
Sub procedures Used to carry out actions. A sub procedure does not return values.
Functions Used to carry out actions and to return an answer to the main body of code.
37

37
Procedures
Sub procedures are used to execute a bit of code, and then return to the main body of the code. The
syntax is as follows:
Sub nameofsub()
Code to Execute Goes Here
End Sub
You can then execute a sub procedure by calling it using the Call command:
Call nameofsub
Functions
Functions are used to execute a bit of code and to return a value back to the main code. The syntax is as
follows:
Function NameOfFunction(Parameter) As Integer
'Code to Execute Goes Here
'Assign a value to the function before it ends
'This will be the value that the function returns
NameOfFunction = 10
End Function
Functions can take parameters, meaning they can accepts values from the main body of code and use
them during the execution of the function. Inside the parenthesis () you can place the name of a
variable that you want to pass to the function. For example, to create a function to calculate the next
time to change the oil of a car (current mileage + 3000 miles), you can pass a variable that stores the
current mileage into the function, as in the following code:
Dim dCurrentMileage as Double
dCurrentMileage = 145000
Function FindNextOilChange(dCurrentMileage) as Double
38
38
When functions are finished performing their calculations, they return the result as a value of a new
variable, which is the name of the function. When you create a function and give it a name, that name
becomes a variable that will store the resulting value of the functions calculations. It is not necessary to
Dim this variable, it is available for use automatically. So, the code above becomes complete when we
assign the value to the function name:
Function FindNextOilChange(dCurrentMileage) as Double
FindNextOilChange = dCurrentMileage + 3000
End Function
It is common to create a new variable, and make the variable equal to the function. This invokes the
function and stores the functions value as a global variable.
Sub CalculateNewMileage()
Dim dCurrentMileage As Double
Dim dNewMileage As Double
dCurrentMileage = 145000
dNewMileage = FindNextOilChange(dCurrentMileage)
MsgBox The mileage for your next oil change is & & dNewMileage
End Sub
39
39
VBA Primer Conclusion

There are many more topics that could be covered to help get you started using VBA. Defining and
using an applications objects will be covered in the next few lessons as will learning to manage events
within VBA.
40
40
Introduction to Automation
Weve covered a few of the techniques that can be used for developing SmartShapes symbols. Now lets
cover how to use these symbols as part of a larger solution. Automation can be used to control Visio
shapes, documents, and the Visio drawing environment, as well as other applications.
Following a brief introduction to general Automation (previously referred to as ActiveX Automation or
OLE Automation), you will cover the basics of automation and Visiothe Visio object model and how to
access the Visual Basic Editor (VBE).
A common application of automation and Visio technology is the automatic generation of Visio
documents. It is common to store descriptive information in a database or a spreadsheet (describing a
network, for example). It is very advantageous to get a graphical view of this data by creating a Visio
document. Many times the generation of this document can be automated through the extraction of
data and the creation of a document through automation. You can open a document, drop master
shapes on the page, and position and size the newly created shape. All these steps can be done through
automation and the techniques will be covered in Generating Drawings.
Once a drawing is created, you often need to ask questions or extract information about the drawing.
These requests can be satisfied though automation. An example of this would be getting an inventory of
the shapes in the drawing, starting an application such as Microsoft Excel, and creating a Bill of Materials
41
41
with part numbers and price information. In Getting Data from Drawings, we will cover the basics of
accessing document, page, shape, and cell properties.
As you work with drawings, you often need to know when something has occurred, a new piece of
equipment has been added, or a network connection has been made. To validate the drawing, you can
trap events and if needed, prompt the user for action. Managing Events covers these topics.
42
42
Introduction
Lets start by reviewing what is meant by Automation as well as some Visual Basic for Applications
fundamentals.
These early exercises focus on the Visio object model and not on development environments. As such,
examples are shown using Visual Basic for Applications. This should not be considered a
recommendation that you use VBA for all of your application development. Its just that VBA is a very
convenient platform for learning about an applications object model.
43
43
Automation Basics
With Automation, one program can incorporate the functionality of another by using objects exposed by
the other program.
Automation encompasses several services defined under the OLE 2 specification, such as linking and
embedding objects and in-place editing. The foundation of this technology is COM (Component Object
Model). COM defines the interfaces for the objects an application exposes. It is this interface structure
that allows COM objects to make their services available to other applications.
The program that controls the automation is sometimes called a controller, client, or container
application. This is a program you write in a language that supports Automation, for example, Visual
Basic, Visual Basic for Applications, C#, or Microsoft Visual C++. You are going to focus on Visual Basic for
Applications in this module, but you can use the Visio object model with Visual Basic, Visual C++, or any
Microsoft Visual Studio .NET language as well.
The program being automated is sometimes called a server or source application. This is the program
that exposes the objects for the controller application to use. The objects have properties and methods
that the controller can use to manipulate the objects. The Visio application is the ActiveX server you are
interested in today.
44
44
Some applications can act as both controllers and servers by embedding Visual Basic for Applications.
Many of the Microsoft Office applications contain VBA, such as Word, Excel and Visio.
45
45
Programming a Server's Objects

Programming a Server's Objects
The server
owns the
objects; you
just use them
You get a
reference to an
object, store the
reference in an
object variable
Container (Controller)
'Create a
reference to
an object
Source (Server)
object
Set myObj =
Source.object
myObj.method
Access to the properties and methods of the object is

made through the interface provided by the object.
The object always resides with its source.
Objects accessed through Automation remain with the objects server. They are not incorporated in
your program.
Everything you do with a servers object is done by way of a reference to that object, which you assign
to an object variable in your program. You manipulate the objects remotely, from your program, by
setting properties, and invoking methods through the object variable.
An object reference is similar to a pointer; it is valid at run time but it is not something you can store
between executions. Furthermore, having a reference doesnt guarantee that you have an object. For
example, you can get a reference to a shape on a page. However, if the user deletes the shape, you still
have the reference but its not referring to anything useful.
Demonstration scenario:
The Visio drawing shows the Tech ED 97 General Session Theater which seats 10,000 and was the actual
location for the original showing of this program.
This demonstration is a nice example of how multiple applications can work together by accessing the
object models of each others application. In this scenario, Visio controls Excel by gathering information
from the Visio drawing and writing it to an Excel spreadsheet. When a row is selected in the Excel 46
46
spreadsheet there is code that controls Visio and selects and centers the drawing on the selected object.
There is a third application which unfortunately cannot be demonstrated here, but was part of the
original demo. That is the automated control of an air cannon gun that was on stage and used to fire tshirts into the crowd. The air cannon is represented by a shape in the Visio drawing. As you move the
pointer for the air cannon in Visio, the coordinates from the Visio drawing were being fed to the actual
air cannon on the stage through Rockwells own automation interface for this device..
The drawing depicts seating, stage, demonstration machines, project units, controls, etc. Contents of the
drawing can be pushed to an Excel spreadsheet by right clicking on the page and selecting "Create Asset
Report". This add-on starts Excel, opens the template file TechED.xlt, and writes each component of the
drawing to the spreadsheet.
Each item in the drawing has shape data which capture the manufacturer, description, number of
individual items and unit cost. When placed into the spreadsheet the total cost of each item is also
calculated. If any item is greater than $10,000 the row item is made Red, Bold, and a larger point size.
The Wet Bar is priced at $25,000 so it gets flagged in the spreadsheet.
From the spreadsheet there are events tied to the up and down arrow keys so that as you move through
the spreadsheet using the arrow keys the corresponding Visio object is selected and centered in the
drawing. NOTE: Be sure to set the option "Center selection on zoom" in the File > Options > Advancced
tab for the centering to occur.
In the Visio drawing there is a T-shirt firing Air Gun on the stage. A control on the Air Gun allows you to
direct the gun by moving it around the drawing. Right click on the Air Gun to either display its shape
data or to display a form with the trajectory coordinates.
Try it! TechEd

1. Minimize all windows except the Visio window.
2. From your student CD, open <install path>\Demos\Vol3\Introduction to
Automation\TechEd.vsd.
3. Right-click on the drawing page and select Create Asset Report.
4. This starts Microsoft Excel and creates a Bill of Materials for all of the objects in the drawing.
5. In Visio select File > Options > Advanced tab. Set Center Selection on Zoom. The
demonstration will take advantage of this feature as you select the Visio drawing objects from
the Excel spreadsheet.
6. Tile the Excel and Visio windows. Select a row in Excel. Notice that the corresponding item is
selected in the Visio window (you may have to zoom in or out in Visio to get a better view).
47
47
48
48
VBE Tools Menu
From the VBE Tools menu you can get to some very useful menu options.
Choose the Options menu under Tools. This displays a tabbed dialog box. Choose the Editor tab. One
of the check boxes on this tab is Require Variable Declaration. Checking this option causes the
keywords Option Explicit to be inserted at the beginning of any new module or form added to
the project. It does not, however, add Option Explicit to already existing forms and modules.
Option Explicit forces any variable name used in code to be explicitly defined. This is very
helpful at design time in catching any mistyped variable names.
Objects other than Visio objects can be accessed by Visual Basic for Applications, but the Visual Basic for
Applications environment must first be notified. This is done from the References menu under Tools.
The dialog box displays all object libraries installed on the local machine. Just check the ones that you
want to access. For example, if you want to control Excel from the Visio application, from the
References menu, check the appropriate Excel object library.
The functionality of Digital Signatures was added to Visio 2002. Digital Signatures allow you to add an
extra level of security to your VBA projects. Using digital certificates, a developer can digitally sign a
project and be identified as a trusted source. When a Visio document with a VBA project is loaded, 49
Visio
49
checks to see whether the project has been digitally signed by a trusted source before loading it. If it
has, the project will be loaded under any security level. If it has not, Visio will load the project based on
the current security level set for the Visio application. Macro security settings in Visio can be found in
the Trust Center.
For more information on Microsoft Office security, search the Microsoft Developer Web site
(msdn.microsoft.com) for Digital Signing.
50
50
Object Browser
Once an object library is part of the project, its objects can be viewed with the Object Browser. Choose
View > Object Browser (or F2) to use the browser.
From the Object Browser you can view the hierarchical structure of any object library.
You can search for objects by name.
Once an object is selected, you can view its properties, methods, and events.
Values of constants defined in a type library can also be determined from the object browser.
To turn off the Object Browser, just close the window.
51
51
Review: Introduction to Automation
Questions
1. Define Automation.
2. What actually happens when one program uses Automation to drive another program?
3. What allows Visio to be a controller and a server at the same time?
4. What function does a digital signature provide?
Answers
1. Automation allows one program to incorporate the functionality of another by using objects exposed
by the other program.
2. The server application returns a handle to an object. The controller application can use this handle to
ask the server application to do things with this object.
3. Because Visio has embedded VBA it can be used as a controller. Because it exposes its object model
it can be used as a server.
4. Using digital certificates, a developer can digitally sign a project and be identified as a trusted source.
52
52
Automation and Visio Technology

In this section, we will tie together some of the concepts that were learned in the ShapeSheet modules
with Automation objects from the Visio object model.
We have spent a good deal of time learning about the ShapeSheet. The ShapeSheet is important to
understand in order to effectively automate Visio because each cell in the ShapeSheet is effectively a
property that you can control through automation. However, most ShapeSheet cells will not be found
directly in the Visio Object Model. Instead, you will access them indirectly through the Cells or CellsU
property of the Shape object.
53
53
Overview
Automation and Visio Technology
The Visio Object Model
Working with Objects, Methods, and Properties
When and How to Run Your Program
Getting More Information
Now you will learn about how you can use SmartShapes as part of a larger solution by using Automation
to control the Visio application and the objects within it.
In this module you will look in depth at the Visio Object Model. You will analyze each object and begin
the process of discovering its methods and properties.
You will learn different strategies for when and how to run your programs and issues to consider when
choosing a platform for your program. Finally, we will look at other resources that are available to help
in you in learning about and using the Visio Object Model.
54
54

Slide is portion of the

complete model
Collections are blue
Individual objects are

yellow
Walk the object

model in code to
obtain your object
reference
This slide shows a portion of the Microsoft Visio object model. A richer, but not complete view of the
Visio object model is on the following page. The image shows the object model of Visio 2003, but at
this high level view it is still shows the major components and the basic structure of the model.
It is not as complicated as it looks; many of the objects are used primarily to access other objects, and
youre unlikely to use all of the objects in a given program. For example, youll probably do more with
shapes than you will with documents and pages; you may never manipulate layers from a program,
although Visio exposes layer objects so you can if you need to.
Many objects in the model correspond to items you can see and select in Visio windows. For example, a
Page object corresponds to a drawing page; a Shape object can represent anything on the drawing page
that you can select with the pointer toola shape, a group, a guide or guide point, or an object that is
linked or embedded in a Visio drawing.
The Application object represents a running instance of the Visio application, and this is where youll
typically start. In some circumstances you can start at the document or the page. The Application object
has properties that return references to next objects in the modelfor example; the Documents
property returns a reference to the Documents collection, which represents all of the documents that
55
are open in the instance. You would retrieve a particular document by using the Item property of the
55
Documents collection. Use the Pages property of that Document object to get its Pages collection, and
so on, down to a particular shape or even a particular formula of that shape, represented by a Cell
object.
The Microsoft Visio global object is automatically available to Microsoft Visual Basic for Applications
(VBA) code that is part of the VBA project of a Visio document. The Visio global object is not available to
code in other contexts. The global object holds references to such properties as ActiveWindow,
ActiveDocument, and ActivePage. These properties are also available through the Application object if
you are building your solution outside of VBA within Visio.
56
56
57
57
A Sample Visio Program

Sample Visio Program
Open Sample Code.vsd
Navigates the object model
Starting with the <Global> object
Gets the shapes Name and NameID properties and

displays the values on a form
Code sample conventions

Code samples in the demonstration files and code displayed on slides generally follow a simple
Hungarian notation. Variable names start with a lower case letter or letters that designate the data type
of the variable. Following the data type designator will be a name describing the variable that starts in
upper case.
Below are some examples of variable names:
oDocs a data type Object referencing a Documents collection

oDoc a data type Object referencing a single Document
sShapeName a data type String containing a shapes name
txtShapeName a text box control containing a shapes name
dCellResult a double precision variable containing the contents of a ShapeSheet cell
Try it! A Sample Visio Program

1. Run an instance of Visio, and from your student CD open <install path>Demos\Vol3\ Automation
and Visio\Sample Code.vsd.
58
58
2. Right-click on the page to run the add-on GetShape (or from View > Macros >
ThisDocument.GetShape). We will look at the VBA code for this add-on in step 5.
3. Close the GetShape add-on.
4. Press Alt+F11 to open Visual Basic for Applications.
5. In the Project Window, open the Forms folder and right-click on frmGetShape. Select View
Code and look at the following line:
Set oDocs = Visio.Documents
Documents is a property of the Application object and also of the <global> object (accessed through the
application name Visio). It returns the Documents collection.
Set oDoc = oDocs.Item(1)
Item is a property of the Documents collection (and of most other collections, too). It happens to be the
default property, so you can omit Item but not (1). The rest of the code establishes a reference to each
collection and collection member.
Set oPages = oDoc.Pages
Set oPage = oPages.Item(1)
Set oShapes = oPage.Shapes
Set oShape = oShapes.Item(1)
sShapeName = oShape.Name
The Name property of a shape returns a string, which can be assigned to the Text property of our text
box.
txtShapeName.Text = sShapeName
59
59
Getting and Setting Properties

Getting and Setting Properties
Properties that return an object
Dim oShape As Visio.Shape
Set oShape = ActivePage.PageSheet
Properties that return other data types
Dim sName As String
sName = oShape.Name
Setting properties
oShape.Name = "Box"
Read-only, read-write, write-only properties
Once you get the object you want, youll probably become interested in its other properties. For
example, in addition to the Name property, a Shape object has a Text property that returns its text, and
a Type property that identifies the type of shapewhether its a group, a guide, or other kind of shape.
Most properties that dont return objects return strings or integers.
The PageSheet property of the page returns a reference to the pages ShapeSheet. This is a Shape
object that has Type=visTypePage.
You can set properties too, as long as theyre read-write or write-only.
Here are some examples of property types:
Read-only: A shapes Sheet.#

Read-write: ShapeSheet cells
Write-only: Custom menu or toolbar sets
The Developer Reference help file contains a list of objects with their properties and methods. This
reference also has an alphabetical list of properties and methods, whether theyre read-only, read-write,
60
or write-only, and their return type.
60
Note:
When making an assignment to a variable of type Object, the Set keyword must be
used. When making an assignment to a variable that is not an object (such as a
string variable), the Set keyword is not used.
61
61
Invoking Methods
Invoking Methods
Methods that create objects
Define specific object type

Dim oDocument As Visio.Document
Set oDocument = Documents.Add("")
Methods that perform other actions

Visio.Windows.Item(2).Activate
oShape.SendToBack
Properties or methods with arguments

Set oShape = ActivePage.Shapes.Item(1)
Set oShape = ActivePage.DrawOval(1,1,3,3)
oFromCell.GlueTo oToShape.Cells("PinX")
There were no methods used in the demonstration program of getting the shapes name, but their
syntax is similar to properties.
Methods often correspond to Visio commands. For example, a Shape object has a Copy method that
performs the same action as selecting the shape and choosing Copy from the Edit menu in Visio.
Other methods correspond to actions. For example, a Window object has an Activate method that
makes that window the active window.
If a method creates an object, it typically returns a reference to that object. Methods that dont create
objects typically dont return anything.
Both properties and methods sometimes take arguments. For example:
A Shape objects Cells property takes the name of the ShapeSheet cell to return.
The Documents collections Add method takes the name of a template on which to base a
new document. Passing an empty string is equivalent to choosing File > New Drawing from
the menu or New from the Toolbar.
62

62
63
63
Compound References
Compound References
You can concatenate object
References
Properties
Methods
Example:
Set oShape = Visio.Documents.Item(1).Pages _
.Item(3).Shapes.Item(1)
Simple references can be more efficient
Store intermediate objects in variables
Code is easier to read and debug
The examples in this course tend to declare an object variable and set it for every object in the model
that we need a reference to. You dont have to do this as you can concatenate Visio object references,
properties, and methods as you can with Visual Basic objects.
However, there are some tradeoffs and sometimes, simple references are better. If you use any of the
intermediate objects in your programfor example, if youre going to be working with more than one
shape from the Shapes collectionit makes sense to assign the intermediate objects to variables so you
have them available for other uses. This requires less overhead than repeatedly calling a compound
statement, and enhances performance.
A compound statement can also be harder to debug. Each expression is evaluated and its return value
plugged into the statement before the next expression can be evaluated. If one fails, youll get an error
at the statement but it may not be obvious where the failure occurred.
64
64
Lab 3.1: Get the Name of an Open Visio Document

Lab 4.1: Get the Name of an Open Visio Document
Run Visio and open GetDoc.vsd
Add code to display the documents name in the text

field of the Visual Basic for Applications form
Add additional command buttons and text boxes to

your form to display other Document properties
Points to Consider
1. Establish each object reference separately.
2. Consider the document properties Description, Path or Subject for your additional information.
Exercise
1. From your student CD, open <install path>\Labs\Vol3\Start\Get Doc.vsd
2. From Visio, choose View > Macros > ThisDocument.Solution. This will display a form with the
title GetDoc.
3. Click the button on the form to display the name of the document.
4. Without looking at the code for how the solution was produced, develop code to retrieve the
documents name and place it in frmExercise.
5. When complete, run the macro.
65
65
Coding Issues
If an object is defined to be a specific type at design-time, as with the following statement

Dim oDoc as Visio.Document
it is bound to that data type at design time. This is called early binding. Many design-time checks can be
made such as testing assignment statements to ensure the correct data type is being used. This creates
more efficient run-time code.
If late binding is used, as with the statement
Dim oDoc as Object
the type of the object must be determined at run time, and assigning the wrong type of data to the
object can cause a run-time error.
Using early binding of objects also allows you to take advantage of the Visual Basic Intellisense feature,
giving you property, method, event and parameter information.
Using Visual Basic for Applications code makes distribution of your add-on easy since the Visual Basic for
66
Applications code is part of the drawing file. Updating the code, however, is more difficult.
66
Demonstration: Protect Your VBA Code

1.
2.
3.
4.
5.
Open a new Visio drawing, and open the Visual Basic Editor window.
From the Tools menu, choose <document name> Properties.
Click the Protection tab, and click the Lock project for viewing checkbox.
Enter a password and confirm it.
Save and close the file.
The next time the file is opened and the VBE is accessed, the project is locked and a password must be
entered to view or edit the project.
67
67
Running Your Program
To run your program:

1. When Visio is launched
a. Put the .exe or .vsl file into a designated Startup folder. To set the Startup folder go
to File > Options > Advanced > File Locations
b. Register the COM-Addin and set its load behavior to Load at Startup.
2. From the ribbon under View > Add-ons
a. Put the .exe or .vsl file into a designated Add-ons folder. To set the Add-ons folder
go to File > Options > Advanced > File Locations
b. Use the Add method of the application's Addons collection to programmatically
add the add-ons.
Note:
You have to restart Visio to refresh its Add-ons list before youll see your
program on the menu. You can also use the file paths refresh method .
3. From the ribbon under View > Macros

a. Create a Macro through the Visio interface.
b. Add a public procedure into a module or ThisDocument of the VBA project for the
drawing. Macros in any one open project can be accessed by another open project.
68
68
4. When the user opens a document

Place your code or a reference to it in the DocumentOpened event in the ThisDocument
module in Visual Basic for Applications.
5. When a shortcut menu command is chosen
Create an entry in the Actions section of the ShapeSheet and make sure the add-on is
either a public procedure within the Visual Basic for Applications project or is in the Addons path specified in the File > Options > Advanced > File Locations dialog.
Note:
Beginning with Microsoft Visio 2003, you can publish your add-ons,
templates, stencils and other files as components to be integrated with the
Visio application. Publishing components is the preferred method of
integrating add-ons and other content with Visio. It offers tighter
integration with the Visio application, and better performance on add-on
discovery. Publish Components will be covered in the section on the Visio
Software Development Kit.
69
69
RUNADDON(string)
RUNADDON(string)
If Visio recognizes the string as a macro, it will execute

that macro
If no macro is found, the RUNADDON function looks for

string in the add-on list and executes the add-on if it
is found
If no add-on can be found, Visio reports no error and

takes no action
Examples:
RUNADDON(ModuleName.Report)
RUNADDON(Calendar.exe)
RUNADDON can execute a macro or call an add-on. Visio will first check for a macro of name string
and execute that macro if one is found. If string is not recognized as a macro, the RUNADDON
function looks for string in the add-on list and executes the add-on if it is found. If no add-on can be
found, Visio reports no error and does nothing.
Examples:
1. Launch an add-on called Calendar.exe
RUNADDON("Calendar.exe")
2. Launch the (VSL-implemented) add-on whose name is Array Shapes.

RUNADDON("Array Shapes")
3. Call the ReportStatistics macro in the ThisDocument module in the document project
containing this function call. To invoke a macro in the ThisDocument module, you must
preface the string with "ThisDocument" as shown.
RUNADDON("ThisDocument.ReportStatistics")
4. Call the ReportStatistics macro in ModuleName in the document project that contains this
function call.
70
70
RUNADDON("ModuleName.ReportStatistics")
For more information, see the demonstration file <install path>\Demos\Vol3\Automation and
Visio\RunAddon.vsd for some examples of using the RUNADDON function.
71
71
CALLTHIS
Even though RUNADDON is a very powerful function, there are times where the add-on being executed
needs to get a reference to the shape that initiated the action.
CALLTHIS is a variation of RUNADDON that automatically passes a reference to the shape that caused
the add-on to be executed. Notice that the reference to the shape is very much like the "this" argument
passed to a C++ member procedure; hence, the name "CALLTHIS."
In effect, a cell that contains a formula with CALLTHIS is saying, "Call procedure and pass it a reference
to my shape."
The demonstration file CallThis.vsd has some good examples of using the CALLTHIS function.
72
72
Where to Find Visio Automation Information
There are many ways to get helpful information on the Visio automation model. A good place to start is
with the Visio help files. The Developer Reference help file contains material for the automation model.
Help information for the ShapeSheet is contained in the Visio SDK.
Demonstration: Developer Reference

1.
2.
3.
4.
Open the Developer Reference help file, Help > Search > Developer Reference.
In the Table of Contents select Visio Automation Object Model Reference.
Display an object topic. This describes the object and lists its properties and methods.
Display the topic for one of the objects methods. Review what is in each property and
method topic.
5. Use some of the other jumps in the method topic to related properties and methods or
other objects that have the same method.
Other sources of information include the Visio Developer Portal on msdn.microsoft.com. This is the key
entry point to gaining access to the latest articles, examples and downloads related to Visio.
There are also Visio discussion groups where you can post questions and get answers.
http://www.microsoft.com/communities/newsgroups/en-us/
73

73
The Visio SDK provides sample applications, code librarian code snippets, documentation, and tools
including the Event Monitor, Persistent Events, Print ShapeSheet, and Solution Publishing.
A great way to explore the object model and really get a feel for how everything ties together is through
the Object Browser. From the Visual Basic Editor choose View > Object Browser to display the Object
Browser window. From the Object Browser you can explore the entire Visio Object Model.
You can also explore a live Visio application by using the Immediate window from VBE. Choose View >
Immediate Window. From the Immediate window investigate objects, properties, and methods of the
current running instance of Visio.
The Watch Window and the Locals Window are great places to view data values when exercising or
debugging code in VBA.
The Macro Recorder can be used to develop snippets of code for performing some function in Visio.
Turn on the Macro recorder, perform the function you wish to automate, and then turn off the recorder.
Viewing the generated code will show you how the operation is performed through automation.
There are, however, limitations on the actions that can be captured by the Macro Recorder. Dialog only
commands and Solution-specific commands are generally not recorded - so you could not automate the
dropping and property setting of Database Model entities, for example. Also, you cannot record the
action of shutting down the application, or any actions which leave Visio in a Modal state. The API
programmability model for Themes, Data Graphics, and Pivot diagrams does not cover everything that
can be done in the user interface so use of the macro recorder in these areas has been short circuited.
74
74
Lab 3.2: Running VB Add-ons

Lab 4.2: Running VB Add-ons
From the Student CD, copy DispName.exe into the

appropriate folder to list it as an add-on
Create a new Visio drawing and shape
Add your DispName.exe file to the shortcut menu for

the shape to run the program via right-click
Run the program when you double-click a shape as

well
For the lab, follow the directions listed on the slide.
Note:
Check File > Options > Advanced > File Locations for the appropriate add-on
folder.
75
75
Review: Automation and Visio

Summary: Automation and Visio
Working with Objects, Methods, and Properties
Running Your Program
Getting More Information
Questions
1. What are some of the objects in Visios object model? How might you use them in a
program?
2. Once youve finished building your custom solution, what are some of the different ways
you can run it?
3. How might this influence the design of your program?
Answers
1. Application, Document, Shape, Window, Cell, etc. Visio drawings can be created using
automation or existing drawings can be interrogated for information.
2. Solutions can be set up to run from a shape with a right-click action or a double-click. Addins and macros can also be executed from the View tab of the ribbon.
3. A fundamental decision is between creating a macro and creating an add-in. Macros are
useful for fairly simple one-off type solutions.
76
76
77
77
Generating Drawings
Overview
Creating Visio Documents
Dropping Masters in a Drawing
Getting and Setting
Shape Properties
Cell Formulas and Values
In this section lets begin by using automation to create a document, drop masters in a drawing, and set
the text of shapes.
Along the way youll see more generally how to get and set shape properties, including how to access a
particular formula and get either the formula as a string, or the value that is its result.
78
78
Creating a Document
Creating a Document
Get the Documents collection of the Application object

Set oDocs = Visio.Application.Documents 'or
Set oDocs = Application.Documents 'or
Set oDocs = Documents
Add a new document to the collection

Set oDoc = Documents.Add("Basic Network.vst")
Set oDoc = Documents.Add("")
Set oDocStencil = Documents.OpenEx( _
Basic Network Shapes.vss", visOpenDocked)
To create a new drawing, add a Document object to the Documents collection of the Application object.
As you may recall, the Application object has a Documents property that returns its Documents
collection. Because this is an object, you need to assign it to an object variable using Set. The first three
code statements are equivalent in VBA because the global Visio is predefined and contains a reference
to the Application object and the Documents object. If working outside of VBA it will be necessary to get
a reference to the active instance of Visios Application object in order to access the Documents
collection.
If no documents are open in the instance, its Documents collection is empty. This can be important to
remember if, for example, you run Visio and attempt to get a document without opening one first.
Attempting to get an object from an empty collection causes an error.
To create a new document, use the Add method. For a Documents collection, Add takes the filename of
a template as an argument. Visio searches for the template in the template location defined under the
menu File > Options > Advanced > File Locations. Alternatively, you may specify the file path explicitly.
If you dont want to base the new document on a template, use a null string. This creates a new blank
document.
79
79
The Open and OpenEx methods can be used to open existing document files. OpenEX takes the
additional parameter that flags how to open the file. See the Microsoft Visio Developer Reference for
more information.
80
80
Getting a Reference to the Master
If you base a new drawing on a template, it probably opens one or more stencils for you.
This means the Documents collection now has more than one object in it. It has the new document you
created plus each stencil opened by the template.
When you use automation to drop a master in a drawing, youll be working with two Document
objectsone that represents the new drawing, and the other that represents the stencil containing the
master.
Note:
Every Visio document has a stencil which holds the master shapes that have been
added to the drawing, so every Document object has a Masters collection. But the
Masters collection of a new drawing is generally empty. Just make sure that you
set your object reference to the Masters collection of the stencil, not the drawing.
81
81
Dropping the Master on the Page

Dropping the Master on the Page
Get the drawing page

Set oPage = ActiveDocument.Pages.Item(1)
Set oPage = ActivePage
Drop the master on the page

Set oShape = oPage.Drop(oMaster,4.25,5.5)
4.25, 5.5 indicate where to place the pin of the new

shape instance on the page
Drop coordinates are always in inches, regardless of

drawing scale or language version
Use ConvertResult method to convert units
Having obtained a reference to the master, you now need a page on which to drop it. The next step is to
get a Page object.
A new document has at least one page, so its Pages collection will contain at least one Page object.
To drop a master, use the Drop method of the Page. Drop takes three arguments: a Master object and a
pair of x,y coordinates that indicate where to place the pin of the new shape (the instance of the
master).
The coordinate arguments to Drop must be expressed in inches, which are the units that Visio uses
internally. Unfortunately, this means you may have to convert the arguments before dropping the
master, if for example, youre working in a scaled drawing or an unscaled drawing in metric units. The
ConvertResult method of the Application is a handy tool for solving these unit conversion problems.
Tip:
Because you are going to do more to the new instance of the master, assign the
object returned by Drop to an object variable, such as oShape. Youll usually want
to do this, but its not required.
82
82
83
83
Adding Text to Shapes

Adding Text to Shapes
Set the text property of the Shape object

oShape.Text = "This is a text string"
Use ASCII linefeed Chr$(10) or vbCrLf to control line

breaks
oShape.Text = "K. Anderson" & _
Chr$(10) & "Chairman of the Board"
Use double double quotes to embed quotes in the string

oShape.Text = """Hello?"""
Equivalent way to get embedded quotes

oShape.Text = Chr$(34) & "Hello" & Chr$(34)
When you are creating a drawing from a program, youll usually set the text in shapes at run time. You
might get the text from another file, or have the user type it in a form, for example.
You assign text to a shape by setting its Text property to a string. You can, of course, concatenate strings
and variables with the Visual Basic concatenation operator, and insert special characters (such as the
linefeed shown here) using the VB Chr$() function or vbCrLf. The Text property of a shape can contain
up to 64K of character data, which will be ample for most purposes.
Use the Characters object to control field codes within the stream of text, just as you can do through the
user interface.
84
84
Getting Formulas of Shapes and Pages

Getting Formulas of Shapes and Pages
In Visios object model, a formula is represented by a

Cell object
To get a Cell object for a shape formula

Set oCell = oShape.Cells("Width")
Set oCell = oShape.Cells(User.WatchHeight)
To get a Cell object for a page formula

Dim oPageSheet as Visio.Shape
Set oPageSheet = ActivePage.PageSheet
Set oCell = oPageSheet.Cells("PageWidth")
Compared to everything you can do to a shape in Visio, Shape objects have relatively few properties and
methods (although they have many compared to some other objects in the model). So it might seem
that your options are limited.
Theyre not, however, because you have full access to the ShapeSheet through Cell objects. A Cell object
represents a particular formula, such as a shapes Width formula. Once you have a Cell object, you can
get the formula or the value it represents, just as you can choose Formulas or Values when viewing the
ShapeSheet. Change the contents of a cell by setting its Formula property.
Most commonly, youll get the values of certain formulas so you can use them to construct your
drawing, such as the width and height of the page, or the drawing scale.
To get a Cell object, get the Cells property of a shape object and specify the name of the cell. Use the
same names for cells as are used in the ShapeSheet. The ShapeSheet reference under help lists all of
the ShapeSheet cells alphabetically by name.
To get page cells, first get the PageSheet property of the page, which returns a Shape object. Then use
the Shape objects Cells property to get the formula of a particular cell.
85
85
Tip:
When should you use Cell vs CellU and Cells vs CellsU. If you are faced the
possibility of having to localize your solution, using CellU instead of Cell and CellsU
instead of Cells will save you some work. CellU and CellsU take the universal name
(not localized) name of a cell as their argument. The universal names never change
in localized versions of Visio.
86
86
Getting a Formula or Its Result

Getting a Formula or Its Result
The Formula property of a Cell object returns its formula

as a string
Dim sCellFormula as String
sCellFormula = oCell.Formula
The Result property returns the value of the formula as

a double in the units specified
Dim dCellResult as Double
dCellResult = oCell.Result("in")
dCellResult = oCell.Result("mm")
See also ResultInt, ResultIU, ResultStr
Once you have a Cell object, use its Formula property to get its formula as a string.
If you want the formulas value instead, use one of the Result properties.
Result and ResultIU return a double precision value as a floating-point number with 15 significant digits.
ResultInt returns a long integer.
ResultStr returns the value as a string.
You can specify units for the value returned by a Result property by passing any valid unit string or one
of the unit constants defined in the Visio type library.
For example, you can use visDrawingUnits to get a result expressed in units defined for the drawing. To
explicitly specify a unit-less number, use visNumber.
Tip:
Use VBAs Intellisense to help view available Visio constants. In VBA just type vis,
hold down the Ctrl key and press the space bar. Also check the Developer
Reference help file for a complete list of these constants.
87
87
Tip:
Visios internal units are inches, for cells that measure linear dimensions or radians
for cells that measure angular dimensions.
88
88
Setting a Formula
Setting a Formula
Set the Cell objects Formula property

oCell.Formula = "GUARD(Width*2)"
Set the Cell object's Result property
oCell.Result(visNumber) = 2.5
Can also set ResultInt and ResultIU
ResultStr is read-only
To overwrite a guarded cell use
FormulaForce
ResultForce
When you set formulas from a program, you probably wont need to construct the kinds of complex
formulas youve been building in the class to control shape behavior. Those more complex formulas will
most likely already be in place in your solution.
Note:
Using the equal sign (=) is optional, just as it is when you type in the ShapeSheet
window
To set a cell value to a constant, set either the Result or the Formula.
If youre working with a cell whose formula is guarded, youll need to use the force equivalents of
Formula and Result:
FormulaForce
ResultForce
ResultIUForce
ResultFromIntForce
89

89
Tips for Positioning Shapes

Tips for Positioning Shapes
Use drawing units to place shapes, for example,

to determine the center of the page
Dim dXLoc as Double
Dim dYLoc as Double
dXLoc = _
oPageSheet.Cells("PageWidth").ResultIU*0.5
dYLoc = _
oPageSheet.Cells("PageHeight").ResultIU*0.5
Use an offset to position one shape relative to another

dXLoc2 = (dXLoc + 0.5) 0.5 inches right
dYLoc2 = (dYLoc - 1.5) 1.5 inches down
Positioning shapes in a drawing can be a challenge, and exactly how you do this will depend on the kind
of drawing your program creates. The Drop method requires the position to be in drawing units (not
page size). Only when you have an unscaled drawing are these the same.
One simple technique involves calculating the shapes position relative to the pages width and height.
For example, if you know you want to center a shape on the page, you can drop its pin at
(PageWidth*0.5, PageHeight *0.5).
Another technique is to position one shape at a constant offset from anotherby getting the PinX and
PinY values of one shape and adding the offset to them for the other.
90
90
Tips for Positioning Shapes (Continued)

Tips for Positioning Shapes (Continued)
Use ResizeToFitContents method to resize the page to

fit tightly around the shapes that are on it
Set oPage = ActivePage
oPage.ResizeToFitContents
create margin around shapes

oPage.PageSheet.Cells(PageWidth) _
.ResultIU = dPageWidth + 1
oPage.PageSheet.Cells(PageHeight) _
.ResultIU = dPageHeight + 1
center shapes on larger page
oPage.CenterDrawing
There may be functionality in your solution that requires page size to change based on how many
shapes are added or deleted from the page.
Visio provides the ResizeToFitContents method for Master and Page objects. This method resizes the
page to fit tightly around the shapes that are on it. This method is the equivalent of clicking the Size to
fit drawing contents on the Page Size tab in the Page Setup dialog.
Because the page is resized using this method, the PinX and PinY values in your shapes will typically
change. If your solution keeps track of shape position, this fact may ultimately be a deterrent of using
the ResizeToFitContents method.
Note:
Using this method, the page extents are right at the edge of the outer most shapes
on the page. Consider using a page margin offset and the CenterDrawing method
together to enhance shape position on the final page.
91
91
Connecting Shapes
Connecting Shapes
To create a connected diagram from a program, you

work with cell objects
Get a Cell object that represents the part of a shape

you want to glue
1-D End Point or Control Handle
Use the GlueTo or GlueToPos methods of the Cell

object and specify what you want to glue to
Connection Point, Shape Geometry or Guide
To create a connected diagram from a program, you work with cells, but in a slightly different capacity.
You are not interested in their formulas or results; instead, you use them to indicate what gets glued to
what.
Assume that you are working with two shapes on the drawing, A and B. To connect the shapes:
Use the Cells property of shape A to get a Cell object that represents the part of the shape
you want to glue, such as a control handle.
Use the GlueTo method of that Cell object and indicate a cell that represents the part of
shape B you want to glue to, such as a connection point. (You do not necessarily need to
get a Cell object for shape B.)
Or, use the GlueToPos method of shape As Cell object and indicate the shape you want to
glue to shape B with a position relative to shape Bs width-height box.
92
92
Getting the Cell to Glue

Getting the Cell to Glue
You can specify either cell of an X,Y pair
Control handle
Set oFromCell = _
oFromShape.Cells(Controls.X1)
Begin point or end point of a 1-D shape

Set oFromCell = oFromShape.Cells(BeginX)
Edge of a shape that will glue to guide or guide point

Set oFromCell = _
oFromShape.Cells(AlignLeft)
Here are a few examples of how you can indicate various parts of a shape you want to glue.
In this example, Controls.X1 refers to the first row of the Controls section in the ShapeSheet. If the
shape had more than one control handle, you can indicate a different row. To do this, the control handle
must be able to be glued (some arent), which depends on the CanGlue setting in the ShapeSheet.
Control handles and the begin and end points of 1-D shapes are defined by two cellsone for X and one
for Y. You do not need both cells in order to glue the item, and you can use either one.
If youre gluing a 2-D shape to a guide or guide point, you can indicate which edge of the shape you want
to glue. The shape edge that you specify needs to be appropriate for the type of guideAlignLeft,
AlignCenter, or AlignRight for a vertical guide, and AlignTop, AlignMiddle, or AlignBottom for a
horizontal one.
For example, if you try to glue the right edge of a shape to a horizontal guide, youll get an Inappropriate
Target Cell error. You may not get this error with a guide point, but you will get odd results.
93
93
Gluing to the Other Shape

Gluing to the Other Shape
GlueTo glues to a specific cell in another shape

oFromCell.GlueTo _
oToShape.Cells("Connections.X1")
connection point
oFromCell.GlueTo _
oToShape.Cells (Geometry1.X1)
geometry vertex
GlueToPos glues to an X,Y position in another shape

oFromCell.GlueToPos oToShape, 0.5, 0.5
GlueToPos always creates a connection point, even if
one already exists.
One type of cell you can glue to using the GlueTo method is a connection point. As when specifying the
cell to glue, you only need one cell of the X,Y pair.
This example does not have a Cell object to represent the glue destination. If it did, the statement would
be:
celObj1.GlueTo celObj2
You can glue to the same items you can in Visio, such as a vertex (Geometry1.Xn or Geometry1.Yn).
If you want to glue to a selection handle, use AlignLeft, AlignRight, AlignTop, or AlignBottom to indicate
the selection handle in the center of that edge of the shape (rather than the whole edge). AlignCenter
and AlignMiddle both glue to the center of the shape.
Internally, a guide is a shape, like anything else on the page. To create a guide you use the AddGuide
method of a Page object. If you check a guides Type property, it returns visTypeGuide. If you want to
glue to a guide, use GuidePosX for a horizontal guide or GuidePosY for a vertical one. For a guide point,
94
you can use either.
94
GlueToPos takes slightly different arguments: a Shape object and the X,Y coordinates of a position
relative to the shapes width-height box. In this case, 0.5, 0.5 indicate the center of the shapes width
and height.
95
95
AutoConnect Mode
The AutoConnect feature added can be accessed programmatically as well as through the user interface.
Use Shape.AutoConnect to simulate Auto-Connect.
Try It!
Below are two procedures for connecting a dynamic connector between two shapes. To run the code
open the file Autoconnect.vsd from the Samples folder for the class. Execute the macros and see that
the connector is placed and glued.
Sub ConnectWithGlue()
'Glue a connector between two shapes using the GlueTo method
Dim vsoConnector As Visio.Shape
'Drop the connector shape
Set vsoConnector = Application.ActivePage.Drop _
(Application.ActiveDocument.Masters.ItemU _
("Dynamic connector"), 0#, 0#)
Dim vsoCellFrom As Visio.Cell
Dim vsoCellTo As Visio.Cell
'Get references for the cell to glue from and the cell to glue to for
'the beginning of the connector
Set vsoCellFrom = vsoConnector.CellsU("BeginX")
Set vsoCellTo = _
Application.ActivePage.Shapes.ItemFromID(1).CellsSRC(7, 2, 0)
'Glue the cells
vsoCellFrom.GlueTo vsoCellTo
'Get references for the cell to glue from and the cell to glue to for
'the end of the connector
Set vsoCellFrom = vsoConnector.CellsU("EndX")
96

96
Set vsoCellTo = _
Application.ActivePage.Shapes.ItemFromID(2).CellsSRC(7, 2, 0)
'Glue the cells
vsoCellFrom.GlueTo vsoCellTo
End Sub
Sub ConnectWithAutoConnect()
'Glue a connector between two shapes using Autoconnect
Dim vsoShapeFrom As Visio.Shape
Dim vsoShapeTo As Visio.Shape
'Get a reference to the two shapes
Set vsoShapeFrom = Application.ActivePage.Shapes.Item("Process")
Set vsoShapeTo = Application.ActivePage.Shapes.Item("Decision")
vsoShapeFrom.Autoconnect vsoShapeTo, visAutoConnectDirNone
End Sub
A quick inspection reveals that it takes about one-half the lines of code to glue shapes using
Autoconnect. The reason for this is that the Autoconnect method hooks up both ends of the connector
with one command. Using the GlueTo method requires that each end of the connector be handled
separately.
Enable/Disable Autoconnect
Autoconnect can be enabled or disabled within the File > Options > Advanced tab. When Autoconnect is
turned on, hovering the mouse over a shape presents the four autoconnect triangles around the shape.
Clicking on one of these triangles connects the shape to another shape. When autoconnect is turned off
these triangles do not appear.
Below are VBA code snippets for turning autoconnect on or off.
Sub EnableAutoConnect()
97

97
Application.Settings.EnableAutoConnect = True
End Sub
Sub DisableAutoConnect()
Application.Settings.EnableAutoConnect = False
End Sub
Note:
It is not necessary for EnableAutoConnect to be set to True in order to use the

Autoconnect method through automation.
98
98
Adding Data to Shapes
Earlier you learned about getting cells that represent formulas. Sometimes you may need to add cells to
a shape, just as when youre developing a shape in Visio.
For example, if a shape does not have Shape Data, you can add a Shape Data section, add rows to it, and
then set formulas of cells in those rows.
99
99
Adding Sections and Rows

Adding Sections and Rows
Add the section

oShape.AddSection visSectionProp
Add a row
oShape.AddNamedRow visSectionProp, _
"PartNo", 0
Note : If the section does not exist, AddNamedRow

will create it
Then reference cells and set formulas

oPropCell = oShape.Cells("Prop.PartNo")
oPropCell.Formula = "XYZ-123"
To add a section, you use the AddSection method and specify the type of section . Constants for these
are defined in the VBA object browser.
The example uses visSectionProp, which is the constant for the Shape Data section.
Unlike adding a section in the ShapeSheet (which automatically gives you one row), when adding a
section from your program you need to add the rows explicitly. To do this in a shape data section, use
the AddNamedRow method, specify the section, the row name, and a row tag of zero.
Note:
The row tag should be zero for any kind of row except the Geometry section rows;
for those its used to indicate the row type, such as LineTo.
Once youve added the row, you can access its cells in the usual way. You dont need to explicitly add
cells to the new row.
If you try to add a section that a shape already has, youll get an error. To avoid this, either use the
SectionExists property to test whether the shape already has the section, or just add the row. If the
section doesnt already exist, it will be created automatically.
100
100
Lab 3.3: "Hello World"

Lab 4.3: "Hello World"
Open Hello.vsd and add code to:
Create a drawing using an unscaled template such as

Basic Diagram (US Units).vst
Instance a master in the drawing and set its text to

"Hello World
Change the size of the page to more closely match the

size of the shape
Challenge
Repeat the exercise with a scaled template
Drop four masters, one in each quadrant of the drawing
Points to Consider
Do the procedure manually first, and note each step and the names of your template, stencil, and
master.
Use X and Y coordinate variables to make dropping the four masters on the page more efficient.
Comments have been developed in a partially completed exercise to guide you through the process. Do
not look at the solution code before attempting the exercise.
101
101
Review: Generating Visio Drawings

Summary: Generating Visio Drawings
Creating Visio Documents
Dropping Masters in a Drawing
Getting and Setting
Shape Properties
Cell Formulas and Values
Questions
1. If you opened a new blank drawing, how many items would the documents collection
contain?
2. What does a Cell object represent?
3. Why are drop-coordinates always in inches?
4. What object property would you use to replace a guarded cell formula?
Answers
1. There would be only one document in the Documents collection since a blank drawing has
no stencils opened.
2. A Cell is an object representing a single cell in the ShapeSheet.
3. Visio maintains internal units in inches.
4. FormulaForce or ResultForce
102
102
103
103
Getting Data From Drawings
104
104
Overview
Overview
Iterating through Visio Collections
Getting Information from
Documents
Pages
Shapes
ShapeSheets
Getting the Selection Object
Now youre going to approach Visio objects from a slightly different perspectiveby retrieving
information about the objects that already exist in the drawing. Heres what you are going to cover in
this section:
Youll learn about how to iterate through a collection so you can get something from, or do something
to, each object in the collection.
Youll read briefly about documents, pages, and shapes, and the kinds of information you can get from
them that you might use in a program, plus youll discover another way of getting a Cell object using
CellsSRC.
It is frequently necessary to access objects selected in the drawing. The Selection object, or set of shapes
selected in a window, can be accessed through the Selection property of the Window object. The
Selection can be accessed through automation or can be created through automation.
105
105
Iterating Through a Collection

Iterating Through a Collection
Most Visio collections are indexed starting with 1
Except for user interface objects which start at 0
The Count property returns a number of items in the

collection
For i = 1 to Documents.Count
Set oDoc = Documents.Item(i)
'process item
Next i
Use the For EachNext statement to iterate through a

collection
For Each oThisShape in oShapesCollection
oThisShape.Cells(Width).Formula = 2
Next
Youve seen how you can retrieve objects from collections, by name or by index. You can iterate through
a collection to perform the same operation on every member, or check each member until you find the
one you want.
Some Things to Remember about Collections

Most Visio collections are indexed starting at 1.
Generally, only the UI object collections are indexed starting at 0, but be careful. Hyperlink collections
also start with 0. Be sure to check before you start writing code.
The Count property returns the number of items in the collection at the time you get the property;
however if you add or remove objects from the collection, the value of Count will change. This could
make a difference in the example above, where Count is evaluated for each pass through the loop.
Collections associated with a valid Visio object always exist, but the collections may be empty, in which
case Count returns 0.
A good way to iterate through collections like page or shape collections is with the For Each Next
statement. Use it to build your object references and process shape data.
106
106
When you delete objects from a collection using an iteration loop, decrement the counter rather than
incrementing it. For example:
For i = oDocs.Count to 1 Step -1
A collection is not like an array; items dont keep a fixed index position. Instead, as you delete an item,
the next item moves into that position. But if youve incremented your counter, you skip that item and
delete the next one, until sooner or later you overreach Count and try to delete an item with an invalid
index, which causes an error.
Try it! Collections

1. Open the file <install path>Demos\Vol3\Getting Data from Drawings\ Collections.vsd.
2. Run the sample code via right-click on the page. Each macro is an example of working with
collections.
3. ColorShapes adds a color to each shape.
4. Form some group shapes on the page. Use CountShapes to count all of the shapes in the
groups, including the groups themselves.
5. DeleteShapes deletes all of the shapes on the page.
Note that the For loop in the code counts down from the highest indexed shape.
107
107
Getting Data from Documents

Getting Data from Documents
Opening a document
Set oDoc = _
Documents.Open(Physical Network 3.vsd")
Binary Visio file or
Documents.Open(Logical Network.vdx)
XML for Visio file
Set oDoc = _
Documents.OpenEx(Logical Symbols.vss", _
visOpenDocked)
Getting an open document

Set oDoc = Documents.Item("filename")
Set oDoc = Documents.Item(index)
The Open method opens a document as an original (that is, for read/write access), which is not good for
stencils and templates, because you probably dont want your users changing those.
Use OpenEx with the appropriate flag to open a file as read-only. Open a stencil docked in a drawing
window, or open a file without adding it to Visios file menu of most recently used files.
For best results, try to use a full path when opening a document. Using relative path names can be
unpredictable at times. Do not hard code the path but instead use the common Open dialog box to get
the user to indicate the path. Under some circumstances you might be able to construct the path from
the Path property of a document that is already open.
If the document you want is already open, you can get it by its filename or its index in the collection.
108
108
Noteworthy Document Properties

Noteworthy Document Properties
Masters, Pages, Styles, Fonts, Colors
Name, Fullname, Path
Creator, Description, Keywords, Subject, Title
ReadOnly, Saved, InPlace
TimeCreated, TimeEdited, TimeSaved, TimePrinted
Various Print properties
These are a few of the Document object properties available through the object model. Youve already
see the Masters and Pages collections, but a Document object also has Styles, Fonts, Colors, and Visual
Basic Project collections, with objects that represent those items.
The Name, Fullname, and Path properties contain the short filename, full filename, and just the path
portion of a documents full filename, respectively.
Description, Keywords, Subject, and Title correspond to options of the same name in the documents
summary information. (Properties command from the File menu.) Creator corresponds to Author in the
File Properties dialog.
ReadOnly, Saved, and InPlace are Boolean properties that indicate whether a document was opened as
read-only, has been changed since it was opened (the Saved property is really a dirty flag) or has been
opened for in-place editing in a container document rather than in a standalone instance of Visio.
To determine whether a document has been saved, check its Path property. If an existing document has
been opened or a new document has been saved, its Path property will be set.
TimeCreated, TimeEdited, TimeSaved and TimePrinted return the date and time of each action. The
return value is a date formatted like this one:
109
109
4/6/10 1:50:21 PM
There are several Print properties that allow you to set properties for printed output, such as Printer,
PrintCenteredH, PrintPagesDown, PrintFitOnPages, etc. Set these properties first and then use the
Print method to print your document.
110
110
Getting Data from Pages

Getting Data from Pages
Getting a page
Set oPage = oPages.Item("pagename")
Set oPage = oPages.Item(index)
Example:
Set oPage = oPages.Item(Bill of Materials")
oPage.Delete True
Getting the active page

Set oPage = Application.ActivePage
When you use ActivePage, make sure the active window

is the drawing window or an error will occur
Getting a page is similar to getting an open document; you can get the page by its name or by its index
in the Pages collection.
The ActivePage property is a quick way of getting a page without going through a document. However,
it only works if the active window is a drawing window. If a stencil window had focus and you attempted
to get the ActivePage, an error would occur in your solution.
This will make more sense a little bit later in the session, when you learn about windows and the
selection object.
We have already seen that a Page has a Shapes property for accessing the shape collection on the page.
The Page also has a Layers property for accessing information about Layers defined for the page and a
Connects property for getting information about connections that exist on the page.
111
111
Getting Data from Shapes

Getting Data from Shapes
A Shapes collection can include
Basic shapes
Groups
Guides/guide points
Linked/embedded objects
Type property indicates a shapes type

visTypeShape, visTypeGroup, visTypeGuide,
visTypeForeignObject, visTypePage
For shape properties and methods, see the Developer

Reference Help file
Youve already worked with shapes and used some of their properties, such as Text and Cells.
When youre working with shapes from a program, the definition is somewhat expanded. A pages
Shapes collection includes basic shapes, groups, guides and guide points, and linked or embedded
objects (bitmaps, metafiles, Excel spreadsheets, and so forth.).
Obviously, these various items differ quite a bit in what you can do with them. So if youre iterating
through a Shapes collection, youll almost always want to check a shapes type before continuing with
whatever youre doing to the shape. The Type property of a Shape object returns a constant describing
the shape.
Recall getting the PageSheet property in the last session. That property returns a Shape object so you
can use its Cells property to get page formulas. If you check that Shape objects Type property, it returns
visTypePage.
A few interesting Shape properties include AreaIU, which returns the area of the shapes geometry in
internal units, Characters, which contains the shapes text and the fields that control that text, Connects
and FromConnects, which contain shape connection information, and Layer, which contains information
about the layers a shape is assigned to.
112
112
Getting Data About Connections

Getting Data About Connections
The Connects property of a Shape object returns its

Connects collection
Contains a Connect object for each shape, group, or

guide that the Shape object is glued to
FromSheet, ToSheet properties
FromPart, ToPart properties
Return shape objects involved in the connection

Return integers indicating part of the shape involved
FromCell, ToCell properties
Return cell objects that correspond to From/ToPart values
Earlier you saw how to connect shapes in a drawing through Automation.

The relationship between a shape and the object that it is glued to is represented by a Connect object.
Every shape has a Connects collection. If the shape isnt glued to anything, the collection is empty.
If the shape is glued to one other shape (or guide), its Connects collection contains one Connect object
representing that relationship. You access the Connects collection differently depending upon whether
the shape is a one-dimensional or two-dimensional shape.
You can get information about the connection by getting properties of the Connect object.
The FromSheet and ToSheet properties return Shape objects for the shapes involved in the
connection.
The FromPart and ToPart properties return integers that indicate which parts of the shapes
are involved. These are represented by constants such as visControlPoint and
visConnectionPoint.
The FromCell and ToCell properties return Cell objects that correspond to the FromPart
and ToPart values.
113

113
For example, if FromPart is visControlPoint, FromCell returns a Cell object that represents that control
handle in the ShapeSheet.
114
114
Connect Object for a Control Handle to a Shape
Study the following case, and for simplicitys sake, assume that shape A has only one control handle and
shape B only one connection point:
Shape A has a geometry that is tied to its control handle.

The control handle is glued to a connection point on shape B.
If you get the Connects collection of shape A, it contains one Connect object with these properties:
FromSheet = A
ToSheet = B
FromPart = visControlPoint + 0
ToPart = visConnectionPoint + 0
FromCell = Cell objects for FromPart
ToCell = Cell object for ToPart
115
115
Connect Object for a 1-D Between 2-D Shapes
Heres a more common case:
Shape C is a one-dimensional connector glued to shapes A and B.

Shape Cs Connects collection contains two Connect objects because its glued to shape A
and shape B.
A and B arent glued to shape C, nor are they glued to each other.
In this case, the begin point of shape C is glued to the third connection point of shape A (first row + 2 =
row 3), and the end point of shape C is glued to the fourth connection point of shape B (first row + 3 =
row 4).
See the Developer help file for more information about the Connects object.
Try it! Connect Object

1. Open <install folder>\Demos\Vol3\Getting Data from Drawings\
Connect Object.vsd.
2. Select the dynamic connector, and remove its connection to Shape 1.
A message box will appear describing the action that occurred, and the shapes that were
116
involved.
116
3. Re-glue the connection you just removed.

4. Open the Visual Basic Editor and review the code in the ConnectionsAdded and
ConnectionDeleted page events.
The message box utilizes the From/ToSheet and From/ToCell properties of the connect
object to relay its information.
117
117
More Connectivity API options

One of the very nice features of Visio has always been the ability to maintain and interrogate connected
diagrams through automation. However, it does get tedious to use the Connects objects to retrieve this
connectivity information. Visio 2010 introduces several new methods that make these efforts a lot
easier.
Use Shape.ConnectedShapes(Flags, CategoryFilter) to return an array of identifiers (IDs) of shapes that
are one degree of separation away from the given shape (i.e. separated by a 1-D connector). In other
words you no longer have to go through the connector to see what is on the other side. The IDs can be
filtered as incoming or outgoing connections.
Try it! ConnectedShapes

1. Open <install folder>\Demos\Vol3\Getting Data from Drawings\Connections API.vsd.
2. Select page ConnectedShapes and follow the directions on the page.
3. Open the VBA Window (AltF11) and turn on display of the Immediate Window (View >
Immediate Window). The results of running the macros are written to this window.
Public Sub GetIncomingShapes_WithCategories()
'Use Shape.ConnectedShapes to get the shapes that are incoming connections to a shape
Dim shp As Visio.Shape
Dim shpIDs() As Long
Dim i As Integer
If ActiveWindow.Selection.Count = 0 Then
MsgBox ("select a shape with connections")
Exit Sub
Else
Set shp = ActiveWindow.Selection(1)
End If
shpIDs = shp.ConnectedShapes(visConnectedShapesIncomingNodes, "Square")
Debug.Print "Incoming shapes"
For i = 0 To UBound(shpIDs)
Debug.Print ActivePage.Shapes(shpIDs(i)).Name
118

118
Next
End Sub
Flags: Filters the list of returned shape IDs by the directionality of the connectors.
CategoryFilter: Filters the list of returned shape IDs by limiting it to IDs of shapes that match the
specified category. A shapes categories can be found in the User.msvShapeCategories cell of its
ShapeSheet. In the sample code above the method only returns shapes that are in the category
Square which is designated in the shapes User.msvShapeCategories cell.
Use Shape.GluedShapes(Flags, CategoryFilter, [pOtherConnectedShape]) to return an array of

identifiers for the shapes that are glued to a shape. The returned IDs can be filtered by 1D vs. 2D and by
incoming vs. outgoing connections. You can optionally specify another shape to which any returned
shapes must also be glued.
Try it! GluedShapes

2. Select page GluedShapes and follow the directions on the page.
3. The results of running the macros are displayed in VBAs Immediate window.
Dim shpIDs() As Long
shpIDs = shp.GluedShapes(visGluedShapesIncoming1D, "")
Debug.Print "Incoming 1D shapes"
For i = 0 To UBound(shpIDs)
Debug.Print ActivePage.Shapes(shpIDs(i)).Name
Next
Flags: Specifies dimensionality and directionality of connectors of shapes returned.

CategoryFilter: Specifies category of shapes returned.
pOtherConnectedShape: Optional additional shape to which returned shapes must also be glued
A method that parallels the AutoConnect feature is Page.DropConnected(ObjectToDrop, TargetShape,

PlacementDir, [Connector]). This creates a shape, positions it relative to the target shape and adds a
connector from the target shape to the new shape. You can optionally specify a specific connector to
use if you need to override the default connector.
119
119
Try it! DropConnected

2. Select page DropConnected and follow the directions on the page. Six Process shapes are
dropped and connected on the page.
Sub DropConnected()
'use Page.DropConnected to drop several Process shapes
Dim lastDrop As Visio.Shape
Dim i As Integer
Set lastDrop = ActivePage.Drop(ActiveDocument.Masters("Process"), 4.5, 8)
For i = 1 To 5
Set lastDrop = _
ActivePage.DropConnected(ActiveDocument.Masters("Process"), _
lastDrop, visAutoConnectDirDown)
Next
End Sub
ObjectToDrop: The shape to be added to the page

TargetShape: The existing shape from which to align, space, and connect
PlacementDir: The direction from TargetShape in which to place ObjectToDrop . The example
drops shapes using visAutoConnectDirDown.
Connector: The connector to use (optional). This overrides usage of the default Dynamic
Connector.
To drop a new shape on a connector and split the connector, use

Page.SplitConnector(ConnectorToSplit, Shape). Pass it the connector to split and the shape to drop.
Try it! SplitConnector

2. Select page SplitConnector and follow the directions on the page. Shape 2 is inserted between
shape 1 and shape 3 and the existing connector is split.
Set connector = ActiveWindow.Selection(1)
Set ovShape = ActiveWindow.Selection(2)
120

120
Set newConnector = ActivePage.SplitConnector(connector, ovShape)
ConnectorToSplit: The connector to split. Must be a routable 1-D connector.

Shape: The shape to use to split the connector. Must be a 2-D shape.
Connectors can be unglued and the end of the connector moved away from the original glue position
with a single method call. Use Shape.Disconnect(ConnectorEnd, OffsetX, OffsetY, Units) and specify
the end of the connector to disconnect, the offset, and the units.
Try it! Disconnect

2. Select page GluedShapes and follow the directions on the page to run macro ShapeDisconnect.
Both ends of the connector are unglued and moved away from the connection points by .25
inches in each direction.
If ovShape.OneD Then
ovShape.Disconnect visConnectorBothEnds, 0.25, 0.25, visInches
End If
ConnectorEnd: The end of the connector to disconnect

OffsetX: The x-distance that the connector end is moved away from the shape
OffsetY: The y-distance that the connector end is moved away from the shape
Units: The units of measure for the assigned offset values
To add many connections quickly, use Page.AutoConnectMany(FromShapeIDs(), ToShapeIDs(),

PlacementDirs(), [Connector]). This method automatically draws multiple connections in the specified
directions between the specified shapes. It returns the number of shapes connected.
Try it! AutoConnectMany

2. Select page AutoConnectMany and follow the directions on the page. The selected shapes are
connected and repositioned from left to right.
Public Sub AutoConnectMany()
'use Page.AutoConnectMany to create connectors between shapes
121

121
If ActiveWindow.Selection.Count < 1 Then

MsgBox "Select at least two shapes in the order they are to be connected"
Exit Sub
End If
Dim fromShapeIDs(10) As Long
Dim toShapeIDs(10) As Long
Dim placementDirs(10) As Long
Dim i As Integer
For i = 1 To ActiveWindow.Selection.Count - 1
fromShapeIDs(i) = ActiveWindow.Selection(i).ID
toShapeIDs(i) = ActiveWindow.Selection(i + 1).ID
placementDirs(i) = visAutoConnectDirRight
Next
ActivePage.AutoConnectMany fromShapeIDs(), toShapeIDs(), placementDirs()
End Sub
FromShapeIDs(): An array of identifers of the shapes from which to draw a connection

ToShapeIDs(): An array of identifers of the shapes to which to draw a connection
PlacementDirs(): An array of constants that represent the directions in which to draw the
connection
Connector: The connector to use (optional). This overrides usage of the default Dynamic
Connector.
DeleteEx(Flag) will delete additional shapes associated with a shape or selection, such as connectors
and unselected container members, when the selection is deleted.
Try it! DeleteEx

2. Select page DeleteEx and follow the directions on the page. The selected shapes are connected
and repositioned from left to right.
122
122
When the option to heal connections is chosen the two hanging connectors resulting from the
shape delete are merged into one. Not the third example on this page. It is not possible to heal
the connectors in this case because there are two incoming connectors and two outgoing
connectors and therefore the result is indeterminate.
ovShape.DeleteEx VisDeleteFlags.visDeleteHealConnectors
Flag: can specify that unselected connectors, shapes within a container, or callouts are to also
be deleted. The flag must be a bitwise combination of the following constants.
o visDeleteNormal=0 match the deletion behavior that is in the user interface
o visDeleteHealConnectors=1 delete connectors that are attached to deleted shapes
o visDeleteNoHealConnectors=2 do not delete connectors that are attached to deleted
shapes
o visDeleteNoContainerMembers=4 do not delete unselected members of containers or
lists
o visDeleteNoAssociatedCallouts=8 do not delete unselected callouts that are associated
with shapes
123
123
Getting a Selection Object

Getting a Selection Object
Get the Selection property of a Window object
Similar to Shapes collection
It has Item and Count properties
Order reflects order selected in the drawing
Does not include shapes sub-selected in a group
Can add and remove selected shapes
Keep it current !
The Selection object, or set of shapes selected in a window, can be accessed through the Selection
property of the Window object.
The easiest way to get the Selection object is to access the selection in the current active window:
Dim oSelection as Visio.Selection
Set oSelection = Application.ActiveWindow.Selection
One very good use for a Selection object is to allow users to indicate the shapes they want to work with.
You can also create a Selection object through automation as a means of working with a subset of
shapes on the page.
The order of items in the collection follows the order in which the corresponding shapes are selected in
the drawing window. The first shape selected is the first item in the collection. If the shapes have been
selected by dragging out a selection rectangle, then they are put in the selection in front to back order,
with the forward-most shape being the first shape in the selection.
124
124
Probably the most important thing to keep in mind about a Selection object is this: Its not bound to the
selection in the drawing window. After you get a Selection object, the user can change the selection, but
the changes wont be reflected in your program unless you get another Selection object. For this reason,
its best to get a Selection object just before you plan to use it.
125
125
Working with Windows and Selected Shapes

Working with Windows and Selected Shapes
Getting the active window

Set oWindow = Visio.ActiveWindow
Checking a windows type

If oWindow.Type <> visDrawing Then
Exit Sub not a drawing window
End If
Type can be
visDrawing, visStencil, visSheet,
visIcon, visAnchorBarBuiltIn etc
SubType (visDrawing) can be

visPageWin, visPageGroupWin,
visMasterWin, visMasterGroupWin
An Application object has a Windows collection, which includes all of the drawing, ShapeSheet, stencil,
and icon edit windows that are open in the instance. One thing to remember about the Windows
collection is that it may grow or shrink by more than one item at a time, depending on other actions.
You can iterate through a Windows collection in the usual way, but more often youll be interested in a
particular kind of window. You can check the Window objects Type property to find out what kind of
window it is. For a drawing window, you may also want to check its SubType property to make sure you
have the right kind of drawing window.
Note:
If the type property of a Window object returns any value other than
visDrawing, the subtype property returns the same value as the type property.
Not surprisingly, the ActiveWindow property returns the active window. If your program has just run an
instance of Visio and created a drawing, you can probably assume that the active window is a drawing
window. However, it is always good to make sure. Many of a Window objects methods are only
relevant in a drawing window.
Here are some ways to utilize a Window objects properties and methods:
Use the Activate method of a Window object to make it the active window
126

126
Get the document displayed in the window by getting its Document property
Change the magnification with the Zoom property
Get shapes selected in a drawing window by getting the Selection property
127
127
Getting Cells with CellsSRC

Getting Cells with CellsSRC
What if the cell you need to reference does not have a

unique name?
Use CellsSRC to get a cell by section, row, and index
In this example, the cell object is set to the Controls

Section, Controls.X cell in the 4th row
Set oCell = _
oShape.CellsSRC(visSectionControls, _
visRowControl + 3, visCtlX)
See also SectionExists, RowExists, CellExists,

CellsSRCExists
You used the Cells property in the last module to get cells by name. This is almost always the preferred
way to get a particular cell. However, sometimes you might want to iterate through rows or cells, or
even sections such as in a shape with multiple Geometry sections. You can do this using section, row,
and cell indexes.
The example on the slide uses CellsSRC to get the Controls.X3 cell. (Rows are indexed starting with the
row index constant as the base, so you need to add an integer offset for the second and subsequent
rows.) This might seem like a lot of work to get a single cell, but iterating through each of the Control
section rows and getting the same cell from each one is easier using CellsSRC. All you have to do is
increment the row offset instead of constructing a cell reference string.
You can also use these indexes to see if the shape has a particular section, row, or cell, or use them to
add sections to a shape, as youll see later in this session.
Try it! CellsSRC

1. From your student CD, open <install path>\Demos\Vol3\Getting Data from
Drawings\Collections.vsd.
128
128
2. Select one of the shapes on the drawing page and run the macro View > Macros >
Sample_Code.SampleCode.PrintGeometry.
3. Open the Immediate window (also known as the Debug window) in VBA. The macro prints
all cell formulas from the Geometry section to the Immediate window.
129
129
Determining Shape Proximity

Determining Shape Proximity
Visio provides shape properties to help you determine a

shapes proximity to other shapes
DistanceFrom property of the shape returns the
distance between two shapes
SpatialRelation property describes the
relationship between two shapes
SpatialNeighbors property of a shape returns
shapes meeting relationship criteria
SpatialSearch property of shape, page, or master
returns shapes near a point
Visio offers several properties for determining shape proximity.
DistanceFrom property of the shape returns the distance between two shapes
SpatialRelation property describes the relationship between two shapes
SpatialNeighbors property of a shape returns shapes meeting relationship criteria (For an
example, see Spatial Relation Office.vsd)
SpatialSearch property of shape, page, or master returns shapes near a point (For an
example, see Which Shapes are in View.vsd)
130
130
SpatialRelation
SpatialRelation
Use to determine relationship between two shapes
The SpatialRelation property returns one of

visSpatialOverlap, visSpatialContain,
visSpatialContainedIn, visSpatialTouching
= visSpatialOverlap
The SpatialRelation property is used to determine the relationship between two shapes. It can
determine if two shapes overlap or touch, or if one is inside the other.
Demonstration: Shape Relationships

1. Open <install folder>\Demos\Vol3\Getting Data from Drawings\Spatial Relation.vsd.
2. Note: Before you establish the shape relationship, both shapes need to be selected.
3. Move the small square so its edge touches the edge of the large square, and click the
Relationship button.
4. Move the small square so it overlaps the large square, and click the Relationship button.
5. Move the small square so it is within the bounds of the large square, and click the
Relationship button.
6. Repeat step five, but this time, change the shape selection order.
131
131
Lab 3.4: Calculate the Area of a Shape

Lab 3.4: Calculate the Area of a Shape
Open Shape Area.vsd
Add code to calculate the area of a shapes:
Alignment Box
Geometry
Loop through the Shapes collection to calculate the

total area of all selected shapes
Points to Consider
Area based on width and height (parameters of shape alignment box) will be larger than area based on
geometry.
Look for a Shape property that calculates area based on shape geometry.
132
132
Review: Getting Data from Drawings

Getting Data from Drawings I: Conclusion
Iterating through a Collection
Getting Information from Documents, Pages, Shapes,

and ShapeSheets
Getting the Selection Object
Questions
1. What would be an advantage of using the ActivePage property? What would be a
disadvantage?
2. What is the difference between Open and OpenEx?
3. Under what circumstances would you use CellsSRC?
4. How would you find out whether a Shape object represents a group shape?
Answers
1. The ActivePage property is a quick way of getting a page without going through a document
object. However, it only works if the active window is a drawing window.
2. The Open method opens a document as the original. The OpenEx method has an additional
parameter that is use to specify how the document is to be opened, e.g., as read-only.
3. Use CellsSRC when a section has an non-fixed number of rows or when the number of cells
in a row can vary, such as in the geometry section.
4. Use the shapes Type property to test whether it is a group.
133
133
134
134
Managing Events
135
135
Learning Objective
Even though you can respond to user events through the ShapeSheet, Visio has a more robust,
programmable event mechanism. This Event object model allows the programmer to set up event
handling for a larger set of events.
In this section you will see how your solution can respond to ShapeSheet events. You will also get an
introduction to the Visio event object model and learn how to use Visual Basic for Applications to create
code behind events.You will first look at handling basic events through the management of ShapeSheet
cells. When something happens to a shape, such as when it is moved or resized, some cell values
change. You can detect these changes in the ShapeSheet and cause another action to occur as a result.
More directly, the ShapeSheet has an Event section that has event cells (TheText, EventDblCick,
EventXFMod, and EventDrop) in which formulas can be placed. These cells evaluate whenever the event
occurs.
Beyond the ShapeSheet, events can be handled through Visual Basic for Applications as code behind
events. This uses the underlying Visio object model to create and respond to events.
136
136
Introduction
Introduction
In Visio, an event occurs as a result of an action
Solution becomes aware of the change
Solution does something in response to this change
Events can occur as a result of a user action or as a

result of a program being run that controls Visio
Before diving into code behind events, you should be clear about what is an event.
A dictionary definition of an event is an occurrence or incident, especially one of significance. As a
programmer, you want to know when these events occur and do something in response to the event.
Keep in mind that events can occur as a result of a user action or as a result of a program being run that
controls Visio.
137
137
Cell Dependencies
Cell Dependencies
A formula may depend on other cells
PinY =(BeginY+EndY)/2
EndY =PAR(PNT(Sheet.2!Connections.X1,
Sheet.2!Connections.Y1))
In this example, the dependency network is implied
PinY depends on EndY, which depends on

Sheet.2!Connections.X1
Value of Connections.X1 changes and forces
EndY and PinY to recalculate
Within the formula of a cell can be references to other cells. This creates intercell relationships or cell
dependencies.
These dependencies are implied by the cell names used in the formulas. In the slide example, PinY
depends on BeginY and EndY. EndY, in turn, depends on a connection point in Sheet.2.
Because of the dependency that has been established, when the value of the connection point changes,
the value of the EndY cell is recalculated. If the value of the EndY cell changes, the PinY cell is
recalculated.
Note:
The Visio product engine does not recalculate all cells whenever a shape changes.
Instead it establishes a dependency network so that it only recalculates cells that
have the potential to change.
138
138
Force Dependencies with DependsOn

Force Dependencies with DependsOn
Force cell dependencies by using the DependsOn

function
Creates a cell reference dependency on the cells

specified in the list of trigger cells
Typically used in a User-defined or Scratch cell
=RunAddon("string") + DependsOn(trigger cell)

runs an add-on whenever the trigger cell changes
=Setf("Cell",formula) + DependsOn(trigger cell)
'resets Cell to some formula or value whenever the
trigger cell changes
In addition to creating intercell dependencies through the use of another cells name, you can force cell
dependencies by using the DependsOn function. DependsOn creates a cell reference dependency on
the cells specified in the list of trigger cells. The function always returns FALSE (the value 0) and thus has
no effect on the final value of the cell when used in this fashion.
A typical use of the DependsOn function is to cause some action to occur whenever a cells value
changes. In the slide, the first example runs an add-on whenever the trigger cell changes. The second
example will reset Cell to some formula or value whenever a trigger cell changes.
In these examples the final result of the User-defined or Scratch cell is irrelevant. However, the
developers use of DependsOn is not limited to these types of examples.
139
139
DependsOn Example
Here is a more practical example. Suppose you want to set a shapes color from the shape data dialog,
but dont want to interfere with the users ability to change a shapes color using the normal user
interface tools. In addition, if the user does change the shapes color through the user interface, you
would like the shape data field to hold the current value.
A shapes color is kept in its FillForegnd cell. Assume that a shape data cell, Prop.Color, has been created
to hold the value to be displayed in the shape data dialog. It is not sufficient to just display the
FillForegnd cell in the shape data dialog by referencing it from Prop.Color. A change to Prop.Color would
overwrite this formula.
The solution lies in creating two User-defined cells. In these cells place the formulas:
=DependsOn(Prop.Color)+Setf(FillForegnd,Prop.Color)
=DependsOn(FillForegnd)+Setf(Prop.Color,FillForegnd)
The first resets FillForegnd whenever the user changes color though the shape data dialog.
The second changes the value displayed in the shape data dialog whenever the user changes the shapes
color using other user interface tools.
140
140
Using this method insures the information in each place is the most current.
Tryit! DependsOn
1. From your student CD, open <install path>\Demos\Vol3\Managing Events\DependsOn
Example.vsd.
2. Display the shape data window. Data > Shape Data Window.
3. Change the shapes fill color through the user interface. Note that the shape data field is
updated.
4. Change the shape data value. Note that the shapes fill color updates.
Note:
The Visio product engine allows circular references in situations like this and
prevents the cells from being recalculated infinitely.
141
141
SetAtRef ShapeSheet Function
The SetAtRef ShapeSheet function creates a cell dependency just as we saw in the DependsOn example,
but it gives greater control over what action is to be taken when the cell change occurs.
Demonstration: SetAtRef
1. From your student CD, open <install path>\Demos\Vol3\Managing Events\SetAtRef
Example.vsd. Note that there are 3 examples on 3 separate pages in the drawing.
2. Example 1
a. Choose drawing page SetAtRef
b. Display the shape data window. Data >Shape Data Window.
c. This example is similar to the DependOn example we looked at earlier except that
the cells being controlled are the Width and Height cells. Modify the shapes Width
or Height by using any of the UI tools or by modifying the shape data fields.
d. Note the SetAtRef formulas in the shapes Width and Height cells. The SetAtRef
function redirects any changes to the Width and Height cells to go to the
corresponding shape data cells.
3. Example 2
a. Choose drawing page SetAtRefExpr
142
142
b. This example uses SetAtRefExpr to force the shape to snap to a custom grid, in this
case a 1 inch by 1 inch grid. View the ShapeSheet to see the formulas.
4. Example 3
a. Choose drawing page Associate without glueing
b. The ShapeSheet formulas are in the Child shapes PinX and PinY cells. Example
shows use of SetAtRef, SetAtRefExpr, and SetAtRefEval together to create a shape
that snaps to a fixed grid size. The grid size is defined in User cells.
143
143
Use the ShapeSheet to Manage Events
The Event section cells of the ShapeSheet provide the next level of event management for the Visio
developer. These cells can be used to program events triggered when:
The text is changed (TheText)

The shape is double-clicked (EventDblClick)
The shapes position, size, or orientation on the page is changed (EventXFMod)
The shape is dropped (EventDrop)
Multiple shapes are dropped on the page at the same time (EventMultiDrop)
You will see an Event cell called TheData. This currently does nothing and has been in the product since
its earliest days.
144
144
Use Formulas Over Code

Use Formulas Over Code
Putting formulas into Visio cells is the most

fundamental way to incorporate event handling into
a Visio solution
Do not put code behind events when putting

formulas behind cells suffices
Shapes first, then code!
However, your solution may require more robust

event functionality and easier maintenance
In this case, use an add-on!
This completes our discussion of handling events through the ShapeSheet. As you have seen several
times in this class, putting capabilities into the ShapeSheet is preferred to writing code. The ShapeSheet
offers a rich set of features and functions that make the development of code behind events
unnecessary. Shapes are easily transferred when drawing files are exchanged.
However, if you need a more robust and expandable solution, writing event handling code in an add-on
may be easier to maintain. But remember - shapes are part of the Visio drawing file, while add-ons are
not!
145
145
Visual Basic for Applications Code Behind Events

Visual Basic for Applications Code Behind Events
Events are defined as part of the type library
Objects have events defined for them and an event

applies only to specific object types
The ShapeAdded event fires for a page when a shape

is added to the page
Can use code behind events in Visual Basic
Objects have events defined for them, such as the ShapeAdded event when a shape is added to a Visio
document and the Click event of a button on a form when the button is pressed.
Take a look at how Visual Basic and Visual Basic for Applications have helped programmers set up event
handlers.
Always keep in mind that Visual Basic for Applications uses the underlying Event Object Model defined
in the Visio Type Library to respond to events. It utilizes this event model to allow you to put code
behind events.
146
146
Supported Events
There are many supported automation events in Visio. Certain events are only available on particular
source objects. For example, you can only respond to the AfterModal event on an Application source
object.
One key point about the Before events is that they are just notifications that the event is about to
happen. You cannot programmatically stop the event from occurring.
For example, when the BeforeSelectionDelete event is triggered, the selection passed to the event
handler is committed to be deleted. You cannot stop the deletion.
147
147
Hierarchical Event Sets

Hierarchical Event Sets
Pick the source object that makes the most sense, as

many events are sourced by several objects
Page.ShapeAdded
Fires when shape added to page
Document.ShapeAdded
Fires when shape added to any page in document
Application.ShapeAdded
Fires when shape added to a document open in
application
Both the VBA Object Browser and the Developer

Reference Help list the events that each object sources
Some events, such as the ShapeAdded event, can be sourced by different objects. The ShapeAdded
event can be detected at the page level, at the document level, or at the application level.
The number of events your code will process can be very different depending upon which object you
choose as the source object for your event. For example, at the application level, the ShapeAdded event
will fire any time a shape is added to any page in any open drawing in the application.
If the page object is used as the source object, the event fires only when a shape is added to that page,
but not when a shape is added to any other page in the application.
You can determine which objects source an event by using either the Object Browser in Visual Basic for
Applications or the Developer Reference help from the Visio Help menu.
148
148
Built-In Document Events
Like other Microsoft Office applications that contain Visual Basic for Applications, Visio has implemented
a class known as ThisDocument.
A large number of events have already been provided, which means you have the ability to use the
Visual Basic code framework and write your own procedures associated with any of these events.
Try it! Add Code Behind Events for ThisDocument

1. In a blank drawing, open the Visual Basic for Applications code window.
2. In the Project Window, right-click ThisDocument and choose View Code.
3. In the code window for ThisDocument, in the left-hand drop down list box, choose
Document.
4. In the right-hand drop down list box, choose ShapeAdded.
5. The Document_ShapeAdded event procedure is created. Add the code:
Msgbox Shape added to the document
6. Go back to the Visio drawing and add a shape to the page. This will trigger the ShapeAdded
event and execute the Msgbox statement above.
149
149
150
150
WithEvents Keyword
WithEvents Keyword
Can use the WithEvents keyword to set up code

behind events for any source object
Need to bind the WithEvents variable to a live object

to get event handling to work
For example
Dim WithEvents oPage as Visio.Page
Set oPage = Visio.ActivePage
Visual Basic for Applications supports the keyword WithEvents that allows you to set up event handling
for any source object.
Use the Visual Basic for Applications keyword WithEvents to declare an object variable for the Visio
object whose events you want to handle. For example:
In addition to the usual access to the page objects properties and methods, this declaration gives the
oPage variable the capacity to handle events when bound to a particular instance of a page. Assigning
Visio.ActivePage to oPage enables oPage to source events for the page represented by Visio.ActivePage
at the time of the binding.
Demonstration: WithEvents
1. In a blank drawing, open the Visual Basic for Applications code window.
2. In the General Declarations section of ThisDocument, add the code:
151
151
Note that oPage is added to the left-hand drop down list box in the code window and you
now have access to the events that a page object can source.
3. In the Document_RunModeEntered event procedure, add the code:
Set oPage = Visio.ActivePage
4. In the oPage_ShapeAdded event procedure, add the code:

Msgbox A Shape was added to Page: & oPage.Name
5. Click the Design Mode button twice to toggle from Design to Run mode, and back.
6. Add shapes to the new drawing page. The message box should be displayed each time a
shape is added to the page.
152
152
Controls
You do have the ability to add controls to your Visio drawing. Visio has a Design Mode and a Run Mode
to allow you to work with the controls. In Design Mode you can place controls in the drawing and set
their properties. The drawing must be in Run Mode for the controls events to fire and allow the user to
interact with the controls as she would in a typical Windows application.
Try it! Add a Control to a Visio Drawing

1. Open a Blank Visio drawing.
2. From the Developer tab, choose Insert and choose a CommandButton.
3. Move and size the control as needed. You can do this, as with any shape, by using the
selection handles.
4. Edit the control by setting its properties. You can do this by right-clicking and choosing
CommandButton_Object > Control Properties, or by editing the controls properties from
the VBA properties window.
5. In the Click event for the command button, add the following code. Note that the name of
the control has been added to the code window in the left-hand drop down list box.
MsgBox I am a live control!
153
153
6. Put the drawing in Run Mode (Developer tab and toggle the Developer Mode switch) and
click the button.
154
154
Query Events
Query Events
Query events give you a way to cancel the event action

before it occurs
If any event handler returns True, the operation is

canceled
If all handlers return False (don't cancel), the action will

be performed
In most cases, one or more of the Before events will fire

after the Query event has fired
Query events triggered only by actions from the UI not

through automation
Query events give you a way to cancel the event action before it occurs.
For example, if you have shapes in your custom solution that you do not want the user to delete from
the page, you would include the QueryCancelSelectionDelete event in your event sink. Once you sign up
for this event, you can add code to respond to it. Then, if a user selects a shape on the page, and presses
the delete key to delete it, you can cancel the delete action, and notify the user.
Query events are triggered only by actions from the UI not through automation.
Here are some of the Query events that Visio provides:
QueryCancelConvertToGroup
QueryCancelDocumentClose
QueryCancelMasterDelete
QueryCancelPageDelete
QueryCancelSelectionDelete
QueryCancelUngroup
QueryCancelQuit
155
QueryCancelWindowClose
155
156
156
Query Events (Continued)

Query Events (Continued)
In this example, the events are scoped to the page

QueryCancelSelectionDelete
True
(Cancel)
False
(Dont Cancel)
SelectionDeleteCancelled
Shape is not deleted.
BeforeSelectionDelete
& BeforeShapeDelete
Shape is deleted.
This is the event sequence for the QueryCancelSelectionDelete event, as it occurs in Visio.
The Before events fire if the Query event is not cancelled.
Note:
Try it! Query Events

1. Open <install folder>\Demos\Vol3\Managing Events\Query Events.vsd
2. Select one of the shapes and click the command button.
This calls a simple Selection.Delete method, and the BeforeSelectionDelete and
BeforeShapeDelete fire.
3. From the Quick Access Toolbar, choose Undo (or use the shortcut, Ctrl-Z).
4. Select another shape on the page, and press the delete key on your keyboard.
This time, the QueryCancelSelectionDelete event is called.
5. Click the Yes button on the message box, to cancel the deletion.
6. Repeat step 5, but choose the No button on the message box for a different result.
7. Open the Visual Basic Editor and review the code.
157
157
Marker Events
Marker Events
Sometimes your event handler modifies the drawing
This can cause additional events to fire
Was event caused by user or by some other event

handler?
Can cause loops responding to self-caused events
By using the MarkerEvent event in conjunction with

the QueueMarkerEvent method, your program can
distinguish events it caused from those it did not cause
Either the MarkerEvent event context string or

sequence number can be used to correlate
QueueMarkerEvent calls with MarkerEvent events
Marker events may be used to ignore events caused by other events.

Sometimes your event handler modifies the drawing, and this can cause additional events to fire. Was
the event caused by user or by some other event handler? This situation can cause loops responding to
self-caused events.
The classic example is when the CellChanged event resets the value of cell. This causes another
CellChanged event, which may cause the value of the cell to change again. You need to be able to
distinguish between the original event and those that are generated by the event manager.
Unlike other events that Visio fires, a client program causes the MarkerEvent to fire by invoking the
QueueMarkerEvent method.
The MarkerEvent passes both the context string and sequence number to the MarkerEvent, event
handler. Either the context string or sequence number can be used to correlate QueueMarkerEvent
calls with MarkerEvent events. This way, your program can distinguish events it caused, from those it
did not cause.
158
158
For more information on Marker Events, see the sample file, Marker Events.vsd, and search the Visio
Developer References Automation section for the MarkerEvent event and the QueueMarkerEvent
method.
159
159
Scoping Methods
Scope Events
Visio also provides the scoping methods

BeginUndoScope and EndUndoScope to set a
scope range
These cause the event procedures EnterScope and

ExitScope to fire
Together these can be used to produce results similar

to using marker events
Wrap your operations with these scope methods to

know whether the events you receive are the result of
action that you initiated
Visio also provides scoping methods BeginUndoScope and EndUndoScope to set a scope range. These
methods start and end a transaction for Visios Application object.
Note:
If you call the BeginUndoScope method, you should call the EndUndoScope
method as soon as you are finished with the actions that comprise the scope.
These methods in turn cause the event procedures EnterScope and ExitScope to fire. When EnterScope
fires, it records extra information in the EventInfo property of the Application object. This textual
description is then accessible in the MoreInfo argument of the VisEventProc.
Together, these methods and events can be used to produce results similar to using Marker events.
For more information on Scoping methods, see the files Undo Scope I.vsd and Undo Scope II.vsd in the
Demos student files.
160
160
Lab 3.5: Create a Shape Area Calculator
Points to Consider
Use ActivePage for your page reference.
Make sure the area that you add to the total is for shapes only.
161
161
Other Considerations
You can actually shut event handling down altogether. This might be useful when debugging. It can be
done through the Trust Center or through the object model by setting the Application.EventsEnabled
property.
To start Visio without automation events and without VBA:

1.
2.
3.
4.
5.
6.
7.
Start Visio normally.

Enter the Trust Center (File > Options > Trust Center > Trust Center Settings)
Click Macro Settings, and then click Disable all macros without notification.
Click Add-ins.
Click to select the Disable all Application Add-ins check box.
Click OK.
Exit Visio, and then restart Visio.
It is sometimes necessary to build a model to contain run-time data to support your drawing. But how
does this model get reconstructed when a drawing is closed and then reopened? The
DocumentOpened event can be used to make data persist. This works fine when you are through with
development and are ready to distribute your solution. However, it can be a nuisance during the
development process to always be opening and closing the drawing in order to reinitialize data. 162
162
Instead of DocumentOpened, use RunModeEntered to initialize run-time data. When a document is

opened, both the DocumentOpened and the RunModeEntered events fire. However, it is much easier
to initialize your run-time data during the development process by just switching to Design Mode and
then back to Run Mode.
163
163
Review: Managing Events
In this module you have seen how to handle events in Visio by using simple cell dependency techniques
in the ShapeSheet, by utilizing ShapeSheet event section cells, and by using the WithEvents keyword in
Visual Basic for Applications. Here are some questions based on the material you just covered.
Questions
1. Under what circumstances would you want to use Automation event handling over
ShapeSheet event handling?
2. What is the name of Visios pre-defined base class?
3. What does the WithEvents keyword allow you to do?
Answers
1. Automation event handling is preferred when a more robust solution is required, beyond
what can be accomplished in the ShapeSheet.
2. ThisDocument
3. Set up event management for any source object.
164
164
Automating Data Graphics

In this module we will take an in-depth look at data graphics. The implementation of data graphics
beginning with Visio 2007 primarily utilizes the existing environment and objects of Visio 2003. Data
graphics and data graphic items are maintained as masters in the Visio object model (albeit hidden
except through the Drawing Explorer window). Therefore, when working with data graphics you are
working with Visio master objects.
The GraphicItem and GraphicItems objects are new for Visio 2007. The GraphicItem holds the detailed
information about a data graphic item, such as its position, and the GraphicsItems object is a collection
of the individual items that make up the data graphic. The GraphicsItems collection has been added as a
property to the Master object. The Shape object has a DataGraphic property that holds the reference to
the data graphic applied to the shape.
Data graphics can be customized. There are several built in text and data bar callouts as well as several
built in icon sets. These callouts and icon sets can be modified and new ones can be created, most easily
by copying and modifying existing data graphic items.
When a data graphic is applied to the shape, the data graphic master and the shape are grouped. You
can then work with the elements of the group just as in previous versions of Visio or you can modify the
data graphics within the Data tab of the ribbon. When these masters are modified the changes are then
reflected throughout the drawing just as when a master is modified in the Document Stencil.
Note:
Modifications made using the Data Graphics within the ribbon will override any
manual modifications made to the grouped shape.
Module Objectives
After completing this module you will be able to:
Work with data graphics with the Visio user interface to add text and data bar callouts
Understand how data graphics are managed by Visio and where information about them
exists in the Visio object model
Understand key ShapeSheet cells required by data graphics
Customize data graphics with the Visio user interface to add additional graphic items to
data graphics
165

165
Modify data graphic items to fine tune their behavior within the drawing environment
Create icon sets
Customize and manage data graphics with automation code
Manage data graphics in the drawing environment by making data graphics available for
new drawings
166
166
Lesson 1: Data Graphics Concepts

Microsoft Visio offers tools for visualizing information. Data can be connected from external sources
and linked to individual shapes. A variety of graphics can be applied to the shapes to display
information about the data they contain. The data can be refreshed from the external source and the
graphics can update automatically based on the values stored in the data.
Data Graphics lets you present information in a concise, understandable format. Text, geometry,
formatting, and graphics are combined to help users identify issues, illustrate patterns in data, and
communicate status. Data Graphics can be expressed in many different ways to give the user a wide
variety of options for visualizing his data.
This lesson covers that full range of options for creating and customizing Data Graphics.
Lesson Objectives
After completing this lesson you will be able to:
Create new data graphics and customize existing data graphics
Apply text, data-bar, and icon set callouts and use color-by-value to visualize data
Create new text, data-bar, and icon-set callouts
Manage Data Graphics objects in a document
Go beyond the basics and customize your own data graphic items
Overview of Objects / Methods / Properties

Included in this section is a description of the objects, methods, and properties related to creating and
managing data graphics in Visio. There are other objects, properties, and methods that come into play
when developing solutions with data graphics. These will be covered as they are needed.
Where appropriate, there are bits of sample code sprinkled throughout this lesson which illustrate how
to use these features programmatically.
167
167
Data Graphics
A GraphicItem is responsible for a single adornment such as a data bar or text callout shown on a Data
Graphic. A GraphicItems collection of these make up a single Data Graphic which is held in Visio in the
form of a hidden Master on a stencil. The master is of type visTypeDataGraphic.
The relationship of the data graphic objects to other portions of the Visio object model is shown in the
graphic below.
Methods
GraphicItem object
GetExpression
SetExpression
Description
Returns the current expression for the primary key column
corresponding to the specified field.
Sets the value of the expression string that is part of a
GraphicItem object's rule, against which shape data is evaluated.
GraphicItems object
AddCopy
Description
Adds a copy of a GraphicItem object to the GraphicItems
collection.
Master object
DataGraphicDelete
Description
Deletes the Master object of type visTypeDataGraphic from the
Masters collection of the document.
Masters object
AddEx
Description
Adds a master of the specified VisMasterTypes object to the
168
168
Masters collection.
Properties
GraphicItem object
DataGraphic
HorizontalPosition
PositionRelativeTo
Tag
UseDataGraphicPosition
VerticalPosition
GraphicItems object
DataGraphic
Master object
DataGraphicHidden
DataGraphicHidesText
DataGraphicHorizontalPosition
Description
Returns the Master object of type visTypeDataGraphic that is the
parent of the GraphicItem object, the GraphicItems collection,
the Selection object, or the Shape object.
Gets or sets the horizontal position of a graphic item relative to a
container or shape, as VisGraphicPositionHorizontal.
Gets or sets whether the graphic item is positioned relative to a
container or to a primary shape, as
VisGraphicPositionRelativeTo.
Gets or sets an expression that stores extra data needed for your
program. For example, the name you want to apply to a graphic
item. Not used by Visio.
Gets or sets whether a GraphicItem object inherits the
DataGraphicHorizontalPosition property setting and
DataGraphicVerticalPosition property setting of the data graphic
master to which it belongs (when set to True), or whether to
apply the GraphicItem object's own HorizontalPosition setting
and Vertical Position setting (when set to False).
Gets or sets the vertical position of the graphic item relative to a
container or shape, as VisGraphicPositionVertical.
Description
See GraphicItem object.
Description
Determines whether the data graphic is visible in the
Data Graphics task pane.
If set to True, hides the text of the primary shape
when a data graphic master is applied. The default is
False.
Gets or sets the horizontal position of a data graphic
relative to the shape it is applied to, based on the
169

169
DataGraphicShowBorder
DataGraphicVerticalPosition
GraphicItems
specified VisGraphicPositionHorizontal value.

Gets or sets whether a border appears around
GraphicItem objects whose UseDataGraphicPosition
property is set to True, or that occupy the same
position as the data graphic of which they are a part.
Gets or sets the vertical position of a data graphic
relative to the shape it is applied to, based on the
specified VisGraphicPositionVertical value.
Returns the GraphicItems collection of the Master
object. Read-only.
Creating Data Graphics Masters

Data graphics can be added to a drawing at any time. They may already be part of a drawing if the
template used to create the drawing contained data graphics or if shapes dropped on a page had a data
graphic associated with them.
Data graphics can be created from scratch or can be copied from existing data graphics and then
modified.
Basics of creating a Data Graphics Master

A new data graphic can be created easily using the Visio interface that is presented in the Data tab (Data
> Data Graphics). Within the task pane completely new data graphics can be created using the
command New Data Graphic. To create a data graphic from an existing data graphic, right-click the data
graphic and choose Duplicate. To modify any data graphic, right-click the data graphic and choose Edit
Data Graphic
170
170
Try it!
1. From the Samples folder open Viewing Data Graphics.vsd
2. Display the Document Stencil and note which masters are displayed.
171

171
3. Display the Drawing Explorer window and note which masters are displayed. Are they the
same?
4. Create a new data graphic (Data > Data Graphics > Create New Data Graphic). Give it a
meaningful name that you will recognize. Does it show in the Document Stencil? Does it
show in the Drawing Explorer?
Viewing a data graphics master

Once a new data graphic has been created, it can be viewed in the Drawing Explorer window. Dont look
for it in the Document Stencil because the data graphics master is hidden. There is a property of the
master object, the Hidden property, that is used to control the display of the master in the stencil
window. However, this property is ignored by the Drawing Explorer, which shows every master
regardless of the Hidden property value.
Try it!
1. Open the VBA window. Make sure the Immediate window is displayed.
2. In Visio use File > Options > Advanced to check the number of Undo levels. Set the
number to at least 30.
3. Run the macro ListMasters. All masters, along with their Hidden property are displayed
in the Immediate window.
4. Run the macro MakeAllMastersShow. This changes the value of the Hidden property of
all masters to False so that they will show in the Document Stencil window.
5. Note the data graphics masters in the Document Stencil and then Undo (Ctrl-Z) the results
of running the macro to again hide the data graphics masters.
Creation with automation
Note:
When Visios macro recorder is turned on the Data Graphics menu is deactivated.
Thus recording anything that happens in the data graphics task pane is not
possible.
The file Working with Data Graphics.vsd in the Sample folder has the following sample code in it for
creating a data graphic master.
Public Sub AddEx_Example()
Create an empty data graphic master
Dim vsoMaster As Visio.Master
172

172
Set vsoMaster = Visio.ActiveDocument.Masters.AddEx(visTypeDataGraphic)

Debug.Print vsoMaster.Name
End Sub
Try it!
1. Open Working with Data Graphics.vsd from the Samples folder. Run the macro (View >
Macros > InterestingMacros.AddEx_Example).
2. A new master can be seen in the Drawing Explorer window. The name of the new master
is displayed in VBAs Immediate window.
3. The empty data graphic also shows in the Data Graphic task pane, but does not show in
the Document Stencil. The AddEx method makes it hidden automatically.
4. There is a data graphic called DGDisposition included in this file. Run the macro
DuplicateDataGraphic to copy this data graphic.
5. The new data graphic shows in the Data Graphic task pane.
The code for DuplicateDataGraphic is below.
Sub DuplicateDataGraphic()
'Copy the data graphic named "DGDisposition"
ActiveDocument.Masters.Drop _
ActiveDocument.Masters.Item("DGDisposition"), 86, 121
End Sub
Creating Data Graphics Items

Overview of Data Graphics
A data graphic is a collection of data presented in a diagram either as a set of graphical widgets or by
formatting shapes that contain data. The widgets are known as callouts. These callouts are placed on or
next to a shape that contains data, referred to as the target shape in this document. The data displayed
is typically Shape Data, but other shape information and custom expressions can also be displayed.
173
173
Note:
Dont confuse the data graphics term callout with the new Callout shapes that are
introduced with Visio 2010. These are two separate entities.
Visio provides three types of callouts, as listed in Table 1.

Table 1. Data Graphics callout types
Type
Description
Text callouts
Display data as text.
Data-bar callouts
Display data by modifying some visual aspect of the callout,

such as the amount filled in a progress bar.
Icon-set callouts
Display data by using icons that appear or disappear based on

conditional statements.
A fourth way of displaying data in a shape is by using Color by Value. This method applies conditional
formatting to the shape itself rather than displaying information in a callout.
Figure 2. Data Graphic applied to regular shape
174
174
Figure 3. Data Graphic applied to pivot node
A data graphic consists of the set of callouts and Color by Value rules used to display data on a shape.
Each shape can have only one data graphic applied at a time, but a data graphic can consist of many
callouts and Color by Value rules. You apply data graphics in the Data Graphics task pane.
More Information:
On the drawing page, a data graphic is a set of special shapes added to a target
shape that contains the data to be displayed. When you apply a data graphic, the
target shape becomes a group (if it is not already a group) and the data graphic
shapes are added as subshapes of that group. Data graphic shapes usually appear
on top of any existing subshapes that are included in target shapes.
Create Data Graphics Item with the Visio user interface

There are many built-in text, data-bar, and icon-set callouts available with Visio. As built in callouts, they
do not show in the Masters collection of the Drawing Explorer window. However, once one of these
callouts is added to a data graphic it is added to the Masters collection.
Visio recognizes a shape as a data graphics callout if the topmost shape in the master contains the userdefined cell User.msvCalloutType.
Text callouts and Data bar callouts

There are eight built-in text callouts provided with Visio. These are shown in the graphic below.
175
175
There are eleven built-in data bar callouts in Visio. Most of them are shown in the graphic below.
176
176
These callouts can be added to any data graphic. Once they are added, they show in the Masters
collection in the Drawing Explorer window. Once in the Masters collection of the drawing they can be
edited and renamed to form a customized callout.
Working with Text callouts and Data bar callouts are very similar.
Try it!
1. Create a new blank drawing.
2. Create a new data graphic (Data > Data Graphics > Create New Data Graphic). The New
Data Graphic dialog is displayed.
3. Select new Item.
4. For Data field: choose More Fields and then select Geometry and Width.
5. For Displayed as: choose Text. The New Text dialog is displayed.
6. Select the Text callout.
7. Under Details > Value Format choose the browse button and then General and check
Show Units.
8. Under Details set Label to Width.
9. Close the dialog. In the Drawing Explorer note that two new masters are added, Data
Graphic and Text callout.
10. Draw a rectangle and apply the data graphic to it. It will display the shapes width.
11. In the Drawing Explorer window click the Text callout and change its name to My Text
callout.
12. Right click My Text callout and choose Edit Master shape. Change the line color and the
text color in the master. Close the master editing window. (Note: you may have to force a
redraw in the drawing for the results to be seen. Moving the shape should do it or reapply
the data graphic).
177
177
13. In the Data Graphics work area choose Edit Data Graphic and choose New Item. Choose
any field for the data then choose Text. Note that the My Text callout is in the list as well
as the original built-in Text callout. Close the Edit Data Graphic dialog.
Note:
The built-in callouts cannot be changed. If you use one in a data graphic and
modify it as was done above, but dont rename it, you will see two versions of the
callout in the callout list, the one you modified and the original built in version. It is
best to rename a callout if it is being modified so that it can be more easily
identified in the callout list.
14. Select the My Text callout master in the Masters collection of the Drawing Explorer
window. Right click and choose Edit Master Shape.
15. In the master drawing window right click the shape and choose Show ShapeSheet. The
first user-defined cell is shown below. Note that the callout type is set to Text Callout.
16. In the same ShapeSheet look at the Shape Data section. Note that the first seven
Prop.msv rows correspond to the elements in the Details section of the New Text dialog
we saw when editing the data graphic. The last row Prop.msvCalloutField holds the value
of the data element being displayed.
The Shape Data rows define the presentation in the Details section of the New Text dialog. The Label
specifies the label displayed. The Type field controls the type of data (boolean, string, list, etc.). Format
specifies list elements.
178
178
A very important column, not seen in this figure, is the Invisible column. Note that Visio uses Shape
Data rows in callouts in highly specialized ways and that these rows are not intended to be used as
standard Shape Data properties. For this reason, the Invisible cell should always be set to True to hide
these rows from the user.
Put a custom formula in a callout

It is easy to modify a data graphic to display Shape Data from a shape. It is also possible to display other
information about a shape, such as its Width or a user-defined cell. It is even possible to display
calculated data that is derived from several data elements.
To create and display a custom formula choose More Fields in the Data field section of the Text or
Data bar callout. The following dialog is presented. Note that it is very similar to the dialog for a Text
Field and it is used in exactly the same way. In the image below Geometry is chosen as a category and
then Width is chosen as the Field name. Note that there are several other categories and each of them
contains several fields that can be chosen.
The real power in this dialog comes from the last Category Custom Formula. From here one can create
calculated fields and format the data using the Format function.
Try it!
1.
2.
3.
4.
5.
Create a new data graphic.

Add a New Item
For Data field choose More Fields
Choose Custom Formula. The Custom formula field at the bottom becomes active.
Enter into the Custom formula field
179

179
="Aspect Ratio = "&Format(Width/Height,"0.0")
6.
7.
8.
9.
10.
Lets take this formula apart from the inside out. Width and Height are references to the
shapes Width and Height cells. Width divided by Height is commonly referred to as the
aspect ratio. Format is a function that takes a value and formats it based on a formatting
string which in this case is the string 0.0. This says to display a number to one decimal
place. On the left side of the formula is the constant string Aspect Ratio followed by &
which is the concatenation operator for putting strings together.
For Displayed as: choose Text and choose callout Heading 3.
Select OK to close this dialog.
In the New Data Graphic dialog set the Callout position to Left and Above Shape.
Select OK to close the dialogs.
Draw a rectangle and apply the data graphic. Resize the rectangle and observe that the
aspect ratio value changes.
Add a field to a data graphic

In this lesson we will add a new field to an existing data graphic that will be used to control the fill color
of the header bar within the data graphic.
Visio recognizes a shape as a data graphic through the user-defined cell User.msvCalloutType. This is
set to Text Callout or Heading for a text callout, Data Bar for a data bar callout and Icon Set for
an Icon set callout.
You can define properties for text callouts or data bars to expose in the Edit Item dialog. Shape Data
rows are used to define the fields to be displayed when editing a data graphic.
Important:
The names of the Shape Data rows used to display fields in a callout must begin
with Prop.msvCalloutProp
180
180
Try it!
Start from the data graphic used in the last section to display the aspect ratio in a Heading 3 callout.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
In the Drawing Explorer window rename the Heading 3 callout to My Heading.

Right-click My Heading and choose Edit Master Shape.
Right-click the shape and choose Show ShapeSheet.
In the ShapeSheet for the My Heading master add a row to the Shape Data section.
Fill in the following cell values for the new row.
Name the row Prop.msvCalloutPropColor. Dont type Prop. This will be added
automatically.
Label = Heading Color
Prompt = List
Type = 1
Format = Red;Green;Blue
Value = Index(1,Prop.msvCalloutPropColor.Format)
Invisible = True
Close the ShapeSheet and the master drawing window. Choose Yes to update My
Heading.
Check what has been done so far in the Data Graphics task pane. Edit the data graphic
and edit the Text callout and look for the new properties. The changes may not update
automatically. Force a refresh by changing the Callout to something different and then
back again. You should now see the new row Heading Color and be able to choose
between the colors Red, Green, and Blue.
Close the dialogs for editing the data graphic.
In the Drawing Explorer window right-click My Heading, choose Edit Master Shape, and
then select the shape and choose Show ShapeSheet.
Set the FillForegnd cell in the Fill Format section to
=GUARD(LOOKUP(Prop.msvCalloutPropColor,Prop.msvCalloutPropColor.Format)+2)
This formula returns the values 2, 3, and 4 which correspond to the colors Red, Green, and
Blue when used in the FillForegnd cell.
11. Close the ShapeSheet and close the master drawing window. Choose Yes to update My
Heading.
12. Edit the Data Graphics (Data > Data Graphics > Edit Data Graphic) by changing the color
in the field Heading Color. Below is the result when the color Red is chosen.
181
181
Icon-set callouts
You can use existing icon sets or create your own either as Visio geometry or by using image files.
An icon-set callout is a shape that can display up to five different images, depending on a value provided
by the Data Graphics feature. Icon-set callouts are different from text callouts and data-bar callouts
because the icon-set callout does not use the data-field value directly. In the Edit Icon Set dialog box,
you can define a set of conditional statements for icon-set data that determines which icon should be
displayed. From the conditional statements, Visio creates a single ShapeSheet formula that returns a
number that corresponds to a particular icon.
Visio recognizes a shape as a data-graphics callout if the topmost shape in the master contains the userdefined cell User.msvCalloutType whose value is set to "Icon Set" (quotation marks required).
A second user-defined cell named User.msvCalloutIconCount tells Visio how many icons the callout
supports. This cell should have an integer value of 1, 2, 3, 4, or 5.
A third user-defined cell named User.msvCalloutIconNumber receives the formula from Visio that
determines which icon to display. This formula evaluates to -1 when none of the user's conditional
statements are true. Otherwise, the formula evaluates to an integer of 0, 1, 2, 3, or 4.
Figure 4. Icon set callout user defined cells
The code sample below will add the three user-defined cells and set their values.
Sub AddUserCellsForIconSet()
'Add the user-defined cells required for an icon set to the currently
182

182
'selected shape
If ActiveWindow.Selection.Count = 0 Then
MsgBox "Select a shape before using this macro"
Exit Sub
End If
Dim fExistsLocally As Boolean
fExistsLocally = False
With ActiveWindow.Selection(1)
'Check to see if the cell already exists. If so, don't add it again.
If Not (.CellExists("User.msvCalloutType", fExistsLocally)) _
Then .AddNamedRow visSectionUser, "msvCalloutType", visTagDefault
If Not (.CellExists("User.msvCalloutIconCount", fExistsLocally)) _
Then .AddNamedRow visSectionUser, "msvCalloutIconCount", _
visTagDefault
If Not (.CellExists("User.msvCalloutIconNumber", fExistsLocally)) _
Then .AddNamedRow visSectionUser, "msvCalloutIconNumber", _
visTagDefault
'Set the values into the cells
.Cells("user.msvCalloutType").Formula = """Icon Set"""
.Cells("user.msvCalloutIconCount").Result(visNumber) = 5
.Cells("user.msvCalloutIconNumber").Result(visNumber) = 0
End With
End Sub
Try it!
1. Open from the Samples folder the file Working with Data Graphics.vsd
2. Use the drawing tools to create a shape on the page.
3. Select the shape just created and run the macro AddUserCellsForIconSet
183

183
4. Check the ShapeSheet to verify that the user cells were added
5. Running this macro again on this same shape will still work because the macro checks to
see if the cells already exist before attempting to add them.
By convention, you should hide the callout shape when User.msvCalloutIconNumber is -1, although it
would be possible to use this state to display another graphic. To hide a shape completely, you must
hide all of its geometry, text, and images.
Using geometry
A common way to draw an icon is by using shape geometry. A shape can have multiple geometry
sections in it, and you can show or hide each section independently, depending on the value you set in
the User.msvCalloutIconNumber cell. Similarly, a shape can be a group containing additional subshapes,
and you can show or hide the geometry in those subshapes independently.
Figure 5 provides an example of an icon-set callout that has two geometry sections.
Figure 5. Icon set callout geometry example
The circle is shown for icon values 0, 2, and 4 (displaying the numbers 1, 3, and 5). The square is shown
for icon values 1 and 3 (displaying the numbers 2 and 4). Figure 6 shows a geometry section.
Figure 6. Icon set callout geometry section
The NoShow cell in each geometry section controls the visibility of the section. Table 2 lists the complete
formulas for the NoShow cells.
Table 2. Icon set callout NoShow formulas
Cell
Formula
184

184
Geometry1.NoSh
ow
IF(OR(User.msvCalloutIconNumber=0,User.msvCallout
IconNumber=2,
User.msvCalloutIconNumber=4),FALSE,TRUE)
Geometry2.NoSh
ow
IF(OR(User.msvCalloutIconNumber=1,User.msvCallout
IconNumber=3),FALSE,TRUE)
Note that when User.msvCalloutIconNumber is -1, both formulas evaluate to TRUE and no geometry is
shown.
Using image files

Another way to show an icon is by using a picture image, such as a bitmap or a metafile. In this case, the
callout shape must be a group shape that contains the image or images as subshapes. Put the userdefined cells for the icon set into the group shape. You can show or hide the images by specifying the
value in the group's User.msvCalloutIconNumber cell.
When working with images, it is easier if all the pictures are the same size. Also, the images should be
combined into an image stripa single picture that contains the images arranged in an evenly spaced
row. You can perform these manipulations either in Visio or in another graphics editor, such as Paint.
Figure 7 shows an example of an icon set based on images.
Figure 7. Icon set callout image example
To create this icon set, draw a rectangle to the final callout size you want. Convert the rectangle to a
group and add the required user-defined cells for the icon set. Then add the image strip to the page, and
lock its aspect ratio. Resize the image strip until it is exactly 5 times the width of the rectangle (or a
different multiple if there are fewer icons in the set).
185
185
Figure 8. Icon set callout image example: Step 1
Using the Crop tool, crop the image strip down to the width of the rectangle. Align the image strip on
top of the rectangle and add it to its group. You can delete or permanently hide the rectangle's
geometry section.
Figure 9. Icon set callout image example: Step 2
The final step is to tie the image strip to the group's icon number. In the ShapeSheet of the image strip,
the Foreign Image Info section controls the size and position of the picture. Only a portion of the picture
is visible in the shape, and the rest is cropped out of view. The ImgOffsetX cell controls what portion of
the image is seen. This cell moves the image based on the icon value of the group.
The formula in the ImgOffsetX cell refers to Sheet.5. This is the group shape that contains the images.
Figure 10. Icon set callout Foreign Image Info section
186
186
Note:
There are significant differences when working with image strips created as
bitmaps vs. those created as enhanced metafiles. For bitmaps, if the image does
not completely fill the frame, then the background must be of some color (lets
assume white). When these images are applied in an icon set, the icons will have a
white border around the image. If the user puts a color on the page other than
white, the icon doesnt look so good. Second, the image quality may degrade.
Image strips created as enhanced metafiles have a transparent region around the
shape and the image quality does not degrade. Using enhanced metafiles instead
of bitmaps for the image strip creates a much better looking icon set.
Try it!
1. Open the file Working with Data Graphics.vsd. An example of creating the icon set
described above is covered in this drawing on page The making of an icon set.
2. Edit a data graphic and add a new graphic item. The new Icon Set is displayed along with
the other icon sets.
3. Choose the icon set (its name is not displayed) in the New Icon Set dialog.
Working with data graphics using automation

Data graphics can be managed through the Visio user interface. But what about doing some these same
tasks or accessing the information about data graphics and graphic items through automation? In the
file Working with Data Graphics.vsd in the Samples folder there is VBA code for the following.
Return a data graphic assigned to a shape

Through automation you can get the data graphic assigned to a shape. The information is in the
DataGraphic property of the shape.
Try it!
1. Open Working with Data Graphics.vsd from the Samples folder.
2. Select a shape that has a data graphic assigned to it and run the macro
WhichDataGraphicAssigned from the Tools menu.
3. The data graphic assigned to the shape is displayed in a message box.
4. View the code.
Apply a data graphic to a shape

You can also set the data graphic for a shape through code.
Try it!
187

187
2. Go to the page named Data Graphics. Right-click one of the shapes and choose Set to
next DG. This runs the procedure SetDGToNextInList which finds the current data
graphic assigned to the shape and then searches all of the data graphics in the document
to find the next data graphic. It then assigns this data graphic to the shape.
3. View the code.
Interrogate Graphic Items

You can interrogate properties for graphic items.
Try it!
2. Go to the page named Data Graphics.
3. Select a shape that has a data graphic assigned to it. Run the macro ListDataGraphic. This
will write information about the data graphic and each of the graphic items that make up
the data graphic to VBAs Immediate window.
4. View the code.
Set information into a data graphic

5. Right click one of the shapes and choose SetDGToNextHorizontalPosition. This runs the
procedure SetDGToNextHorizontalPosition which increments the horizontal position of
the data graphic.
Note:
Editing a data graphic in the Data Graphic task pane is equivalent to editing the
master in the Drawing Explorer window. To do the equivalent operation in code
you must edit the master. This requires that 1) the master be Opened (which
creates a copy), 2) edits are made to the copy, and 3) close the copy. On close the
changes are copied back to the master and the update happens in the drawing.
6. View the code.

7. There is also a procedure SetDGToNextVerticalPosition.
Set information into a data graphic item

8. On the page named Data Graphics make sure there is a data graphic assigned to one of
the shapes.
188
188
9. Edit this data graphic and edit the item within it so that it does NOT use the default
position of the data graphic (uncheck the box Use default position) and then reposition
the Text callout or Data Bar callout.
10. Select the shape that has the data graphic just modified and run the macro
ResetGraphicItemsToDefaultPosition. This macro steps through each of the graphic
items for the data graphic assigned to the shape and sets the property
UseDataGraphicPosition to True. This is equivalent to editing the graphic item and
checking the checkbox Use default position.
11. View the code
Note:
Like editing a data graphic, editing a graphic item is equivalent to editing a master.
We therefore need to open the master, edit the copy, and close the master.
Other things to do with a data graphic

There are two check boxes in the Edit Data Graphic dialog
Show border around items at default position. Get or set the property
DataGraphicShowBorder.
Hide shape text when data graphic is applied. Get or set the property
DataGraphicHidesText.
Other things to do with a data graphic item
Set details as in the Edit Item dialog. The details fields come from the Shape Data rows in
the master. Setting the Shape Data cells through automation is equivalent to opening the
Edit Item dialog and changing details values.
Set data field as in the Edit Item dialog. Use the SetExpression method of the
GraphicItem.
Guidelines for constructing data graphic callout shapes

Use of common design practices helps ensure consistency and ease of use for callout shapes.
Callout Name
For text callouts and data bars, the name assigned to the callout master is the name displayed in the
Callout drop-down list in the Edit Item dialog. Icon sets are only displayed graphically.
189
189
Sample Values
Visio uses the callout master shape as a thumbnail in the Edit Item dialog. The master shape also
appears in the Data Graphics viewing area as part of the data graphic thumbnails. To help your users
understand how your callout displays information, choose an appropriate sample data value for the
shape.
Controlling callout size

Visio applies special formulas to your callout shape to control its size and position relative to the parent
shape in the drawing. In general, these formulas size the callout to match the width and height of the
parent shape. To specify a fixed size or a size controlled by logic within the callout, place GUARD
expressions in the Width cell or in the Height cell in the callout, or in both cells. In Figure 11, in the first
example, the Width cell value is matched to the width of the parent shape, but the Height cell value is
determined by the callout. Also in Figure 11, in the second example, both the width and height remain
fixed.
Figure 11. Callout sizing examples
Controlling margins
Callout shapes are often stacked together or aligned along the edges of the parent shape. This may
make the geometry or graphical images in the callouts appear crowded. It is often helpful to build a
margin into the callout shape's geometry or image strip. The icon set example, discussed previously,
includes a margin to inset the geometry of the callout, as shown in Figure 12.
Figure 12. Callout margin example Geometry sections
190
190
In this example, a user-defined cell named Margin was created to specify the spacing to be used. When
you use fixed dimensions in a shape, include a factor for the page scale so that the shape is usable in
scaled drawings. You can do this by multiplying the fixed dimension by the value of the
DropOnPageScale cell.
Figure 13. Callout margin example user-defined section
Protection cells
When you design callout shapes, you must decide what you want to allow your users to manipulate in
the callout after they apply it to a parent shape. The Protection section in the ShapeSheet enables you
to lock down specific behaviors or properties in the callout shape.
This is an example of changing the text size in callouts.
In the flowchart above, a data graphic is applied to the three process steps. The data graphic has two
text callouts displaying the Cost and Duration shape data fields. The default text size for the flowchart
shapes and the text callouts is 8 points. What happens if we do a Select All and change the text size to
12 points?
The flowchart shape text has increased in size, but the callout text has not. Normally when you apply
formatting to a group shape, Visio automatically pushes that formatting to all sub-shapes as well.
However, Data Graphics callouts are designed to prevent this automatic propagation. There are many
scenarios where it is desirable to maintain separate formatting for the shapes and the callouts. Visio
191
191
2007 introduced a new protection on shapes to prevent group formatting from propagating to subshapes.
Group formatting protection does not prevent all formatting changes on a shape - just those pushed
from groups. You can directly select (or sub-select) a shape and still format it. Data Graphics callouts
work this way. Not all Visio shapes allow selection of sub-shapes. This is controlled by the group
selection behavior property found in the Developer > Behavior dialog. If the Selection property is set to
Group Only, you will have to right click the shape and choose Group > Open Group to make any
formatting changes.
As was shown earlier, the master callout can be edited to effect global callout changes.
The following table shows Protection section cells useful for controlling callout behavior.
Cell
Explanation
LockAspect
Useful for icon sets if the Width cell and the Height cell are not
protected with the Guard function.
LockFormat
Prevents users from making formatting changes to the callout.
LockCustProp
Prevents users from deleting Shape Data properties from the callout.
192

192
LockGroup
Prevents users from deleting subshapes that make up the callout.
LockFromGroupFormat
Prevents formatting changes made by users to the target shape from

also being applied to the callout. Direct formatting of the callout
shape is still allowed.
LockThemeColors
Prevents color themes from changing the formatting of the callout.
LockThemeEffects
Prevents effect themes from change the formatting of the callout.
Performance, memory, and file size

Because data-graphics callouts are Visio shapes and can contain complex graphics, they can significantly
affect the size and responsiveness of a Visio drawing. If an average callout shape includes two subshapes
and an average data graphic includes three callouts, Visio adds nine shapes to the document every time
you apply a data graphic to a target shape. For some drawing types, such as flowcharts, the datagraphics shapes are far more complex than the shapes that constitute the drawing itself. The file size
and memory requirements for a drawing that contains data graphics might be an order of magnitude
larger than those of a drawing without data graphics. This affects the performance of the document.
The most important factor that influences performance, memory, and file size is the number of shapes
per callout. Ideally, each callout should be a single shape. If you must combine multiple callout shapes
into a group, ensure that the group itself is used for its geometry or text. Shapes support multiple
geometry sections, so an additional shape is often not necessary. You can individually show or hide each
geometry section based on the configuration of the callout. Additional shapes are necessary when a
callout needs multiple formats or pieces of text, but try to keep the total number of shapes to a
minimum. Also, avoid creating groups nested inside other groups.
Another performance factor is the time required for Visio to add new ShapeSheet cells to the callout
when you use it in a drawing. Visio generates several additional user-defined cells to implement some of
the data graphics behavior in the callout. Including these cells in the callout master shape saves time
and file size. Table 3 lists named rows that you must add to callout masters.
Table 3. Callout user-defined cells used by data graphics
Row
Value
User.visDGCalloutItem
blank
193

193
User.visDGDefaultPos
blank
User.visDGStackHeight
blank
If you design target shapes to work with data graphics, you can add some of the named rows listed in
Table 4 to target masters.
Table 4. Target shape user-defined cells used by data graphics
Row
Value
User.visDGDisplayFormat
blank
User.visDGDefaultPos
blank
User.visDGCBVFill
blank
User.visDGOldColors
blank
User.msvThemeColors
blank
User.msvThemeEffects
blank
By pre-creating the user-defined cells needed by data graphics, you can reduce the time needed to apply
data graphics to shapes.
One final performance issue to be aware of is the use of the ShapeSheet functions TEXTWIDTH and
TEXTHEIGHT. These functions calculate the geometric boundary of shape textwhich is useful
information for precisely arranging text and geometry together. However, they require Visio to fully
compose and lay out the shape text each time the function is evaluated. These functions are very
expensive relative to other ShapeSheet expressions, so use them sparingly.
194
194
Managing Data Graphic Masters

Where are they stored and how do you see them?
There are a number of built-in data graphics, callouts, and icon sets. These do not show anywhere in the
user interface except in the data graphics viewing area on the ribbon.
Once assigned to a shape, these data graphics, callouts, and icon sets are added to the masters
collection of the drawing and can be seen using the Drawing Explorer window. As masters, they have a
Hidden property that is set to True. This prevents them from be displayed in the Document Stencil
window, but not in the Drawing Explorer.
Making a data graphic part of a document

The built-in data graphics are always included in any Visio document. Other data graphics can be added
and saved with a document.
Add a data graphic to a document

To copy a data graphic from one document to another, apply the data graphic to a shape in the current
drawing. Then copy the shape and paste it into the other document. This action copies the data graphic
definition to the other document, and it copies the callouts used by the data graphic. You can then
delete the shape from the first document, but the data graphic remains available in the second
document.
Try it!
1. Open a drawing from the Visio Samples. File > New > Sample Diagrams > Process
Improvement.
2. Create a new drawing that has no data graphics in the template. File > New > General >
Basic Diagram.
3. Look at the Masters in the Drawing Explorer for each drawing. There shouldnt be any in
the second drawing.
4. In the first drawing select a process shape that has a data graphic applied to it. Paste it
into the second drawing.
5. Check the masters collection after pasting the process shape. Depending on the shape
chosen there may be several masters added. For example, the masters collection will look
something like this:
Bubble callout
Data bar 2
195
195
Process
Process 2
Status icons
Text callout
6. Check the Document Stencil. The Process shape should be there.
7. Within the new document delete the process shape. There should be no shapes left on
the drawing page. The Masters collection and the Document Stencil are unchanged
meaning that the data graphic is still part of this drawing. Check the Data Graphic task
pane to verify this.
8. Delete the Process shape from the Document Stencil. Check the Masters collection and
the Data Graphics task pane. The Data Graphics remain.
Make a data graphic part of a template

The process above can also be used to add any data graphic to a template. Open the template for
editing, add the data graphic, and save the template. When a drawing is created from the template the
data graphic will show in the Data Graphics task pane.
More Information:
It is not possible to define a data graphic in a central location for use in all
documents, so building the data graphic into the template is the best approach.
Make a master with a data graphic already applied.

One additional option is to pre-associate a data graphic with a master shape. This method is useful for
diagrams in which data graphics are an integral part of the drawing and in which each shape can use the
same data graphic to display information. To build a data graphic into a master shape, apply the data
graphic to a shape on the page and then drag the shape to a stencil to create a master. Note that, by
doing this, you remove the association that the shape had with its previous master. Visio makes a new
master from this union of shape and data graphic. Visio also places a copy of the data graphic and any
callout masters in the stencil.
Try it!
1. Open a drawing from the Visio Samples, File > New. Choose Samples Diagrams and then
open Process Improvement.
2. Create a new stencil.
3. Drag one of the process shapes that has a data graphic applied to it into the blank stencil
196
196
4. Create a new drawing that has no data graphics in the template. File > New > General >
Basic Diagram.
5. Tile the windows so that both windows can be seen.
6. Drag the master from the new stencil into the new basic diagram drawing.
7. Check the masters collection and the Data Graphic task pane. The data graphic is there!
8. Use the Drawing Explorer to review the shape. Note that it is a group shape and that each
of the data graphic items are also members of the group.
Hidden masters and removing hidden information

Normally, unused masters can be removed using the Remove Hidden Information tool of Visio.
However, some custom solutions include data graphic masters in the document and the solution
depends on these graphics being present.
To protect a hidden data graphic (or any master) from removal by the RHI tool, create a user-defined cell
User.msvRHIPreventRemoval to the masters PageSheet and set its value to 1. The Remove Hidden
Information tool will then ignore this master and NOT remove it.
197
197
Lesson 2: Related Topics

Data Graphics heavily utilizes Visios Shape Data features. The custom solution developer must
recognize that there while be Shape Data fields created by the end user and also Shape Data fields
created for use by Data Graphics.
Lesson Objectives
Distinguish between Shape Data used to define Data Graphic fields and Shape Data used
to store general information within a shape.
Understand the relationship of Shape Data and Data Graphics and use Shape Data to
define the property fields of text callouts and data bar callouts
Shape Data Management

With the advent of data graphics and data linking in Visio 2007 the Shape Data section of the
ShapeSheet takes on additional responsibilities. Previously, it was used mostly as place to store extra
data to be associated with a shape. This data could be viewed through the Shape Data window and
reports could be generated from it using the Reports tool. If the data was to be viewed visually, the
shape needed to be programmed to do something with the data. As an example, consider the timeline
shapes that hold information about the timeline in shape data. This data is used to control the graphical
output of the shape.
Beginning with Visio 2007, in addition to serving as the repository of data associated with shapes, Shape
Data is also used to define fields in data graphic callouts. These fields control the display of the prompts
in the Edit Item dialog.
The data linking features of Visio automatically add shape data fields for each field in a record being
linked to a shape if that shape data field does not already exist in the shape.
How to add shape data

The basic techniques of adding shape data have not changed, although the menus changed with Visio
2007 from Custom Properties to Shape Data.
198
198
Define Shape Data dialog

The Shape Data dialog still exists with the revised interface of Visio 2010. There are a couple of options
for viewing the dialog.
Right-click in the Shape Data window and choose Define Shape Data
Right-click a shape (or selection) and choose Data > Shape Data
The ShapeSheet
Shape Data fields can be created in the ShapeSheet window by adding rows to the Shape Data section
and filling in the values for each of the cells in the row.
Shape Data sets

Shape Data Sets allow the copying of a group of shape data fields in mass from one shape to another.
This feature is available as a right-click menu of the Shape Data window.
Effect of LockCustProp cell in Protection section

There is a Protection section cell named LockCustProp that affects the users ability to add shape data
through the user interface. This cell is available only through the ShapeSheet. It is not displayed in the
user interface in the Protection dialog.
This cell determines whether the user can add, delete, or modify shape data in the user interface using
the Define Shape Data dialog box or the shortcut menu for the Shape Data window.
When the cell has a value of True the Define button does not appear in the Shape Data dialog box, and
the Define Shape Data command on the shortcut menu in the Shape Data window is disabled.
A value of TRUE does not prevent a user from changing the value of a shape data item or changing the
Shape Data section in the ShapeSheet window.
Relationship of shape data and data graphics

Visio places the data to be displayed in a Shape Data row named Prop.msvCalloutField. Design the
callout to make use of the information in this row in whatever way is desired. Note that Visio uses Shape
Data rows in callouts in highly specialized ways and that these rows are not intended to be used as
standard Shape Data properties. For this reason, you should set the Invisible cell value in these Shape
Data rows to TRUE to hide these rows from the user.
Figure 14. Text and Data Bar callout Shape Data cells
199

199
Visio puts the following information into cells in the Prop.msvCalloutField row when the callout is used
in a data graphic.
Table 5. Prop.msvCalloutField cells written by Visio
Cell
Value
Label
Not set by Data Graphics.
Prompt
Type

If data field is a Shape Data property, Format of Shape Data property.
Format
If data field is not a Shape Data property, not set by Data Graphics.
Value
Reference to data field value.

If data field is a Shape Data property, Label of Shape Data property.
SortKey
Invisible
Not set by Data Graphics, TRUE recommended.
Ask

If data field is a Shape Data property, LangID of Shape Data property.
LangID
If data field is not a Shape Data property, LangID of target shape.
Calendar
If data field is a Shape Data property, Calendar of Shape Data

property.
You specify the data field to be shown in the callout when you include the callout in a data graphic. You
can define additional properties for text callouts or data bars to expose in the Edit Item dialog. These
properties enable you to configure the callout in special ways.
200
200
You define custom callout properties by creating additional Shape Data rows that have names beginning
with the prefix Prop.msvCalloutProp.
Figure 15. Custom callout property cells
Visio interprets these cells in the property rows in the following ways.
Table 6. Custom callout property cells read by Visio
Cell
Value
Label
Property label to be displayed in dialog boxes.
Prompt
Control type of property (defined below).
Type
Not used.
For List control types, semicolon-delimited list of choices.
Format
For Field control types, format of data field or empty if field is not a
Shape Data property.
For String control types, optional default value for the property.
Invisible
Not used by Data Graphics, TRUE recommended.
Ask
Not used.
Visio puts the following information back into these cells in the property rows.
Table 7. Custom callout property cells written by Visio
Cell
Value
Value
Property value.
201

201
SortKey
For Field control types where data field is a Shape Data property,
Label of Shape Data property.
LangID of Shape Data property.
LangID
For Field control types where data field is not a Shape Data property,
LangID of target shape.
For Format control types, LangID of data format picture.
Calendar
Calendar of data field.
For Format control types, Calendar of data format picture.
Visio supports a variety of input controls in the Edit Item dialog. The Prompt cell specifies the control to
be displayed. Other cells might be interpreted in different ways, depending on the control type.
Table 8. Custom callout property control types
Control
Type
Prompt cell value
Control used in dialog box
String
"String"
Text box
Number
"Number"
Text box requiring numeric input
List
"List"
Drop-down list box with choices supplied by

the Format cell
Boolean
"Bool"
Drop-down list box with yes and no choices
Date
"Date"
Text box with date picker
Field
"Field"
Data-field drop-down list box
Data
Format
"Format"
Text box with Data Format button

202

202
Figure 16. Custom callout property examples
Field controls offer the same choice of fields as the data-field drop-down list box, with the addition of a
[Not Used] choice. If you select [Not Used], Visio places the formula NA() in the property's Value cell.
203
203
Lab 3.6: Data Graphics

During this lab, you will create a data graphic item to represent a pie chart and then create two data
graphics to test the data bar item.
Estimated time to complete this lab: 60 minutes
Before You Begin

To complete this lab, you will need:
Participants should have completed the Try This! Sections of this module before
completing this lab.
Visio 2007 or higher installed and configured.
Lab files needed:

o
ScheduleBuilder.vss
What You Will Learn

After completing this lab, you will be able to:
Create a new data graphic item from an existing shape
Add the data graphic item to a new data graphic
Apply the data graphic to a shape
Change the display size of a data graphic item on a shape
Exercise 1: Create a Pie Chart data graphic item

Scenario
You need to include a pie chart in a data graphic, but the standard data bar items do not include a pie
chart. You will have to create a new pie chart data bar data graphic item.
Tasks
1. Create a new blank drawing.
204
204
2. A basic pie chart shape is needed. You dont need to create one from scratch because
well start with a variation of an existing Visio Pie Chart shape and turn it into a data bar
item. It has the basic pie chart features needed. Open the stencil from the Labs folder
(from the Shapes window More Shapes > Open Stencil and then traverse to the Labs
folder and open ScheduleBuilder.vss.
3. Drag the New Pie Chart shape to the page. Use the RMA commands to set Number of
Slices and Slice Sizes.
This is a modified version of the Pie Chart shape from the Charts and Graphs stencil. It is
limited to 5 sections. Enter a value for each slice. The value is normalized to be a
percentage of the total of the five slices.
Note: The shape is themed. Browse through some of the subshapes of the group and
look at the FillForegnd cells. They have Theme formulas that reference the different accent
colors of the Theme.
4. Open the ShapeSheet for the Pie Chart group shape. Look at the User-defined section and
the Shape Data section. Note that there are Shape Data cells to contain the values for
each slice. There are User-defined cells that calculate normalized values for the cells.
These User-defined cells are referenced from the groups subshapes.
5. Turn this shape into a data bar data graphic item by editing the master in the Document
Stencil. Add the User-defined cell User.msvCalloutType. Set its value to Data Bar.
Close the Master editing window and save the changes.
6. Check if it worked. In the Data Graphics task pane create a new Data Graphic. Add a new
graphic item of type Data Bar. The New Pie Chart shape should show as a new data bar
option to choose from.
7. Now you need to set up the fields that are to be displayed on the data graphic by turning
the existing shape data fields into data graphic fields. Edit the New Pie Chart master from
the Document Stencil window. Open the ShapeSheet for the New Pie Chart group shape.
a. In the Shape Data section delete the row Prop.Slices. This will be driven from the
data graphic, not by user choice.
b. Change the name of Prop.Pie1 to Prop.msvCalloutField and set the following
column values:
Label=No Formula
205
Value=0
205
Invisible=True
c. Change the name of Prop.Pie2 to Prop.msvCalloutPropField2 and set the
following column values:
Prompt=Field
Value=0
Invisible=True
d. Change the name of Prop.Pie3, Prop.Pie4, Prop.Pie5 to msvCalloutPropField3,
msvCalloutPropField4, and msvCalloutPropField5 respectively. Set the Prompt,
Value, and Invisible fields the same as msvCalloutPropField2.
e. Delete the Actions section from the ShapeSheet. This is no longer needed.
f.
In the User-defined section delete the row User.Pies. This is no longer needed.
g. Close the master window and save the changes.

8. Check if it worked. In the Data Graphics task pane create a new Data Graphic. Choose a
Data field. Any field will do for the moment so choose More Fields>Geometry>Width.
Set Displayed as: to be Data Bar. Select the New Pie Chart graphic item. The New Item
dialog should look like the following. You should see Pie2 through Pie5 in the Details
section and the values are displayed as [Not Used].
206
206
9. Make the new master graphic item hidden. You can create a macro for this or use the
Immediate Window in VBA. From the Immediate Window type:
activedocument.Masters("New Pie Chart").Hidden=true
The master can still be seen from the Drawing Explorer window, but not from the
Document Stencil.
Exercise 2: Test the New Pie Chart data graphic item

Scenario
To test the new graphic item you will link a shape to a row in an external data set and then create a data
graphic and apply it to the shape.
207
207
Tasks
1. Choose Data > Link Data to Shapes and choose the file ScheduleBuilder.xls from the Labs
folder. Specify the Sections worksheet in the Excel file. The Sections data will appear in
the External Data window. Accept all defaults to finish the wizard.
2. Draw a rectangle on the page and link it to the first row of data. Note that a default data
graphic is assigned to the shape.
3. Choose Data > Data Graphics > Create New Data Graphic . Add a New Item.
4. Set the Data Field to 9. This is the number of students in grade 9.
5. Set Displayed as to Data Bar and set the Style to New Pie Chart.
6. Set the following:
Pie2=10
Pie3=11
Pie4=12
Leave Pie5 unchanged.
7. Set the callout position of the data graphic item to Center and Middle.
8. Apply the data graphic to the shape. Does the data graphic appear the right size for the
shape? By default it scales to the size of the shape.
9. From the Drawing Explorer window edit the New Pie Chart master. Open the ShapeSheet
and set these formulas into the Width and Height cells.
Width=Guard(0.5 in*DropOnPageScale)
Height=Guard(Width)
10. Close the master editing window and save the changes.
11. The data graphic will not update on the shape automatically so apply the None data
graphic and then reapply the new data graphic. It should now appear in a fixed size of 0.5
inches.
12. Rename this data graphic to DG Pivot
208
208
Exercise 3: Add a data bar to the Data Graphic that totals the
9th, 10th, 11th, and 12th grade slots for a class section.
Scenario
Create a new data graphic based on DG Pivot and add a data bar item.
Tasks
1. Create a duplicate of DG Pivot. Choose Data > Data Graphics. Right click the data
graphic and choose Duplicate.
2. Rename the new data graphic DG Section.
3. Edit DG Section. Add a New Item.
4. Under Data Fields choose More Fields and then Custom Formula. In the Custom
formula text field enter ={9}+{10}+{11}+{12}
5. Set the Displayed as field to Data Bar and set the Style to Data Bar 3.
6. Set the callout position to Right Bottom.
7. Set the Maximum value to 35.
8. Set the Label to Total. Close the Data Graphic dialog.
a. Draw a rectangle
b. Link it to a row of data
c. Apply the data graphic
d. You should see something similar to the image below.
9. Save the drawing. You will use the data graphics just created in the next module.
209
209
Additional Resources Data Graphics

Building Data Visualization Solutions with Visio 2007
A PowerPoint presentation giving an overview of the features of Visio 2007 from the Visio
Developers conference in January, 2006. These are just the slides. No notes are included.
http://download.microsoft.com/documents/uk/msdn/download/devcon/Session_D3_Microsoft_Office
_Visio_2007_New_Data_Visualisati.ppt
Demo: Let data tell its story with data graphics

An online demo showing the new features of Visio 2007.
http://office.microsoft.com/en-us/visio/HA101829791033.aspx
Q&A: With Microsoft Office Visio 2007, Every Picture Tells a Richer Story
While a picture may be worth a thousand words, having the right pieces of data associated with that
picture can be invaluable to IT professionals and business managers in making better-informed
decisions.
http://www.microsoft.com/presspass/features/2006/sep06/09-19visio2007.mspx
Data Graphics: visualizing data on your diagram

A high level review of applying and modifying data graphics
http://blogs.msdn.com/eric_rockey/archive/2005/12/14/503483.aspx
Visio 2007: Customizing Data Graphic Items

Creating a custom data graphic item
http://blogs.msdn.com/wmorein/archive/2006/06/15/632742.aspx
210
210
Visio 2007: More on Customizing Data Graphic Items: Icon Sets

Shows constructing and icon set including what is required in the ShapeSheet.
http://blogs.msdn.com/wmorein/archive/2006/07/14/665997.aspx
Building Custom Data Graphics for Visio 2007

A very good article by Mark Nelson on creating and customizing data graphics. Several good examples
and specific how to do it!
http://msdn2.microsoft.com/en-us/library/aa468596.aspx
Customizing Data Graphics

Provides good insight on why trying to apply formats to data graphics through the user interface gives
unexpected results. The author also tells you how to solve the problem.
http://blogs.msdn.com/visio/archive/2007/01/02/customizing-data-graphics.aspx
Custom Formulas in Data Graphics

Nice example of creating a custom formula in a data graphic
http://blogs.msdn.com/visio/archive/2007/03/06/custom-formulas-in-data-graphics.aspx
About Displaying Data Graphically

211
211
Review: Automating Data Graphics

Questions
1. What new objects are added to the Visio object model to support data graphics?
2. What two places in the Visio drawing environment can you see a data graphic?
3. True or False. A good way to learn about automating data graphics is to use the macro
recorder.
4. What are the four types of data graphic items that can be displayed in a data graphic?
5. What distinguishes a data graphic master from other masters in the masters collection?
6. Data graphic masters that are callouts have what user-defined cell to describe what type
of callout they are.
7. Instead of referencing just a Shape Data row, a custom formula can be displayed in a data
graphic item. In the object model, which method is used to set the custom formula?
8. Additional fields can be added to a callout by adding rows to Shape Data. What naming
convention is required to enable the data in these rows to be displayed as Details in the
Edit Item dialog?
9. What three user-defined cells are required for the icon set callout?
10. What property of the shape is set to assign a data graphic?
11. True or False. You can edit the data graphic master directly using automation.
12. True or False. Data graphics are not very expensive in terms of size and performance in a
drawing.
13. What is a way to make a data graphic always be part of a drawing?
14. How can you add a data graphic from one drawing to another drawing?
15. Since Shape Data is used to create data graphics fields, how do we prevent these fields
from being displayed in the Shape Data window?
212
212
Answers
1. GraphicItem and GraphicItems
2. The Data Graphic task pane and the Drawing Explorer window
3. False. The macro recorder will not work with data graphics. If the macro recorder is
started, the Data Graphics task pane is immediately closed and cannot be opened until
the macro recorder is turned off.
4. Text callout, data bar callout, icon set callout, and color by value.
5. The data graphics master is hidden so that it does not show in the Document Stencil and
the master type is visTypeDataGraphic.
6. User.msvCalloutType which has values Text Callout, Heading, Data Bar, or Icon
Set.
7. SetExpression of the GraphicItem object.
8. The Shape Data row name must start with msvCalloutProp
9. User.msvCalloutType, User.msvCalloutIconCount, User.msvCalloutIconNumber.
10. The DataGraphic property.
11. False. You most Open the data graphic master, which creates a copy. This copy can then
be modified and when the master is closed the changes are pushed back to the master.
12. False. Data graphics can be very expensive because a data graphic can be made up of
several masters. When applied to many shapes in a drawing you can quickly double,
triple, or more the size of the drawing.
13. Add the data graphic to a template. Then it will exist in all drawings created from the
template.
14. Copy a shape that has the data graphic applied and then delete the shape. The data
graphic will remain as part of the drawing.
15. Shape Data rows have an Invisible cell which is set to True in the ShapeSheet.
213
213
Managing External Data Sets

A key feature of Visio is the ability to pull external data from a variety of data sources into the Visio
environment and link shapes from the drawing to this data. The linking process updates a shape to
import data into existing Shape Data fields, and adds new fields as needed.
Each of the actions that can be performed through the user interface can also be performed
programmatically. Using programming techniques to add datarecordsets, create and link shapes, add
data graphics, refresh data, and detect and respond to changes after refresh are the topics of this
module.
Module Objectives
Add data to Visio programmatically from different data sources
Describe the objects, properties, and methods that control data linking
Link shapes to records within the data
Manage the links programmatically
Refresh the data
Detect and react to changes in the data on refresh
214
214
Lesson 1: Data Link Concepts

The first part of managing linked data is getting connected to the data. There are three variations of the
Add method for creating a new datarecordset: Add, AddFromConnectionFile, and AddFromXML.
The key to using these methods is setting up the connection string and the command string. The
connection string identifies the datas location of the data and any security information needed for
accessing the data. The command string is used to specify what part of the data is desired.
At the end of this lesson we will review an example that is more extensive than the simple code snippets
in the Help files. This example adds datarecordsets, adds shapes, links the shapes to the data, adds and
modifies a data graphic, and lays out the drawing. The final solution is an organizational chart created
from data in an Excel file, but uses simple rectangle shapes and data graphics to display the
organizational information on the shapes.
Lesson Objectives
Identify the new objects added to Visio 2007 for managing data linking and where they fit
in the object model
Identify the properties, methods, and events of the new objects
Create datarecordsets programmatically from different data sources using different Add
methods
Manage the DataConnection object to modify the connection string
Overview of Objects / Methods / Properties

Big changes occurred to Visio 2007 in the area of data support. Visio now provides a general purpose
tool for bringing data into the Visio environment and linking that data to shapes within the drawing
(data linking and pivot diagrams). There are also new tools for displaying data associated with shapes
(data graphics). These tools utilize heavily and also enhance the preexisting Shape Data features
(formerly Custom Properties) of Visio that allow any data to be associated with Visio shapes.
215
215
Data Linking
The DataRecordSets object is part of the Document. This collection is empty until data is added to the
drawing either through the user interface or through one of the automation methods that creates a
DataRecordSet object. There may be multiple DataRecordSet objects within a document, each pointing
to a different data source.
The data in a DataRecordSet contains columns of data, each column representing a field. The
DataColumns is the collection of all of the columns. The DataColumn object allows custom mapping of
the column to a ShapeSheet cell.
The DataConnection object holds the information for making the connection to the data source.
When data recordset rows are added, changed, or deleted, and when data recordset columns are added
or deleted, in each case as a result of a data recordset being refreshed, properties of the
DataRecordsetChangedEvent object return arrays of the affected rows or columns.
The relationship of the data linking objects to other portions of the Visio object model is shown in the
graphic below.
216
216
Methods
DataRecordSets
AddFromConnectionFile
AddFromXML
GetLastDataError
DataRecordSet
GetAllRefreshConflicts
GetDataRowIDs
GetMatchingRowsForRef
reshConflict
GetPrimaryKey
GetRowData
Refresh
RefreshUsingXML
RemoveRefreshConflict
SetPrimaryKey
Description
Adds a DataRecordset object to the DataRecordsets collection,
associates it with a new or existing DataConnection object, and
fills it with data from an OLEDB or ODBC data source by using
the connection and query information stored in a specified
ODC connection file.
Adds a DataRecordset object to the DataRecordsets collection
and fills it with data from an XML file, without requiring a
DataConnection object.
Gets the ActiveX Data Objects (ADO) error code, ADO
description, and data recordset ID associated with an error
that results from adding a new data recordset or refreshing the
data in an existing recordset.
Description
Returns an array of all the shapes in the data recordset that
have refresh conflicts.
Returns an array of data recordset row IDs that match the
rows in the data recordset specified in the criteria string
passed to the method.
Returns an array of IDs of data rows that may have a broken
link to a specified shape after a refresh operation.
Returns the name of the primary key column of the data
recordset.
Returns an array of values for each column in the
specified data row. Returns an array of column names
when data row 0 is specified.
Refreshes the data in the data recordset.
Refreshes the data in a data recordset that has no data
connection.
Removes all conflict information from the drawing file.
Sets the column name of the primary key column used during
a refresh operation.
217
217
DataColumns
SetColumnProperties
Description
Sets the properties of the specified columns to the values
specified.
DataColumn
GetProperty
Description
Returns the value of the data column property passed in as
VisDataColumnProperties.
Sets the specified property (as VisDataColumnProperties) to
the specified value.
SetProperty
Page
DropLinked
DropManyLinkedU
GetShapesLinkedToData
GetShapesLinkedToDataRow
LinkShapesToDataRows
Selection
AutomaticLink
BreakLinkToData
GetIDs
LinkToData
Description
Creates a shape linked to data on the page.
Creates many shapes linked to data on the same page.
Returns an array of shapes on the page linked to a specific
data recordset.
Returns an array of shapes on the page linked to a particular
data row in a data recordset.
Links an array of shapes to an array of data rows from a
particular data recordset on a one-to-one basis, by matching
positions in the arrays. Optionally, applies a data graphic to
linked shapes.
Description
Automatically matches shapes to data rows by comparing
shape-attribute values with recordset-data-row values and
finding the best match. You can specify the column (field) in
each row of data and the shape attribute upon which to base
the comparison.
Breaks the link between one or more shapes and the data
row or rows to which the shape or shapes are linked.
Returns an array of the IDs of shapes in a selection so that
you can link them to data.
Links a single data-recordset row to a shape or to all shapes in
a selection. Optionally, applies a data graphic to linked
shapes.
218

218
Shape
BreakLinkToData
GetCustomPropertiesLinkedToData
GetCustomPropertiesLinkedColumn
GetLinkedDataRecordsetIDs
GetLinkedDataRow
IsCustomPropertyLinked
LinkToData
Description
Breaks the link between one or more shapes and the data
row or rows to which the shape or shapes are linked.
Returns an array of indices of shape data linked to a
particular data recordset.
Returns the name of the column in the specified data
recordset that is linked to the specified shape-data field.
Returns an array of the IDs of data recordsets linked to a
shape.
Returns the ID of the row to which a shape is linked in the
specified data recordset.
Determines whether a specified shape data item is linked to
a particular data recordset.
Links a single data-recordset row to a shape or to all shapes
in a selection. Optionally, applies a data graphic to linked
shapes.
Properties
DataRecordset
CommandString
DataAsXML
DataColumns
DataConnection
LinkReplaceBehavior
RefreshInterval
Description
Gets or sets the command string used to query the data source.
Permits exporting data in XML format from Visio. Gets the XML string
describing the data recordset following the ADO XML schema.
Contains all the rows in the data recordset with Visio row IDs prepended to them. Read-only.
Returns the DataColumns object associated with the DataRecordset
object.
Returns the DataConnection object associated with the
DataRecordset object. Returns Nothing for a connectionless
DataRecordset object. Read-only.
Gets or sets how existing links between shapes and data rows are
handled during application of the Selection.AutomaticLink method.
Gets or sets the refresh interval for the data recordset in minutes.
Default value is 0, which means that refreshing by interval never
occurs. Minimum value is one minute.
219
219
RefreshSettings
TimeRefreshed
DataConnection
ConnectionString
Timeout
DataColumn
DataRecordset
DisplayName
Gets or sets refresh settings for the data recordset, as a combination

of VisRefreshSettings values.
Returns the date and time of the last refresh operation. Read-only.
Description
Gets or sets the connection string used to access an existing
DataConnection object or to create a new DataConnection object.
Gets or sets how long (in seconds) to attempt to establish a data
connection before terminating the attempt and generating an error.
Default is 15 seconds.
Description
Returns the DataRecordset object associated with the parent object.
Gets or sets the display name for the data column in the External Data
window and the label for the associated text box in the Shape Data
dialog box for the linked shape or shapes.
DataRecordsetChangedEvent
DataColumnsAdded
DataColumnsChanged
DataColumnsDeleted
DataRecordset
DataRowsAdded
DataRowsDeleted
Application
Description
Returns an array of the IDs of columns added to the data
recordset as part of a refresh operation. Read-only.
Returns an array of the IDs of columns in the data recordset
whose type changed as part of a refresh operation. Readonly.
Returns an array of the IDs of columns deleted from the data
Returns the DataRecordset object associated with the parent
object.
Returns an array of the IDs of rows added to the data
Returns an array of the IDs of rows in the data recordset
whose type content was changed or deleted as part of a
refresh operation. Read-only.
Description
220

220
DataFeaturesEnabled
True if data features are enabled for the current instance of

Visio. Read-only.
Document
Description
DataRecordsets
Returns the collection of DataRecordset objects associated

with the Document object.
Window
Description
SelectedDataRecordset
Gets or sets the DataRecordset object that is selected on the

active tab of the External Data window.
Gets or sets the row ID of the selected row displayed on the
active tab of the External Data window.
SelectedDataRowID
Data Sources
The Data Selector wizard enables the Visio user to connect to external data sources and bring that data
into the Visio environment. Data sources you can connect to include Microsoft Office Excel worksheets,
Microsoft Office Access databases, Microsoft SQL Server databases, Microsoft SharePoint lists, and
other OLEDB or ODBC data sources, such as an Oracle database.
To connect your Visio drawing to a data source programmatically, use the new additions to the Visio API
for data connectivity which include the following objects and their associated properties, methods, and
events:
DataRecordsets collection object

DataRecordset object
DataConnection object
DataRecordsetChangedEvent object
DataColumns collection object
DataColumn object
221
221
Figure 17. Data objects as they appear in the user interface.
Each Visio Document object has a DataRecordsets collection, which is empty until you make a
connection to a data source. To connect a Visio document to a data source, you add a DataRecordset
object to the DataRecordsets collection of the document. A DataRecordset object has a DataColumns
collection of DataColumn objects, each of which is mapped to a corresponding column (field) in the data
source. When you add a DataRecordset object by connecting to an data source, Visio abstracts the
connection in a DataConnection object, and the DataRecordset object is said to be connected.
You can also add a DataRecordset object by using an XML file that conforms to the ActiveX Data Objects
(ADO) XML schema as the data source. The resulting DataRecordset object is said to be connection-less.
An example of using this technique to create a DataRecordset is presented later in this material.
The connection between a data source and a DataRecordset object goes only one wayfrom the data
source to the Visio drawing. If data in the source changes, you can refresh the data in the drawing to
reflect those changes. You cannot, however, make changes in the data in the drawing and then push
those changes back to the data source. Visio can only read the data source. It cannot update the data in
the source.
222
222
Information is stored in the DataConnection object

An easy way to discover what information is required in a connection string is to use the macro recorder
within Visio. Accessing different data sources only requires a modification to the connection string used
that describes the location of the data.
Try it!
1. Open from the Samples directory Working With DataRecordsets.vsd.
2. Use the Data Selector wizard (Data > Link Data to Shapes...) to import the data in
Orgdata.xls data from the Samples folder. When the import is finished, the data is
displayed in the External Data window.
3. Run the macro to display the DataConnection object (View > Macro >
InterestingMacros.GetDataConnectionObject). The connection string is displayed in the
Immediate window. The code and the connection string are listed below.
Public Sub GetDataConnectionObject()
'Displays the connection string from the DataConnection object
'for the most recently opened datarecordset
Dim vsoDataConnection As Visio.DataConnection
Dim vsoDataRecordset As Visio.DataRecordset
Dim iCount As Integer
iCount = ActiveDocument.DataRecordsets.Count
Set vsoDataRecordset = ActiveDocument.DataRecordsets(iCount)
Set vsoDataConnection = vsoDataRecordset.DataConnection
Debug.Print vsoDataConnection.ConnectionString
End Sub
Sample connection string for Excel data source:

Provider=Microsoft.ACE.OLEDB.12.0;User ID=Admin;Data Source=C:\Program
Files\Microsoft Office\OFFICE12\Samples\1033\ORGDATA.XLS;Mode=Read;Extended
Properties="HDR=YES;IMEX=1;MaxScanRows=0;Excel 12.0;";Jet OLEDB:System
database="";Jet OLEDB:Registry Path="";Jet OLEDB:Engine Type=35;Jet OLEDB:Database
Locking Mode=0;Jet OLEDB:Global Partial Bulk Ops=2;Jet OLEDB:Global Bulk
Transactions=1;Jet OLEDB:New Database Password="";Jet OLEDB:Create System
Database=False;Jet OLEDB:Encrypt Database=False;Jet OLEDB:Don't Copy Locale on
223

223
Compact=False;Jet OLEDB:Compact Without Replica Repair=False;Jet OLEDB:SFP=False;Jet

OLEDB:Support Complex Data=False
Sample connection string for SharePoint list:

PROVIDER=WSS;DATABASE=http://name.officeisp.net/ShapingFuturez;LIST={05F6AF30-326C4932-83C1-35BF2015F718};
Sample connection string for SQL Server:

Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist Security Info=True;Data
Source=localhost\sqlexpress;Initial Catalog=WhitePaperSamples
Add a DataRecordset
DataRecordsets.Add
The Add method adds a DataRecordset object to the DataRecordsets collection by connecting to and
retrieving data from an ODBC or OLEDB data source.
Try it!
1. From the file Working with DataRecordsets.vsd run the macro View > Macro >
InterestingMacros.AddDataRecordsetFromConnectionObject. The macro will create two
DataRecordsets from the sample data in ORGDATA.xls.
2. View the code for this macro. The first time the Add method is used, the connection
information is passed as a string. Upon completion of this first Add the DataRecordset
object is created and its DataConnection object is established.
Set vsoDataRecordset = ActiveDocument.DataRecordsets.Add( _
strConnection, strCommand, 0, "Org Data")
3. The second time the Add method is used the DataConnection object previously created is
passed as the parameter to the Add method. This creates another DataRecordset from
the same data in ORGDATA.xls.
Set vsoDataRecordsetTwo = ActiveDocument.DataRecordsets.Add( _
vsoDataRecordset.DataConnection.ID, _
strCommand, 0, "Org Data")
224
224
Tip:
Anytime a DataRecordset exists, there will be a DataConnection object containing

the connection information for the data used to create the DataRecordset (except
for connectionless DataRecordsets). This DataConnection can be used to create
more instances of the same data.
DataRecordsets.AddFromConnectionFile
Creating a DataRecordset from an Office Database Connection file (.odc) is done with the
AddFromConnectionFile method of the DataRecordsets object. If an .odc file exists pass the path of the
.odc file in the first parameter of the method similar to the code presented below.
Public Sub AddFromConnectionFile_Example()
'Create a DataRecordset from an .odc file using the
'AddFromConnectionFile method
Dim strFile As String
Dim strName As String
strFile = "C:\Documents and Settings\System Admin\My Documents\" & _
"My Data Sources\Northwind Employees.odc"
strName = "Data from ODC"
Set vsoDataRecordset = _
ThisDocument.DataRecordsets.AddFromConnectionFile( _
strFile, 0, strName)
End Sub
Note:
An .odc file can be created in different ways including using tools in SharePoint and
tools in Access and Excel. The .odc file used for this example was created with the
Data Connection Wizard in Excel.
225
225
Try it! (optional)

1. Use Excel to create an .odc file. This can point to any Excel file or easily accessible
database such as Northwind.mdb. Note the path where the .odc file is saved.
2. Modify the macro AddFromConnectionFile_Example in the file Working with
DataRecordsets.vsd to create a DataRecordset based on the new .odc file just created.
DataRecordsets.AddFromXML
Adds a DataRecordset object to the DataRecordsets collection, and fills the resulting data recordset
with data supplied in the form of an XML string.
In contrast with data recordsets created by using the Add or AddFromConnectionFile methods, data
recordsets created by using the AddFromXML method are not associated with a DataConnection object.
Note:
Because DataRecordsets created using AddFromXML have no DataConnection

object, they are referred to as a connection-less data source.
What's more, Visio never refreshes a data recordset you created by using the AddFromXML method
automatically, regardless of the setting of the DataRecordset.RefreshInterval property. To refresh the
data in such a data recordset, you must call the DataRecordset.RefreshUsingXML method.
Try it!
1. From the file Working with DataRecordsets run the macro View > Macro >
InterestingMacros.AddFromXML_Example. The macro will create a DataRecordset from
the XML data defined within the macro.
2. View the code. Following is the XML data used to create the DataRecordset. Compare this
to the VBA code to see how the XML data is put into a string.
<xml xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882'
xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882'
xmlns:rs='urn:schemas-microsoft-com:rowset'
xmlns:z='#RowsetSchema'>
<s:Schema id='RowsetSchema'>
<s:ElementType name='row' content='eltOnly' rs:updatable='true'>
<s:AttributeType name='c1' rs:name='Cities'
226

226
rs:number='2' rs:nullable='true' rs:maydefer='true' rs:write='true'>

<s:datatype dt:type='string' dt:maxLength='255' rs:precision='0'/>
</s:AttributeType>
<s:extends type='rs:rowbase'/>
</s:ElementType>
</s:Schema>
<rs:data>
<z:row c1='Seattle' />
<z:row c1='Redmond' />
</rs:data>
</xml>
3. Run the macro GetDataConnectionObject. This will trip the error handler when checking
for the DataConnection object and display a message in VBAs Immediate window.
Accessing data in the DataRecordset

When you import data, Visio assigns integer row IDs, starting with the number 1, to each data row in the
resulting datarecordset, based on the order of the rows in the original data source. Visio uses data row
IDs to track the rows when they are linked to shapes and when data is refreshed. If you want to access
data rows programmatically, you must use these data row IDs.
Two important methods for retrieving information from DataRecordsets include GetDataRowIDs and
GetRowData. Use GetRowData to retrieve all columns of data within a given row. Use GetDataRowIDs
to retrieve a subset of IDs within the DataRecordset that satisfy a given criteria string.
A sample of how to use these methods is included in the following demonstration code.
Try it!
1. Make sure a datarecordset exists and then run the macro GetDataRecords. This macro is
a simple example of using GetRowData and GetDataRowIDs and writing the information
to the VBAs Immediate Window.
2. Run the macro View > Macro > BuildOrgMacros.DoItAll. This macro builds an
organizational chart. It creates a DataRecordset, drops shapes on the page and links them
to the data records, drops connectors on the page and glues them between the employee
and its Reports_To shape, modifies the data graphic that displays the organizational data,
and then lays out and resizes the page.
227
227
3. Look at the code in the macro AddDataRecordSet. This macro is used by the DoItAll
macro. Note that it uses the DataRecordSets.Add method to create the datarecordset. It
also sets the primary key field of the datarecordset.
4. Look at the code in the macro DropManyLinkedShape. This macro is used by the DoItAll
macro and sets up the DropManyLinkedU method to add a shape linked to each record in
the datarecordset. Note that the data graphic is added at the same time the shapes are
created.
5. Look at the code in the macro AddAndGlueConnectors. This macro utilizes GetRowData
and GetDataRowIDs to extract the needed information.
The key segment of code follows. Each record contains the data for one employee and in
that record is the Reports_To field which gives us the name of the person they report to.
GetRowData is used to extract the fields from a row in the form of an array of variant data.
The data in the Reports_To field is used to construct a criteria string which is then passed to
the method GetDataRowIDs to retrieve the ID of the record within the datarecordset of
that employee.
An example criteria string is Name = Joseph Goldberg
Given the ID of this record we use GetShapesLinkedToDataRow to find the shape on the
page that is linked to the row in the datarecordset.
This is enough information to give us the from shape and to shape so that we can add
and glue the connectors.
'Get the shape id of the "Reports_To" shape
varRowData = vsoDataRecordset.GetRowData(ShapeRowID)
strReportsTo = varRowData(2)
'Find the datarecordset row that has this "Reports_To" data
'in the "Name" field
strCriteria = "Name = '" & strReportsTo & "'"
lngNameRowIDs = vsoDataRecordset.GetDataRowIDs(strCriteria)
'Find the shape linked to this data row
ActivePage.GetShapesLinkedToDataRow vsoDataRecordset.ID, _
lngNameRowIDs(0), lngShapeIDs
6. The macro ModifyDataGraphicMaster modifies the default data graphic applied to the
shapes to add another text callout that displays the employees Title information.
228
228
7. The final step is in LayoutAndResize. This macro applies the Layout method to arrange
the drawing and resizes the drawing page so that the entire organization chart fits on the
page.
We will explore the other macros in this file later in this module.
229
229
Lesson 2: Managing Data sets

After creating a datarecordset, the next step is to link shapes to its rows. A shape can be linked to only
one row within a single datarecordset, but it can be linked to multiple datarecordsets one row in each.
Multiple shapes can be linked to the same row. The steps of creating the shapes, linking the shapes, and
adding a data graphic can be done in a single step.
Datarecordsets can be refreshed. They can be refreshed on demand or they can be refreshed
automatically at prescribed intervals.
When a datarecordset is refreshed, it may change. These changes can lead to conflicts with the linking
that was previously established. Visio provides tools for detecting these conflicts and detecting changes
to the datarecordset so that your program can react appropriately to the changes.
At the end of this lesson we will review a macro that refreshes the datarecordset for the organization
chart created in the previous lesson. After the data is refreshed the code checks for conflicts in the data
and for additions and deletions to the data.
Lesson Objectives
Link existing shapes to rows in a datarecordset
Add shapes to a drawing and link them at the same time
Link many shapes to a row in a datarecordset
Link shapes to rows in multiple datarecordsets
Automatically link shapes
Add data graphics to linked shapes
Discover existing links
Break links
Manage refresh
Discover and manage conflicts after refresh

230

230
Linking data to shapes

After you connect your Visio drawing to an external data source, you can link the shapes in the drawing
to data from that source programmatically. You can link one or more shapes to a single row of data in a
data recordset or to multiple rows of data in different data recordsets. However, you cannot link shapes
to multiple rows of data in the same recordset.
You can link existing shapes to data, one shape at a time or many at a time; or, you can create shapes
and link them to data simultaneously.
Creating shapes linked to data

When you want to create shapes that are already linked to data, on a drawing page that either does not
contain any shapes or contains shapes other than the ones you want to link, you can use the
Page.DropLinked method and the Page.DropManyLinkedU method to create one or more additional
shapes already linked to data. These methods resemble the existing Page.Drop and Page.DropManyU
methods in that they create additional shapes at a specified location on the page; but they also create
links between the new shapes and specified data rows in a specified data recordset.
An example of using DropLinked follows.
Set vsoShape = ActivePage.DropLinked(vsoMaster, dblX, dblY, _
lngDataRecordsetID, lngRowID, True)
vsoMaster is a reference to the master that is being dropped on the page

dblx, dbly define the drop location and correspond to the created shapes pin location
lngDataRecordsetID is the ID of the datarecordset being linked to
lngRowID is the ID of the row within the datarecordset being linked to
the last parameter (True) is a Boolean that specifies whether a data graphic is to be
applied to the shape automatically
vsoShape is a returned reference to the created shape
Try it!
1. In the file Working with DataRecordsets.vsd, run the macros AddFromXML_Example
(although any open datarecordset will do) and then DropLinkedShape.
2. View the code in DropLinkedShape.
231
231
An example of DropLinkedManyU was covered in an earlier example. The complete code can be viewed
in the macro DropManyLinkedShape. The core piece of code follows:
'Create one shape record for each record in the datarecordset
lngReturned = ActivePage.DropManyLinkedU(avsoMaster, _
dblXY, vsoDataRecordset.ID, _
lngRowIDs, True, alngShapeIDs)
avsoMaster is an array of shapes to be dropped, one per record in the datarecordset

dblxy is an array of x, y coordinates that determine the drop locations for the new shapes
vsoDataRecorset.ID is the ID of the datarecordset being linked to
lngRowIDs is an array of row IDs within the datarecordset that determine the row that
each shape is linked to
the next to last parameter (True) is a Boolean that specifies whether a data graphic is to
be applied to the shapes automatically
alngShapeIDs is an array of IDs for the created shapes
lngReturned is a returned value specifying the number of created shapes
Linking existing shapes to data

Link a single shape to a single row
To link a single shape to a single row LinkToData method of the shape as shown below.
vsoShape.LinkToData vsoDataRecordset.ID, lngRowID, boolAddDataGraphic
The following information is needed:
vsoShape is a reference to the shape to be linked

vsoDataRecordset.ID is the ID of the datarecordset being linked to
lngRowID is the ID of the row within the datarecordset
boolAddDataGraphic is a Boolean specifying whether a data graphic is to be applied
automatically to the shape
Link a shape to multiple datarecordsets

A single shape can be linked a single row within a single datarecordset, but it can still be linked to a
different row within a different datarecordset.
232
232
To link a shape to rows in multiple datarecordsets apply the LinkToData method multiple times, once for
each datarecordset.
Link multiple shapes to a row in a datarecordset

This is the same as linking an individual shape except the LinkToData method of the Selection object is
used.
If Visio cannot establish a link between a shape and the data row, Visio skips that shape and goes on to
the next shape in the selection. After you run the method, to determine if all shapes in the selection are
actually linked to the data row, call the Shape.GetLinkedDataRow method on each shape in the
selection. If that method fails for any shape, it indicates that the shape is not linked to the data row.
Visio will usually succeed in linking a row to a shape unless the shape is already linked to data and the
link-replacement-behavior setting for the datarecordset specifies that the link should not be replaced.
Link multiple shapes to multiple rows

The Page.LinkShapesToDataRows method is similar to the Selection.LinkToData method because it
links multiple shapes. The LinkShapesToDataRows method links shapes to multiple data rows. The
LinkToData method of the Selection object links multiple shapes to a single row.
ActivePage.LinkShapesToDataRows vsoDataRecordset.ID, alngDataRowIDs,
alngShapeIDs, boolAddDataGraphic
To link shapes, pass the LinkShapesToDataRows method a pair of arrays: one for shapes, and one for
data rows. Note that the matching array positions must correspond. As a result, for example, the shape
at position 1 in the shape array is linked to the data at position 1 in the data row array. Again, when you
call the method, you can optionally specify whether to apply an existing data graphic to linked shapes.
Automatically link shapes and data rows

If you are unsure about the correspondence between shapes and data rows, but you know a match
exists between a specific attribute of every shape and the data in one column in the data recordset, the
Selection.AutomaticLink method provides a way to link a selection of existing shapes to multiple rows
of data. Note that it must be the same attribute for all shapes.
The help file for the AutomaticLink method gives a coding example for setting up an automatic link
where a single column to be matched is specified. Lets set up an example for matching multiple
columns and lets use the record macro feature of Visio to create the code.
233
233
Try it!
1. Open Working with DataRecordsets.vsd and run the macro
BuildOrgMacros.AddDataRecordset to create a datarecordset from ORGDATA.xls.
2. Drop three rectangles on the page and link them to the first three records in the
datarecordset. This will add shape data fields to the rectangles.
3. Unlink the three shapes.
4. Turn on the macro recorder.
5. Select the three shapes.
6. Right-click in the External Data window and choose Automatically Link. The Automatically
Link wizard is presented.
7. On the first page choose Selected Shapes and then Next.
8. Choose Data Column = Name and Shape Field = Name. Then click the and button.
9. Choose Data Column = Title and Shape Field = Title.
10. Click Next and Finish. This will link the three selected shapes.
11. Stop the macro recorder and look at the code.
The last portion of the code should look similar to the following.
ColumnNames1(0) = "Name"
FieldTypes1(0) = visAutoLinkCustPropsLabel
FieldNames1(0) = "Name"
ColumnNames1(1) = "Title"
FieldTypes1(1) = visAutoLinkCustPropsLabel
FieldNames1(1) = "Title"
Application.ActiveWindow.Selection.AutomaticLink 41, ColumnNames1, _
FieldTypes1, FieldNames1, visAutoLinkReplaceExistingLinks, _
IDsofLinkedShapes1
We are passing to the method arrays for column names, field types, and field names. In this case we are
specifying that multiple columns and fields must match before the shapes can be linked.
The penultimate parameter specifies the auto link behavior. Use values from the VisAutoLinksBehavior
enumeration. These enumerated values provide options to customize the method, for example to
replace existing links with new ones.
The last parameter returns an array of shape IDs of the linked shapes.
234
234
Discovering links
Discovering information about links is very straight forward. The sample code in the Visio help files gives
examples using these methods. Some key methods include:
Page.GetShapesLinkedToData given a datarecordset, returns an array of shape IDs on a

page linked to the datarecordset
Page.GetShapesLinkedToDataRow given a datarecordset and a row ID, returns an array
of shape IDs on a page that are liked to that row
Shape.GetLinkedDataRow given a datarecordset, returns the ID of the row the shape is
linked to
Shape.GetLinkedDataRecordsetIDs returns a list of IDs of all datarecordsets that are
linked to by this shape
Shape.GetCustomPropertyLinkedColumn given a datarecordset ID and a shapes Shape
Data row ID, returns the name of the data column linked to this shape data row
Shape.GetCustomPropertiesLinkedToData given a datarecordset ID, returns an array of
Shape Data row IDs that are linked to the data columns in the datarecordset
Shape.IsCustomPropertyLinked - given a datarecordset ID and a shapes Shape Data row
ID, returns whether that Shape Data item is linked
Breaking links
Breaking links through automation is handled with the Shape.BreakLinkToData and the
Selection.BreakLinkToData methods.
In addition, actions in the user interface can cause links to be broken, such as deleting a datarecordset
or deleting the Shape Data item in a shape that is linked.
Regardless of how the link was broken, the Shape.ShapeDataLinkDeleted event is fired.
A note on the use of IDs in Visio

Visio keeps unique IDs for shapes, datarecordsets, and rows within the datarecordsets.
Shape IDs
Shape IDs are unique to the page. Shape IDs are reused when one shape is deleted and then another
shape is added.
Shape UniqueIDs
Unique IDs are GUIDs. They are unique within the scope of the application.
235

235
To convert between shape IDs and unique IDs, you can use two methods of the Page object,
ShapeIDsToUniqueIDs and UniqueIDsToShapeIDs.
By default, a shape does not have a unique ID. A shape acquires a unique ID only if you set its UniqueID
property. If a Shape object has a unique ID, no other shape in any other document will have the same
ID.
DataRecordset IDs
DataRecordsets have unique IDs accessible via the DataRecordset.ID property. These ID values are not
reused if a DataRecordset is closed. Generally, the DataRecordset.ID value will NOT be the same as the
position of the DataRecordset within the DataRecordsets collection. There is no index value for a
DataRecordset.
Row IDs within a DataRecordset

Rows of data within a DataRecordset generally have unique IDs starting with a value of 1, but they may
not run consecutively depending on recent refresh operations.
Because shapes are linked by their shape IDs to specific data rows, when Visio refreshes linked data, it
must determine which rows in the linked data recordset or recordsets were added, changed, or
removed since the last time the data was refreshed.
To identify these rows, Visio uses the row IDs assigned to the rows in the data recordset. Visio can assign
these row IDs two ways, depending on whether you designated primary keys for the data recordset
when you created it.
Refreshing Data Recordsets That Do Not Have Primary Keys

When you create a data recordset, Visio assigns row IDs to all the rows in the recordset based on the
existing order of the rows in the data source. Accordingly, the first row in the recordset is always
assigned row ID 1, the second is assigned row ID 2, and so on.
Subsequently, data rows can be added or removed from the original data source. Then, when data is
refreshed, the data recordset reflects those changes. As a result, row order in the data recordset may
change.
For example, in a five-row data recordset, if the fourth row in the data source is removed, when Visio
refreshes the data recordset connected to that data source, the fifth row in the data recordset becomes
the new fourth row and is assigned row ID 4. Row ID 5 is removed from the data recordset. As a result,
shapes linked to row ID 5 lose their links, and shapes linked to row ID 4 now get data from the row
previously in the fifth position.
236
236
As you can see, not assigning primary keys to data recordsets when you create them can result in
broken links between shapes and data, or in Visio linking shapes to rows other than the ones to which
you want them linked.
Refreshing Data Recordsets That Have Primary Keys

You can help prevent these broken or mismatched links by assigning primary keys to data recordsets. A
primary key identifies the name of the data column or columns that contain unique identifiers for each
row. The value in the primary key column for each row uniquely identifies that row in the data
recordset. Primary keys are often ID values, but you can set any column or combination of columns to
be the primary key. However, to get consistent results when you refresh data, it is essential that you
make the primary key column value (or set of values for multiple primary key columns) unique for each
row.
As a result, when you refresh or when Visio refreshes a data recordset that includes primary keys, its
rows retain the same row IDs they had before the refresh operation. Because Visio links shapes to data
rows by IDshape ID to row IDand because row IDs remain the same after a refresh operation, datalinked shapes remain linked to the correct row. Note that row IDs are never recycled for a given a data
recordset.
Managing Refresh
DataRecordsets can be refreshed programmatically using the DataRecordset.Refresh method. Calling
this method executes the query string associated with the datarecordset and then updates the linked
shapes with the data returned by the query.
When a datarecordset is created it does not refresh automatically. To enable automatic refresh set its
refresh interval to some value greater than zero.
'Set the refresh interval to 2 minutes
vsoDataRecorset.RefreshInterval = 2
To turn off automatic refresh set the refresh interval to zero.

'Turn off automatic refresh
vsoDataRecorset.RefreshInterval = 0
237
237
If calling Refresh results in conflicts, Visio displays the Refresh Conflicts task pane in the UI, unless you
set the RefreshSettings property to include the visRefreshNoReconciliationUI (=2) enumerated value.
By default RefreshSettings=0.
As a developer, you should reconcile refresh conflicts programmatically by using the
GetAllRefreshConflicts, GetMatchingRowsForRefreshConflict, and RemoveRefreshConflict methods.
'Dont display refresh conflicts in the Refresh Conflicts task pane
vsoDataRecorset.RefreshSettings = visRefreshNoReconciliationUI
Identify changes and resolve conflicts

When a datarecordset is refreshed conflicts are displayed in the Refresh Conflicts task pane.
If a data row has been deleted and a shape was linked to it, that shape is displayed and the user is
prompted for what to do with it.
If a new data row is added that is a duplicate of a previous row that was linked, the link is removed and
the user is presented with the duplicate data and prompted for how to deal with it.
If a new data row is added that is not a duplicate, there is no conflict. From the user interface the new
record is apparent by looking at the External Data window and noting the unlinked records.
The automation model provides tools to handle each of these scenarios.
GetAllRefreshConflicts
This method returns an array of shapes that are linked to data rows in a datarecordset that have nonresolved conflicts after a datarecordset is refreshed.
Conflicts can result when a single shape is linked to more than one row in the same data source, or
when a shape is linked to a row in the data source that has been deleted. If the shape would be linked
to multiple rows, the link is removed and the conflict is presented in the Refresh Conflicts task pane.
Use GetMatchingRowsForRefreshConflict to retrieve all of the rows in the datarecordset that match
with this shape.
If no conflicts exist, an empty array is returned.
238
238
GetMatchingRowsForRefreshConflict
When a shape is potentially linked to multiple rows in a datarecordset after a refresh, the list of
matching rows can be retrieved with this method. It returns an array of row IDs from the datarecordset
that each match the shape in conflict.
Conflicts can also occur when a previously data-linked row from the data recordset is removed. When
this occurs, the method returns an empty array.
RemoveRefreshConflict
Once a conflict has been dealt with it can be removed from the list by using the RemoveRefreshConflict
method of the shape.
DataRecordsetChanged event and DataRecordsetChanged object

Retrieving conflict information is great for when changes to the datarecordset results in conflicts, but
this does not help when new rows are added to the datarecordset. For example, when a new row is
added the user may want to add a new shape that is linked to the new rows.
Fortunately, there is a way to retrieve this information programmatically. Use the
DataRecordsetChanged event to detect that the datarecordset has changed. Within the
DataRecordsetChanged event you have access to the DataRecordsetChanged object which contains a
wealth of information about what has changed in the datarecordset including data columns that have
been added, changed, or deleted, and data rows that have been added or deleted.
Try it!
The sample code in Working with DataRecordsets.vsd has a macro that will Refresh a datarecordset and
then check for and process changes using the methods and events just described. If you already have
the file open, it is best to close it and then reopen it. Some of the code is not bullet proof, but it does
illustrate how to use the methods.
1. Open Working with DataRecordsets.vsd from the Samples folder.
2. Run the macro BuildOrgMacros.DoItAll. This builds the organization chart we saw earlier
using the OrgData.xls file.
3. Run the macro BuildOrgMacros.RefreshDataAndResolveConflicts. This macro refreshes
the Org Data datarecordset by modifying the connection string to point to a modified
version of the Excel file OrgDataModified.xls and then using the Refresh method.
4. The following changes are made to the organizational data:
239
239
a. The record for Toby Nixon is changed to Toby Dixon. In the code this is handled
as one deleted record and one added record. The original Toby Nixon shape is
deleted and a new shape is added.
b. The record for Meng Phua is changed to report to Toby Dixon. There is no conflict
created by this change. The datarecordset and the shape data are updated on
the refresh, but because the Toby Dixon record is new, the connector has to be
changed to point to the correct Reports_To shape
c. A new record is added for Fred Taylor who reports to Toby Dixon and a duplicate
record for Fred Taylor is also created. If both records are added at the same time
there is no conflict because there is no shape linked to these rows. A new shape
is added for Fred Taylor. When the second new Fred Taylor shape is processed it
is ignored because it is a duplicate.
5. Look at the code for RefreshDataAndResolveConflicts. Only the refresh code is here.
6. The resolution of the conflicts is handled in the event procedure
vsoDataRecordsets_DataRecordsetChanged which is in the ThisDocument module.
Note:
It is best to put the resolve conflicts code inside the event procedure. The event
code does not fire immediately after the Refresh method so if you have some code
in the event procedure and some code following the Refresh method, you wont be
able to determine which code is executed first.
7. Look at the event procedure code. Conflicts are handled first using GetAllRefreshConflicts
and then processing the conflict list. If a row has been deleted, the corresponding shape
is deleted. If duplicate rows are created which have a corresponding shape, the shape is
linked to one of the rows and the other row is ignored.
8. New rows added to the datarecordset are handled next. If a new row is added which
does not represent a duplicate, a new shape is added to the drawing and linked its
Reports_To shape.
9. All resulting changes in the drawing are in the lower right hand area of the drawing page.
Warning for VBA users implementing code samples from Help files
Below is the code sample provided in the Help file for GetMatchingRowsForRefreshConflic. Note that
after the call to GetAllRefreshConflicts and to GetMatchingRowsForRefreshConflic there is an If test that
uses the function IsEmpty to test for an empty array being returned by the methods.
Unfortunately, this test does not work in VBA. The IsEmpty function is designed to work with variables
of type Variant and does not reliably return information for other data types. It returns False even when
240
the array has no data.
240
There are several similar methods that return arrays and similar code samples that use IsEmpty to test
these arrays. All of these samples will be problematic in VBA.
Public Sub GetMatchingRowsForRefreshConflict_Example()
Dim intRecordsetCount As Integer
Dim intShapeCount As Integer
Dim vsoShapes() As Visio.Shape
Dim intRowCount As Integer
Dim vsoShapeInConflict As Visio.Shape
Dim alngRowIDs() As Long
Dim lngvsoRowID As Long
intRecordsetCount = Visio.ActiveDocument.DataRecordsets.Count
Set vsoDataRecordset = Visio.ActiveDocument.DataRecordsets(intRecordsetCount)
vsoDataRecordset.Refresh
vsoShapes = vsoDataRecordset.GetAllRefreshConflicts
If IsEmpty(vsoShapes) Then
Debug.Print "No conflict"
Else
For intShapeCount = LBound(vsoShapes) To UBound(vsoShapes)
Set vsoShapeInConflict = vsoShapes(intShapeCount)
alngRowIDs =
vsoDataRecordset.GetMatchingRowsForRefreshConflict(vsoShapeInConflict)
If IsEmpty(alngRowIDs) Then
Debug.Print "For shape:", vsoShapeInConflict.Name, "Row deleted."
Else
For intRowCount = LBound(alngRowIDs) To UBound(alngRowIDs)
241

241
lngvsoRowID = alngRowIDs(intRowCount)
Debug.Print "For shape:", vsoShapeInConflict.Name, "Row ID of row
in conflict:", lngvsoRowID
Next intRowCount
End If
Next intShapeCount
End If
End Sub
Alternatives to using IsEmpty

Sometimes, but not always, the UBound function will work and return a value of -1 if the array is empty.
However, in some cases the UBound function will throw a subscript out of range error.
If using UBound does not work the only reliable alternative is to create an error handler to trap and
process the error.
Changing data locations

Sometimes data locations change or network connections are lost. Is there a way to build some
resiliency into your code so that if your access to the data changes your program does not fall over?
Lets examine some common scenarios:
1. If the data changes location you may have to change the connection string in your code to
point to the new location. Weve already seen that the connection string can be changed
and the datarecordset refreshed so straightforward to build this kind of change into your
code.
2. You can isolate your program from the data by using a data connection file and using the
AddFromConnectionFile method. Connect to the data via a connection file with the
assumption that the connection file stays in a fixed location and if the data moves, the
connection file is updated with the new location.
3. The third variation is when the data becomes unavailable unexpectedly such as when a
network connection is lost or if the data is moved, but you dont know where it is. In this
scenario we cant reconnect to the data, but we can detect that the data could not be
found and then fail as gracefully as possible.
242
242
To detect a failed connection use the Timeout property of the DataConnection object. This property is
used to set a timeout interval (default is 15 seconds). If the interval elapses without success an error is
raised. An error handler must be written to trap the error. An example follows showing a portion of the
subroutine which refreshes a datarecordset and displays the error message when an error occurs:
'Set the connection string into the DataConnection object to point to
'the desired data
vsoDataRecordset.DataConnection.ConnectionString = strConnection
'Set up error handler to catch the timeout error
On Error GoTo ErrorHandler
vsoDataRecordset.DataConnection.Timeout = 15
'Refresh the data. This will fail if the file cannot be reached
vsoDataRecordset.Refresh
Exit Sub
ErrorHandler:
Debug.Print "Error: ", Err.Description
End Sub
243
243
Lab 3.7: Data Linking

During this lab, you will recreate a portion of the ScheduleBuilder program. In the process you will also
fix some program errors that exist in the lab version of the file.
You will use automation code to:
1. Fix the error in finding and loading the Section DataRecordset from an external Excel
data file.
2. Link the Instructor shapes to rows in the Teacher DRS. (LinkSelectedInstructors)
3. Drop and link the Section shapes to rows in the Section DRS. (DropSectionShapes)
4. Refresh the Section DRS after changing the Excel file to add one or more records, delete
one or more records and modify one or more records
5. Fix a problem in the linking/refresh conflicts logic that is preventing the conflict
resolution from working properly.
Before You Begin

Participants should have completed the Try This! Lessons of this module before
completing this lab.
Visio 2007 or later installed and configured.
The following files are needed to complete this lab:

o
Lab Module 3 Start.vsd
ScheduleBuilder.vss
ScheduleBuilder.xls
Completed Visio drawing created in lab 3.6 (a completed file is provided)
What You Will Learn

Attach to an external data set via automation code
Automatically link shapes to rows in a DataRecordset
244

244
Drop multiple shapes onto a drawing and link them to rows in a DataRecordset
Manage Refresh of external data and resolve refresh conflicts
Exercise 2: Connect to an external data set

Scenario
There is an error when opening the drawing Lab 3.8 Start.vsd. The error appears when trying to connect
to an Excel file. You must diagnose the error and repair the code.
Tasks
1. Start Visio and open the file Lab 3.8 Start.vsd. The following error message appears.
2. Select Debug and review the comments in the code. Recode the CreateLink procedure to
load the DataRecordset properly.
Exercise 2: Link the Instructor shapes to rows in the Teacher

DataRecordset
Scenario
The Instructor shapes must be linked to their respective rows in the Teacher DRS in order to later drop
the Section shapes properly.
Tasks
1. Look at the macro LinkSelectedInstructors. It is incomplete.
245

245
2. Read the comments in the code and complete the macro.
Exercise 3: Drop and link the Section shapes to the rows in the
Section DataRecordset
Scenario
The macro DropSectionShapes will drop a Section shape for each record in the Section DRS.
Tasks
1. Find the macro DropSectionShapes. It is incomplete.
2. Read the comments in the macro and complete the code.
Exercise 4: Change the external data, refresh the drawing, and

manage changes required by the data
Scenario
Change the Excel file containing the Section data so that some new records are added, some existing
records are deleted, and some existing records are changed. Refresh the DataRecordset from the user
interface. You find that the conflicts are not being refreshed correctly.
Tasks
1. Look at the event procedure sectionRecordset_DataRecordsetChanged. This event
procedure listens for changes to the DRS and then evaluates and processes the changes.
It adds new Section shapes for each new record added, deletes Section shapes for any
deleted records.
You will find that the updates are not happening properly. Your task is to figure out why
and make the necessary changes.
246
246
Additional Resources External Data

Whats New for Developers in Visio 2007 (Part 1 of 2)
This article introduces new features of interest to developers in Microsoft Office Visio 2007 and explains
how to use them. Author: Saul Candib.
Whats New for Developers in Visio 2007 (Part 2 of 2)

This article describes all new objects and members of the Visio 2007 VBA object model and newly
deprecated existing members. Author: Saul Candib.
Visio Developer Portal

http://msdn2.microsoft.com/en-us/office/aa905478.aspx
Integrating Visio 2007 and Microsoft SQL Server 2005

Learn how you can integrate Microsoft Office Visio 2007 with Microsoft SQL Server 2005, to create datadriven diagrams from stored SQL data.
http://msdn2.microsoft.com/en-us/library/bb267248.aspx
Integrating Visio 2007 and Access 2007

Use Automation code to create a Visio drawing from data defining the contents of a drawing and the
connectivity between shapes stored within Access tables.
247
247
Visio 2010 Beta: Software Development Kit

The Microsoft Office Visio Software Development Kit (SDK) contains the latest documentation, samples,
header files, libraries and tools that you need to develop custom solutions for Microsoft Visio. As of this
writing the 2010 Beta version was the latest version available.
http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=1cdbb7e7-6bd4-488f91bd-7bd732dbf378
About Connecting to Data in Visio

About Linking Shapes to Data

248
248
Review: Managing External Data Sets

Questions
1. What are the three methods of the DataRecordsets object for creating new
datarecordsets?
2. What is different about the datarecordset created using the AddFromXML method?
3. Where can the connection string be found in the object model?
4. Where can the command string be found in the object model?
5. When adding a datarecordset, how is the primary key set?
6. Which property of the DataConnection object is key to catching errors thrown when a
data source cannot be reached?
7. True or False. When creating and linking shapes using the DropLinked and
DropManyLinkedU, the shapes are created and linked at the same time, but a data
graphic has to be added as a separate step.
8. True or False. A shape can be linked to multiple datarecordsets with a single command.
9. True or False. To link multiple shapes to a single row you can use the Shape.LinkToData
method multiple times.
10. How does a programmer reliably detect when a shape link has been broken, either
through programmatic actions or through user actions.
11. True or False. GetAllRefreshConflicts can be used by the programmer to discover all
changes that occur during a refresh operation.
12. How does the programmer control display of the Refresh Conflicts task pane?
13. True or False. The DataRecordsetChanged event will fire immediately following the
Refresh method.
249
249
Answers
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
Add, AddFromConnectionFile, and AddFromXML

It is a connectionless datarecordset.
It is in the DataConnection object which is part of the DataRecordset object.
The DataRecordset object.
The primary key is set as a separate step from the Add. Use the SetPrimaryKey method of
the DataRecordset object.
Set the Timeout property. When the interval is exceeded and error is thrown.
False
False. The LinkToData method must be called once for each datarecordset.
True. This will work, but use the Selection.LinkToData to do it in one step.
Use the ShapeDataLinkDeleted event.
False. This only gives information on conflicts. Use the DataRecordsetChanged event and
DataRecordsetChanged object to get additional data on records added or deleted and
columns changed, added, or deleted.
vsoDataRecorset.RefreshSettings = visRefreshNoReconciliationUI
False. There can be a time lag between the Refresh and the firing of the event which
means code following the Refresh may execute before code in the event procedure. Put
any conflict resolution code or code that looks for datarecordset changes inside the event
procedure.
250
250
Visio Software Development Kit (SDK)

This module covers all aspects of the Visio 2010 SDK. The SDK is made up of code samples, sample
applications, tools, and documentation to support developers creating shapes, creating code, and
delivering their own custom solutions on Visio.
Note:
At the time of this writing the Visio 2010 SDK was still in beta. Little of the
documentation has been updated and some sample files have not been released
and therefore are not covered. The reader may find differences between the
discussion in the final version when the RTM version of the SDK is released.
Hopefully those differences will be minor.
Module Objectives
Understand all of the parts that make up the Visio SDK

Use the tools delivered with the SDK to aid in manage events and publish solutions
Use the sample code from the code library in your own programs
Use the sample applications as examples for creating add-ins and add-ons for Visio
251
251
Lesson 1: Setup / Overview

The Microsoft Office Visio 2010 Software Development Kit (SDK) contains the latest documentation,
samples, header files, libraries, and tools that you need to develop custom solutions for Microsoft Office
Visio 2010.
Visio SDK 2010 Contents

To open the Visio 2010 SDK, click Start > All Programs > 2010 Microsoft Office Developer Resources >
Microsoft Office Visio 2010 SDK.
The Visio 2010 SDK includes:
Microsoft Office Visio Code Samples Library. A database of Visio code samples.
In the Code Samples Library, you can select a code item from the tree-view Explorer
window, or you can search and select the desired code item from the Search Results tab.
You can use the Code Samples Library to view and copy many reusable classes, functions,
and procedures.
To open the Code Samples Library, click the Start button, point to Microsoft Office 2010
Developer Resources, then point to Microsoft Office Visio 2010 SDK, and then click
Microsoft Office Visio Code Samples Library.
Sample applications. The provided sample applications can be used to experiment and
to become acquainted with features. These sample applications are written both to
demonstrate aspects of developing on the Visio platform and to be used as a starting
point for your custom applications.
Tools. Customization and extensibility tools are provided to increase your productivity
and reduce development time. These tools include the Persistent Events, Print
ShapeSheet, Solution Publishing, and Event Monitor tools.
The SDK also includes wizards to set up new Visio add-ons and Component Object Model
(COM) add-ins in Microsoft Visual C#, Microsoft Visual Basic .NET, Microsoft Visual C++
and Microsoft Visual Basic.
Documentation The documentation includes the full set of Visio references and articles.
252

252
You do not need to have the Microsoft Office Visio 2010 application installed on your computer to be
able to install the Visio 2010 SDK; however, for selected code samples or tools to run properly, Visio is
required.
Locating the SDK Files

By default, the Visio 2010 SDK is installed in the following folder:
C:\Program Files (x86)\Microsoft Office\Office14\visSDK\ for the 32 bit version of the Visio SDK.
To uninstall the SDK at any time

In Control Panel, click Add or Remove Programs, click Microsoft Office Visio 2010 SDK, and then click
Remove.
Software Requirements for Visio 2010 SDK Tools and Samples

Although you do not need to have Visio 2010 installed on your computer to be able to install the Visio
2010 SDK, the following tools and samples will not run correctly unless the following software
dependencies are met.
Table 2. Visio 2010 SDK software requirements for tools and samples
Tool or sample
Persistent Events tool
Event Monitor tool
Print ShapeSheet tool
Visio Solution Publishing tool
Microsoft Visual Studio 2005 Visio Addin wizard
Microsoft Visual Studio 2008 Visio Addin wizard
Microsoft Visual Basic 6.0 Flowchart
sample application
Microsoft Visual Basic .NET Flowchart

sample application
Software requirements
Visio 2010
Visio 2010
Visio 2010
Visio 2010
Microsoft Visual Studio 2005
Microsoft Visual Studio 2008
Visio 2010
Microsoft Office Excel 2007
Microsoft Office Word 2007 (to embed the drawing into
a Word document)
Visio 2010
Excel 2007
Word 2007 (to embed the drawing into a Word
253

253
C# Flowchart sample application
C++ Flowchart sample application
TreeView sample application
Office Plan sample application
Visio 2010 Code Samples Library
document)
Microsoft .NET Framework 1.1 or Microsoft .NET
Framework 2.0
Visual Studio .NET 2005 or Visual Studio 2008
Visio 2010
Excel 2007
document)
Framework 2.0
Visio 2010
Excel 2007
document)
Visual Studio .NET 2005, Visual Studio 2008, or Visual C++
6.0 (Service Pack 3 or later)
Visio 2010
Framework 2.0
Visual Studio .NET 2005 or Visual Studio 2008 (to build
the sample code)
Visio 2010
Framework 2.0
Visio 2010
2007 Microsoft Office System
Known Issues and Notes
Some sample applications and code samples in the Visio 2010 Code Samples Library
require the installation of Microsoft Office applications or Visio 2010 solutions and
wizards. See Visio 2010 SDK Samples located in the Samples folder in this SDK for more
information about specific requirements.
254

254
In versions of Visio previous to Visio 2007, Shape Data was called Custom Properties. In
the Visio 2010 SDK, these terms are used interchangeably; they both refer to the concept
of attaching user data to Visio shapes.
In order to compile SDK samples in Visual Studio running on the Microsoft Windows Vista
operating system, you must have administrative rights in Visual Studio.
Microsoft SQL Express 2005 is available as a free download at the following URL:
http://www.microsoft.com/downloads/details.aspx?FamilyID=220549b5-0b07-4448-8848dcc397514b41&DisplayLang=en.
Documentation
This documentation contains reference material describing the Visio 2010 Automation Interface, the
Save as Web Page Interface, the ShapeSheet interface and the XML schema documentation.
Visio 2007 Automation Reference

Provides an overview of Automation in Visio. It includes information about the Visio object model, the
Visio type library, and about extending the functionality of Visio with macros, add-ons, and COM
(Component Object Model) add-ins. A sample Microsoft Visual Basic for Applications (VBA) macro is also
provided. This reference provides details on Visio objects, properties, methods, and events.
Save as Web Page Reference

Provides an overview of using the Save as Web Page API with Microsoft Office Visio 2007. Details about
the Save as Web Page methods, objects, enumerations, and properties are provided. There is also an
example of a Microsoft Visual Basic example of the Save as Web Page object model.
ShapeSheet Reference
Provides an overview of the ShapeSheet spreadsheet in Visio, including 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. Details on
each section, row, and cell in a ShapeSheet spreadsheet and details on functions you can use in formulas
are provided.
XML 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,
255
255
round-tripping XML data, embedding custom XML data, units of measure, and errors and warning
messages.
Containers
Folders Installed with the Visio 2010 SDK
The following table describes the folders that are installed with the Visio 2010 SDK.
Table 9. Visio 2010 SDK folders
Folder name
\Docs \
\Libraries\
\Samples \
Description
References and articles
Support files
Sample applications that demonstrate how to use the Visio
programming model
Development, customization, solution-publishing, and
extensibility tools
Wizards to simplify developing Visio applications
\Tools \
\Wizards\
Docs folder
visSDK.chm entry point into help files for Visio 2010 SDK Documentation
Libraries
CPP folder C and C++ files

o
Include
AddSink.h contains the prototype for the event call back function
(VISEVENTPROC) along with the class definitions for VEventHandler and
CVisioAddonSink.
Helpers.h - contains the definitions of helper classes to be used with the

wrapper code in Visiwrap.h. You can choose to use no helpers, or nonMFC helpers or MFC-aware helpers.
Ivisreg.h - contains helper functions for launching the Visio application.
Vaddon.h - contains the definition of a superclass for Visio add-ons.

256

256
Vao.h - contains definitions that define the interface between Visio and
VSLs.
Visio.h - this ALWAYS GENERATED file contains the definitions for the
interfaces
Visio_i.c - this ALWAYS GENERATED file contains the IIDs and CLSIDs
Visiwrap.h - contains a set of wrapper classes and their implementations

for the Visio automation API
Source
AddSink.cpp - contains implementation of Visio's Advise Sink event

handling.
Helpers.cpp - contains the implementation of helper classes to be used
with the wrapper code in Visiwrap.h.
Ivsireg.cpp - contains helper functions for starting Visio and getting access
to the IVisioApplication interface.
Vaddon.cpp - provides the entry point for a Visio VSL. It also provides an
add-on 'manager' superclass called VAddon. You can use VAddon as the
base class for Visio add-ons.
Vao.c - This file provides implementations for the routines prototyped in
vao.h.
Vdllmain.c - contains an implementation of DllMain for Win32 VSL's.
Vexe.cpp - implements the standard Windows message

loop and
window procedure for EXE based VAddon subclasses. It allows VAddonderived classes to be compiled into an EXE with no additional effort.
TypeLib folder contains the following type library files

o
Visio.tlb 2010 type library
SaveAsWeb.tlb Visio 2010 Save as Web type library
VisOCX.tlb Visio 2010 Drawing Control type library
Samples
The Samples folder contains the Code Samples Library folder which contains a .chm file with many
examples of common tasks done in Visio through automation. Directions are provided on how to copy
code directly from the help file into your project.
257
257
It also contains three complete projects:
FlowChart - shows how to create a Component Object Model (COM) add-in that automates the
creation of a flowchart drawing from a Microsoft Office Excel spreadsheet, uses command bars
in the Visio user interface, and publishes the drawing to the Web or to a Microsoft Office Word
document. The code is available in C++, C#, VB, and VB .NET.
OfficePlan - shows how you can use the Microsoft Visio 2010 Drawing Control to create an
application that takes advantage of the drawing features of Microsoft Visio 2010 in a Microsoft
Windows Form. The sample application can be used to select furniture from an inventory list
and plan the space for a conference room or office. The code for this application is in C#.
TreeView - shows how to create a hierarchical drawing and its accompanying tree view in
Microsoft Office Visio 2010. The sample application provides a summary view of a drawing
that has many shapes and which therefore can be hard to view on the page. The sample
application is a Visio COM add-in, written in Microsoft Visual Basic .NET.
Note:
The final Visio 2010 SDK is expected to have a new VSTO Add-in Sample
Application that uses a "ClickOnce" post-deployment action to install Visio
template and stencil files and also samples for API functionality added in Visio
2010.
Tools
This folder contains Help files and for using a set of tools provided with the Visio 2010 SDK:
Event Monitor tool that monitors events that are fired by an instance of Visio and reports
events based on options you select in the Event Monitor user interface.
Persistent Events - provides a user interface that lets you add persistent events in an active Visio
document and modify existing persistent events.
Print ShapeSheet - provides a user interface that lets you print ShapeSheet data for one or more
shapes, a document, or a page, or lets you print ShapeSheet data for all document styles.
Solutions Publishing tool that provides a user interface that lets you generate entries to insert
in the PublishComponent table in a Windows Installer (.msi) file for publishing Visio content.
Each of these tools is covered in more detail later in this module.
Note:
258
258
Wizards
The Visio 2010 SDK contains two add-in wizards, one for Visual Studio 2005 and the other for Visual
Studio 2008. These wizards create a shell add-on or add-in project in Microsoft Visual Studio .NET
2003, in Microsoft Visual Basic .NET, Microsoft Visual C#, and Microsoft Visual C++, to help speed the
development process and demonstrate suggested practices for developing Visio add-ons or Component
Object Model (COM) add-ins.
This tool is covered in more detail later in this module.
Note:
TypeLibs Included
The Microsoft Visio 2010 Software Development Kit (SDK) provides type libraries for three application
programming interfaces (APIs) that Microsoft Office Visio 2010 exposes. The following type libraries are
included in the TypeLib folder, the path to which is SDK\Libraries:
Library
Visio.tlb
SaveAsWeb.tlb
VisOcx.tlb
Contents
Visio type library
Save as Web type library
Microsoft Office Visio Drawing Control type library
Visio type library

An overview of the Visio type library was given in the beginning of Volume 3 of this course.
Save As Web type library

The Save As Web interface is not covered in this class, but there is a good example of how to use it
provided in the Flowchart sample program in the SDK. The Flowchart sample uses this interface to save
Visio drawings as web pages.
Visio Drawing Control type library

The Visio Drawing Control can be used to embed the full functionality of the Visio drawing surface into
your applications. You can take advantage of the full Visio object model (API) and you can pick the
259
259
aspects of the Visio user interface you want to expose to better integrate Visio seamlessly into the user
interface of your application.
Use of the Visio Drawing Control will be covered in the next module of this course: Module 5: Visio
Drawing Control
Changes from Visio 2010 SDK

The following are changes to the SDK since the 2003 version.
Shape Studio has been removed
Visual Studio 2005 and 2008 Add-in Wizards

The Visio SDK installs wizards for creating Visio add-on projects in Microsoft Visual Studio 2005 and
Microsoft Visual Studio 2008. These Wizards let you set up new Visio add-on projects in Microsoft Visual
Basic .NET, Microsoft Visual C#, and Microsoft Visual C++, and create corresponding setup programs to
install add-ons. Once you have used the wizard to create a Visio project, you can explore the project
code and settings to learn more about how Visio add-ons should work.
260
260
Microsoft Visual Studio 2010 also includes wizards to generate Visio 2010 VSTO add-in projects. The
Visio SDK is not required to use these wizards.
The Visio projects that you create by using this wizard are compatible only with Microsoft Office Visio
2003 or later. They will not work with other versions of Visio.
261
261
Projects created by these wizards provide examples of recommended Visio development practices. Once
you have used the wizard to create a Visio project, you can explore the project code and settings to
learn more about how Visio add-ons and add-ins should work.
Depending on the programming language that you choose with this wizard, you can create different
types of projects.
When you use the wizard for the Visual Basic .NET or C# programming languages, you can create
projects of the following types:
Executable add-ons (EXEs)

COM add-ins (DLLs)
When you use the wizard for the C++ programming language, you can create projects of the types listed
previously as well as VSL add-ons.
In the next steps we will build an add-on without the wizard and then build one with the wizard and
contrast the two projects in Visual Studio.
Try it! Create a project using the Windows Application template.

We will contrast this with using the add-in wizard afterwards.
1. Create a simple Visio add-on as a Windows Application. This add-on will start Visio, open
a stencil and build a simple flowchart. Follow the directions from the article How to
Automate Visio with Visual Basic .Net listed in the Additional Resources section of this
module.
Note:
This example is a little out of date. Add a reference to the Visio 2010 type library
instead of Visio 2002. Second, you will need to add one line of code at the
beginning of Module1 to work with the Visio 2010 PIAs. See the next step for
details. Third, there are a couple of uninitialized variable warnings that should be
fixed.
2. To make this example work with the Microsoft Office PIAs, add the following line of code
at the beginning of Module 1.
Imports Microsoft.Office.Interop
262
262
Note:
A finished example of this project is in the Samples folder for this course under the
folder WindowApplication1.
3. Copy the WindowApplication1.exe file to the desktop.

4. From Visio modify the add-ons file path to include the Desktop. Close Visio.
5. Restart Visio and run the add-on from the Tools menu.
Try this!
Create an add-on project using the Visio wizard for Visual Studio.
1. Create another project using the Visio add-in wizard. Choose File > New > Project This
opens the New Project dialog. Give the Project and the Solution a name such as
MyAddOn.
2. Under Project Types choose Visual Basic.
3. Under Templates choose Visio add-in or add-on. This starts the wizard. Choose Next.
4. For the add-on type choose Create a Visio EXE add-on. Choose Next.
5. Choose Finish to close the wizard and create the project. The default project displays the
argument string that is passed to the add-on in a dialog box. We wont change the
default code.
6. In Visual Studio build the project, Build > Build MyAddOn. This creates an .exe file in the
project bin folder.
7. Copy MyAddOn.exe to the desktop and make sure the add-ons paths in Visio is set to
search this folder. You may have to restart Visio in order for the add-on to show in the
Tools menu.
8. From Visio run the add-on from the Tools menu: Tools > Add-Ons > MyAddOn. The addon will display the dialog below.
263
263
9. Add a shape to the drawing and run the macro from the double click event of the shape.
You can use the Format > Behavior dialog or enter the formula
=RUNADDON("MyAddOn.exe")
directly in the EventDblClick cell in the ShapeSheet. Double click the shape. The add-on will
display a dialog similar to the one below.
264
264
Note:
An add-on can be run when a cell formula is evaluated. When this happens, Visio
automatically sends a command string to the add-on with the following
information:
/visio=instanceHandle /doc=docIndex /page=pageIndex /shape=NameID
This information can be used by the add-on to access the shape that caused the
add-on to execute.
Try it! Create a COM Add-in project using the Visio wizard for Visual Studio.
1. Create another project using the Visio add-in wizard. Choose File > New > Project This
opens the New Project dialog. Give the Project and the Solution a name such as
MyAddIn.
2. Under Project Types choose Visual Basic.
3. Under Templates choose Visio add-in or add-on. This starts the wizard. Choose Next.
4. For the add-on type choose Create a Visio COM add-in. Choose Next.
5. Give the add-in a meaningful name and description. Choose Next.
6. Select Load the add-in when the Visio application loads. Choose Next.
7. Choose Finish to close the wizard and create the project. The default project will display a
message box when the add-in is loaded.
8. In Visual Studio build the project, Build > Build Solution. This adds the generated .dll to
the Windows registry.
9. Close Visio and then start Visio. The add-in loads when Visio starts and displays the
message MyAddIn connected.
Contrast the three projects in Visual Studio

Lets take a look at these three projects.
Using Windows Application template

The project is a bare bones project when it is created. A default form is created, but that is about it.
The developer has to do everything else. In this example we completed the form and then added a
module and code that launched Visio and built the drawing.
The form is the startup for the application by default, but you can change this in the
Project Properties window.
There is also no setup project created for us.
265
265
Using the Visio template to create an .EXE

A default project is built with code that parses the command string that is sent to the add-on. When
creating your own add-on this code can be deleted if it is not needed by the add-on. In addition to this
code, the following is created as part of the project.
There is a main procedure in VisioEXEAddon.vb that serves as the startup location for the
project. Whether a form is displayed is controlled by this code.
There is a setup project constructed by default.
There is a default application icon file.
There is a default assembly created and default project resource strings.
Using the Visio template to create a COM add-in

A default project is built with code that displays a message box when the add-in is first loaded. Also
created for this project:
A Connect.vb module. This module contains code that implements the interface for
connecting to a COM add-in.
There is a setup project constructed by default.
There is a default assembly created and default project resource strings.
266
266
Lesson 2: Tools
The Visio 2010 SDK comes with a set of tools to aid developers in managing events and publishing
solutions. These tools can all be found in the SDK Tools folder. The Event Monitor, Persistent Events
tool, and Print ShapeSheet can all be started from the Developer tab in Visio once the SDK is installed.
The Solution Publishing tool can be started from the SDK or from the Start menu.
Lesson Objectives
Use the Event Monitor tool to track events fired in Visio

Use the Persistent Events tool to add, edit, or delete persistent events in drawings
Use the Print ShapeSheet tool to write the ShapeSheet data to the Clipboard, to a file, or to the
printer
Use the Publish Components tool to bind stencils, template, drawings, and other files to a Visio
solution that you create
Event Monitor
The Microsoft Visio Event Monitor tool watches for events that are raised in an instance of Visio and
logs all events of the types that you specify in the Event Options dialog box. The Event Monitor can help
you determine which events to handle in your own solutions.
The Event Monitor uses the AddAdvise method of the EventList collection of the Visio Application
object to monitor and report events by the Visio Application object. The Event Monitor reports all
events that are sourced by the Application object, except for events that are raised by keystrokes and
targeted at an add-on window (the OnKeystrokeMessageForAddon event). For the list of events that
the Visio Application object can raise, see the Microsoft Office Visio Automation Reference. (On the
Help menu, click Developer Reference.)
Note:
Because the Event Monitor runs in a separate process from Visio, depending
on the order in which processes are suspended, the Event Monitor may be
suspended before Visio and, hence, may not monitor and report the
BeforeSuspend, QueryCancelSuspend, and SuspendCancelled events,
even if you include them in the Events to monitor list.
267
267
To start the event monitor from Visio choose Developer > Event Montior.
The Event Monitor tool automatically connects to a running instance of Visio, or if Visio isn't already
running, the Event Monitor starts a new instance of Visio. When the Event Monitor starts, the log
displays the following information:
The version of Visio that it has connected to or started

The Microsoft Office Visio Type Library version number
The process ID of the Visio instance
The list of monitored event types and their status; that is, that they are set to be
monitored. Event types previously set to be ignored in the Event Options dialog box are
not listed at startup.
When all events in the Visio events queue have been processed, Microsoft Visio fires the
NoEventsPending event. When Visio has emptied its message queue, Visio fires the VisioIsIdle event.
When there has been no activity in Visio for a time, you will see these two events at the bottom of the
list in the event window.
When a monitored event fires, the Event Monitor tool displays its name and, depending on the event
and your Event Monitor settings, additional data about the event. For example, if you drag a Rectangle
shape onto the drawing page, the ShapeAdded event fires. In the log window, the Event Monitor
reports the event firing as follows:
21365 | ShapeAdded Rectangle [/doc=1 /page=1 /shape=Sheet.1]
In this log entry:
21365 is the event sequence number, which is determined by the number of events that
have fired since Visio was started. Visio gives each event a unique sequence identifier to
distinguish between separate firings of the same event, and then passes that number as
one of the arguments to the VisEventProc function you write to handle that event.
ShapeAdded is the name of the event that fired.
Rectangle is the name of the master of the shape that was added.
Within the brackets, the Event Monitor tool displays the index number within the
Documents collection of the document in which the event fired, the name of the page
where the shape was added, and the name of the shape itself. Information within the
268

268
brackets is displayed only if the Include additional event information box is selected in
the Monitor Options dialog box.
Demo: Use Event Monitor to track actions in Visio

1. Start the Event Monitor from Visio. It lists the events being monitored and then lists
results for each new event as it fires. Note that there are a lot of MouseMove events
every time the cursor moves in the Visio window.
2. From the Event Monitor choose Tools > Event Options. Remove MouseMove from the
list. There are still a lot of events firing when the mouse moves.
3. Stop monitoring MustFlushScopeBeginning, MustFlushScopeEnding, and
NoEventsPending. Now it is easier to see some of the other events that fire when an
action occurs in Visio.
4. Add a shape from a stencil.
5. Copy and paste a shape.
6. Duplicate a shape.
7. Draw a shape using one of the drawing tools.
8. Note that each of these actions causes a ShapeAdded event, but ShapeAdded doesnt tell
you how a shape was added. How can we distinguish between these actions?
9. Note that there is always an EnterScope event that occurs for each of these actions and
within the EnterScope event we can test the command ID that was just executed. Add a
shape from stencil is done with command ID 1246 Drop on Page. Paste a shape is done
with command number 1022. Duplicate is 1024. Control drag duplicate is 1184. Drawing
shapes with the drawing tools gives unique commands for each tool used. Therefore it is
possible to tell exactly how any shape gets created!
Tip:
This is really handy if you want to do something different for shapes added to a
drawing, depending on how they are added. Just be sure to test for performance
as EnterScope gets called a lot!
10. Close Visio. Note the message displayed in the monitor.

Connection to Visio has been terminated.
To restart Visio, click Tools, then click Connect to Visio.
269
269
11. From the Event Monitor choose Tools > Connect to Visio. Visio is restarted and monitoring
is resumed.
About Using the Persistent Events Tool

The Persistent Events tool provides a user interface that enables you to add and modify persistent
events in the active Microsoft Visio Document object's EventList collection.
By persisting events in a document or template, you can make Visio run add-ons in response to user
actions, usually when users create a Visio document based on a template or open a Visio document or
template. The Persistent Events tool displays the list of events persisted in the active document or
template and for each event, shows the add-on that runs when that event fires and any arguments
passed to that add-on.
For more information about persistent events in Visio, see the Microsoft Office Visio Developer
Reference (on the Help menu, click Developer Reference).
Many solutions that are a part of the Visio product persist events in their templates. For example, the
DocumentCreated event is persisted in the Organization Chart template, and when this event fires, its
action is to run the Organization Chart add-on.
You can see evidence of this by opening a new or existing organization chart document (drawing) based
on the Organization Chart template and then, after making sure that this document is active, opening
the Persistent Events tool. In the tool's list of persistent events for the active document, you'll see a row
that contains the following data:
DocumentCreated OrgC11 /cmd=DocCreated
On this line, DocumentCreated is the name of the persistent event that fired, OrgC11 is the universal
name for the Organization Chart add-on in Microsoft Visio, and /cmd=DocCreated is the argument
passed to the add-on by the event. Whenever a new document is created based on the Organization
Chart template, the DocumentCreated event fires, calls the OrgC11 add-on, and passes the argument
/cmd=DocCreated to the add-on to indicate that DocumentCreated was the event that fired. For addons to run and take the appropriate action, they must know which event fired.
When writing an add-on solution, add persistent events that call your add-on in the Event Properties
dialog box (which is accessible from the Persistent Events tool). In the Event Properties dialog box, in
270
270
the Event box, you can select from the following list of persistable events sourced by the document
object:
1.
2.
3.
4.
5.
6.
7.
DocumentCreated
DocumentOpened
MasterAdded
BeforeMasterDelete
PageAdded
BeforePageDelete
ShapesDeleted
The Universal name list box is populated with the names of all add-ons in the Add-ons collection of the
Visio Application object. To specify the add-on to run when the event fires, either select it from the list,
or, for a new add-on, type its name.
Note:
Note:
You must first install the new add-on before persisted events will
run it.
If the add-on's name you type doesn't exist, Visio doesn't display
an error message; however, you can use the TraceFlags property
of the Application object to view errors in the Immediate window.
Optionally, pass an argument to the add-on. When the event you selected in the Event list fires, the
value you enter in the Argument box gets passed to the add-on; you can use it to inform the add-on
which event called it. This feature is useful if the add-on needs to handle different events differently. For
example, you may want your add-on to respond differently if a new document is created than if an
existing document is opened.
You can also use the Persistent Events tool to edit existing persistent events, for example, to change an
argument string, or to delete persistent events.
Try it!
1. Create a new organization chart drawing in Visio.
2. Start the Persistent Events tool: Developer > Persistent Events. The dialog below is
displayed. Note that the DocumentOpened and DocumentCreated events are persisted in
271
the organization chart template.
271
3. Add a new persistent event for PageAdded and hook the event to the add-on created in
the last section of this module, MyAddon. This add-on displays the command string
passed to it. You should see something similar to the dialog below.
Persistent Event information in the Visio object model

Persistent Events can be added, edited, and deleted by using the Visio object model. The Event object
has a Persistable property (read-only) and a Persistent property (read-write). Set the Persistent
property to True. The Target and TargetArgs properties contain the add-on name and the argument
272
272
string. The Event property of the Event object contains the event code, e.g., the code for PageAdded is
visEvtAdd+visEvtPage.
Note:
There is a known problem that causes an overflow error when working with event
codes with values greater than &H8000. To get around the problem pass the event
code argument using the hex representation instead of the Visio constants.
Try it!
1. Open PersistentEvents.vsd from the Samples folder. This drawing was created from an
organization chart template so it already has some persistent events in it.
2. Start the Persistent Events tools and view the existing persistent events.
3. Run the macro PrintPersistentEvents. This prints the persistent event information from
the object model to the Immediate Window. View the code.
4. Run the macro EditOrAddPersistentEvent. This will edit an existing PageAdded persistent
event if it exists or add it if it does not. View the code.
Print ShapeSheet
The Microsoft Visio Print ShapeSheet tool provides a user interface that lets you print ShapeSheet
spreadsheet information for one or more selected shapes, a Visio document, the styles defined in the
document, or the current drawing page. You can send the result to the Clipboard, a file, or a printer. You
can use the Print ShapeSheet tool to print data from various sections of the ShapeSheet and to search
for cell references and dependencies in various formulas.
To start the Print ShapeSheet tool, from Visio choose Developer > Tools > Print ShapeSheet. The Print
ShapeSheet dialog is displayed below.
273
273
Under Sheet type: choose from: Selected shapes, Document, Styles, Page, and All Shapes. The default
choices under Include sections will change depending upon the choice made. Use this section to choose
which ShapeSheet sections are to be captured in the output.
Under Send to: choose from File, Clipboard, and Printer.
If there are grouped shapes on the drawing page and you want to print data for individual shapes within
groups, select Include group subshapes.
Sample output that was sent to a text file is shown below.
274
274
Note that both a cells value and its formula are included.
Publish Component
Beginning with Microsoft Visio 2003, you can publish your add-ons, templates, stencils and other files as
components to be integrated with the Visio application. Publishing components is the preferred method
of integrating add-ons and other content with Visio. It offers tighter integration with the Visio
application, and better performance on add-on discovery.
The publish component functionality enables developers to include a PublishComponent table in the
Microsoft Windows Installer file that they create to install content (such as add-ons, templates, stencils,
or other files). Each PublishComponent table entry contains information pertaining to how a specific file
to be installed should be displayed in the Visio user interface. During installation, these entries are
published to the Visio registry. Visio uses this information to display the add-on in its user interface, and
install on-demand or repair the file as needed.
Publishing Content
Tip:
The following content is derived from the Visio Insights blog produced by the Visio
team at Microsoft. This is a great source of practical how to information.
275
275
Publishing a piece of content to Visio adds entry points to the user interface side-by-side with content
created by Microsoft. For a stencil this translates into a menu entry added to the File > Shapes fly-out
menu while for a template this means an entry in Visios startup screen (as seen below) and in the File >
New fly-out menu.
Method #1: Sharing Templates using Path Discovery

The simplest way to publish a template to Visio is to use the Path Discovery method described below:
1. Copy your template and supporting stencils to a known location on a drive.
2. Add the location defined in step 1 to Visios Template Paths; this tells Visio where to find
extra content to populate its startup screen.
3. Restart Visio your template should appear in the (Other) category.
276
276
The advantages of this approach are:
It is simple.
It is supported across most versions of Visio.
It however has a few drawbacks:
Your users may be subjected to potentially long and error prone manual work.
Your templates will always end up in the (Other) content category in the startup screen.
You dont have any way of repairing content on a users machine if it gets damaged.
You cannot control which language of Visio will load your stencils and templates.
This approach does not scale well. The Path Discovery publishing method does just that:
every time you boot Visio it searches a users hard drive for content files an expensive
operation.
Sharing templates through Path Discovery is good for small scale content deployments as well as
deployments to older versions of Visio.
Method #2: Sharing using the PublishComponent System

The PublishComponent system introduced in Visio 2003 lets developers use Windows Installer
technology for template distribution to register their content with Visio in a rich and robust way. The
main advantages of this method are quite interesting:
The Windows Installer setup wizard is familiar to users and easy to use.
You benefit from Windows Installer repair, install-on-demand and add/remove features.
You may choose what language versions of Visio to publish your content to.
The approach scales well: Visio only rebuilds its content cache, a moderately expensive
operation, when new content is published.
The approach is tried and tested since the product publishes its own content this way
since the 2003 release.
That said, using the Publish Component system is:
A little more complicated than the Path Discovery method.

Will only work for Visio 2003 and or later.
To use this method youll need Visual Studio .NET or later, the Visio 2003 SDK or later.
277
277
Try it!
1. Create a simple template and stencil that will be added to the published solution. Save
the files.
2. Create a setup project in Visual Studio.
3. Select the "Application folder" and change its default location property to your target
install location. Add your template and their supporting stencils to this location by
dragging files into the folders. Your project should look something like the figure below
at this point.
278
278
4. Build the project. This will produce an MSI file - a multi-table installation database that is
used by windows to coordinate setup.
5. Install the package as is. Visio will not discover the files the MSI installed.
To notify Visio on the whereabouts of these files, the next thing to do is populate the PublishComponent
table of the MSI produced above with registration data. Once installed, this extra information will force
Visio to rebuild its content cache and incorporate and display the new templates and stencils.
1. Start the Solution Publishing Tool that is included with the Visio SDK (a.k.a the publish
component tool). This tool may be found in the Start menu entry for the Visio SDK.
2. On the File menu, select New. It will prompt you for an MSI. Navigate to the one that
you've just built.
3. This will present the Visio Files that are in MSI. You must now, for each entry:
a. Set the LCID of the language for which you want the templates to be accessible in.
Do the same for the supporting stencils.
b. Set the position in the Visio startup screen hierarchy you want the template to
live in. This is defined by separating different levels of the hierarchy by \
symbols for example:
MyTemplateCategory\MyTemplateSubCategory\MyTemplateName. Do the
same with the supporting stencils, setting their location in the File > Shapes flyout.
Note:
For VSL files that contain more than one add-on, select the file in the list and click
Add Add-on on the Edit menu to specify information about the additional add-ons
implemented in the VSL.
To make the changes described above double click on each entry to bring up the
Template Information dialog seen below, or its counterpart the Stencil Information
dialog.
279
279
4. Press the "!" button in the tools toolbar; this will make modifications to the MSI's Publish
Component table.
5. Install the MSI.
The MSI can now be distributed; Windows Installer and Visio will do the rest. Although we
havent discussed it here, the same techniques can be used to publish add-ins and help
files.
280
280
Lab 3.8: Build and run the Visio SDK Flowchart sample
During this lab, you will:
1. Build and install the SDK Flowchart sample add-on for VB.NET
2. Review the basics of how this sample application is put together
Before You Begin

Participants should have completed the review of this module before completing this lab.
Visio 2010 SDK installed and configured.
Software required for the SDK Flowchart code sample:

o
o
o
o
o
Visio 2010
Excel 2007
Word 2007 (to embed the drawing into a Word document)
Microsoft .NET Framework 1.1 or Microsoft .NET Framework 2.0
Visual Studio 2005 or later
What You Will Learn

Build and run the Flowchart example from the Visio 2010 SDK
Understand the software architecture for this sample
Exercise 3: Build and run the Flowchart (VB.NET) sample code

from the SDK
Scenario
Build the Flowchart code sample in Visual Studio, install the COM Add-in, create a drawing from the
Flowchart(VB .NET) and run.
281
281
Tasks
1. Copy the project files from the SDK folder to the Visual Studio 2005 Projects folder. From
the SDK folder you can copy everything from \visSDK\Samples\Flowchart.
2. In the Visual Studio 2005 Projects folder double-click \FlowChart\VBNet\Visual Studio
80\FlowchartSample.sln to open the project in Visual Studio 2005.
3. In the Solution Explorer window right-click on FlowchartSample and choose Build.
4. In the Solution Explorer window right-click on FlowchartSampleSetup and choose Build.
This creates FlowchartSampleSetup.msi in the \Visual Studio 80\bin\Debug\Setup folder.
5. Double-click FlowchartSampleSetup.msi to install the COM Add-in.
6. Start Visio and verify the add-in is loaded.
a. Choose File > Options > Add-ins
b. Find FlowchartSample (VB.NET) in the Active Application Add-ins list
7. Create a new drawing from the Flowchart (VB.NET) template, File > New > SDK > Samples
> Flowchart (VB.NET). The following dialog will be displayed:
8. Choose Yes. The add-in will build a multi-paged flowchart. Choosing No will do the same
thing, but screen updating is turned off so you wont see anything until the process is
complete.
9. Note that a new toolbar has been created: SDK Flowchart Publication. It has two buttons
for publishing the drawing to Word and publishing the drawing to the web.
10. Click the button to publish to Word. This copies the active page to a Word document. To
put the other pages into Word you would need to go to each page individually and click
the button to publish to Word.
11. Click the button to Save Document as a Web Page.
282

282
12. Right-click a flowchart shape and choose Number Of Connections This command
displays a message box show the number of connections and the name of the connectors
glued to the shape.
Exercise 2: Code review.

Scenario
This is a high level break down of how the add-in has been architected.
Code components
1. Connect.vb
This class implements the IDTExtensibility2 interface, allowing it to serve as a COM add-in
for Microsoft Office Visio and initializes the Visio Application object's EventList with events,
for which the Flowchart Sample add-in will listen.
2. EventSink.vb
This class is an event sink for Visio events. It handles events from Visio which were specified
using AddAdvise. It handles event notification by implementing the IVisEventProc interface,
which is defined in the Visio type library.
In order to be notified of events, an instance of this class must be passed as the EventSink
argument in calls to AddAdvise. The Flowchart Sample calls AddAdvise once in Visio on the
Connect module where it registers for Marker events sourced by the Application object.
The code in this class processes marker events created by this Flowchart sample. It listens
for three events:
a. DocumentCreate creates a new drawing when a user creates a new document
based on the Visio SDK Flowchart Sample template
b. DocumentOpen creates a custom command bar when a document created from
the SDK Flowchart Sample template is opened
c. handleRightMouseClick handles the case where the user does a right mouse
click on a flowchart shape and chooses Number of Connections
3. DocumentCreator.vb
This class creates a Visio document containing flowchart drawings, based on data contained
in a Microsoft Office Excel worksheet. The drawing process is driven by the CreateDrawing
procedure which is initiated from the DocumentCreate event handler.
283
283
4. CustomCommandbar.vb
Creates the custom command bar "SDK Flowchart Publication" and adds it to the Visio
CommandBars. It also contains methods to handle the click events for the buttons on the
custom command bar.
5. Publisher.vb
This class provides procedures to export a document to either a Web page or a Microsoft
Office Word document.
6. Shared.vb
Low level shared utilities and constants.
7. Assemblyinfo.vb
Provides the assembly information for the Flowchart Sample Add-in.
Other components
1. Flowchart (VB.NET).vst Visio template file for creating the drawings.
2. Flowchart.xls Excel file containing the shape and connection information for the
flowchart.
284
284
Additional Resources - SDK

Introducing the Microsoft Visio 2010 Beta SDK
Visio Insights blog about the first beta release of the 2010 SDK.
http://blogs.msdn.com/visio/archive/2009/11/19/introducing-the-microsoft-visio-2010-beta-sdk.aspx
Visio 2007: Software Development Kit

The Microsoft Office Visio 2007 Software Development Kit (SDK) contains the latest documentation,
samples, header files, libraries and tools that you need to develop custom solutions for Microsoft Office
Visio 2007.
http://www.microsoft.com/downloads/details.aspx?familyid=373d34b8-5ef7-4e6e-a582c8d6b5ee4e33&displaylang=en
Microsoft Office Visio 2007 SDK Release Notes

http://msdn2.microsoft.com/en-us/library/ms409266.aspx
Visio 2003 Software Development Kit (SDK)

The Visio 2003 SDK contains sample applications, code librarian code snippets, documentation, and
tools, including the ShapeStudio, Event Monitor, Persistent Events, Print ShapeSheet, and Solution
Publishing tools.
http://www.microsoft.com/downloads/details.aspx?familyid=557120bd-b0bb-46e7-936ab8539898d44d&displaylang=en
Visio 2002 Technical Articles

Technical articles from the Visio 2002 SDK. Many of the technical articles are still relevant, but they
arent repeated in later versions of the SDK.
http://msdn2.microsoft.com/en-us/library/aa167946(office.11).aspx
285
285
Visio Developer Portal

http://msdn2.microsoft.com/en-us/office/aa905478.aspx
How to automate Visio with Visual Basic .NET

This article demonstrates how to automate Visio using Visual Basic .NET. It does not use the add-in
wizard for Visual Studio.
http://support.microsoft.com/kb/305199
286
286
Review: SDK
Questions
1. What kind of add-ins and add-ons can be created for Visio with the add-in wizard in the
SDK.
2. What versions of Visio do projects created with this wizard work with?
3. What are some reasons for using the event monitor?
4. What are persistent events?
5. What is the advantage of using Publish Components over using Visios File Paths to detect
file locations?
287
287
Answers
1. Depending on the programming language you choose:
a. VSL add-ons (can only be created with C++)
b. Executable add-ons (EXEs)
c. COM add-ins (DLLs)
2. Only Visio 2003 and later.
3. Discover what events fire when certain actions occur in Visio.
4. These are actions defined to be kicked off when an event occurs. They are saved with the
drawing and do not need to be reestablished each time the drawing is opened thus they
persist.
5. It offers tighter integration with the Visio application, and better performance on add-on
discovery.
288
288
Visio Drawing Control

The Microsoft Visio Drawing Control offers the full functionality of the Visio application through the
rich Visio object model, as an embeddable component. You can drive the Visio drawing control
programmatically by events or by code in your hosting application. Alternatively, the Visio drawing
control can provide a diagramming environment for application users within the context of your own
application's user interface (UI).
Module Objectives
Describe how that drawing control can be used to provide a graphics rich application
without using the Visio user interface
Identify the features of the Visio drawing control and example use scenarios.
Describe best practices for creating new applications that use the drawing control.
Embed the Visio drawing control in a variety of host applications.
Use the properties of the Visio drawing control API to manage Visio from your host
application.
Deploy the Visio drawing control with your application.
289
289
Lesson 1: Concepts
The Visio Drawing Control is a Microsoft ActiveX control that provides full access to the Visio object
model (API) and user interface so that you can integrate the Visio user interface, customize its
appearance, and automate Visio in your applications. The Visio Drawing Control is provided with all
version of Visio and is installed when you install Visio.
The Visio Drawing Control allows the developer to provide Visio functionality within the context of
another application. This level of integration allows the developer full control over the Visio user
interface integration with the host application. The new functionality provides more power than just
simply embedding a Visio drawing into an OLE container document, like Word. Using a Visio drawing as
an OLE object allows you to view the diagram in the container application, link the OLE object to the
actual Visio document to reflect changes, and edit the Visio drawing by activating the Visio application
from within the container document.
In the case of in-place OLE activation, you are still working within the Visio user interface. You cannot
create your own UI. You are also limited to application hosts that implement an OLE container, which
rules out technologies such as .NET Windows Forms.
The Visio drawing control, however, provides functionality to address these scenarios, and allows you to
develop new Visio solutions that go beyond creating add-ons and add-ins for Visio. With the drawing
control you can create your own application with its own interface and be in control of how much of the
Visio user interface is presented to the user.
Lesson Objectives
Describe how that drawing control can be used to provide a graphics rich application without
using the Visio user interface
Describe the requirements of deploying an application containing the drawing control
Describe the types of container applications that can host the drawing control
Requirements / Containers
The Visio drawing component is essentially an ActiveX wrapper for the main Visio library. Like any
ActiveX component, it can be embedded in custom host applications developed using Visual Studio .NET
290
2003 and later, Office 2003 and later containers (such as Microsoft Word), Microsoft Internet Explorer
290
5.5 and greater, and other ActiveX component containers. Although the component uses the ActiveX
architecture, it is more of an embeddable application component than the typical ActiveX control found
on a Web site. The Visio component provides the full functionality of the Visio application rather than a
small subset of features.
Because it essentially repackages the Visio application engine in a component, the Visio control is
installed with the Visio application setup program and requires the Visio client application to initialize. If
the user does not have the Visio client application installed on the machine, the control will fail to
initialize in the host container.
Host container applications that support the Visio Drawing Control

You can embed the Visio Drawing Control in Microsoft Visual Basic 6.0, Microsoft Visual C++ 6.0,
Microsoft Visual Studio 7.1 and higher, and other ActiveX control containers. However, you cannot
embed the Visio Drawing Control in another Visio drawing, another ActiveX control, a Microsoft Visual
Basic for Applications (VBA) form in Visio, or a Visio solution window.
Security considerations
The Visio Drawing Control is targeted for use in an intranet environment. The Visio Drawing Control does
not support the IObjectSafety interface. Before it is run in any version of Internet Explorer, the control
warns the user that it is an unsafe file (unless the end user's browser security level is set to Medium,
Medium-Low, or Low).
Run-time requirements and distribution of your application

Microsoft Visio must be installed on any computer where the Visio Drawing Control will be used. When
you distribute your application, all users must have licensed copies of a version of Visio that supports
the Visio Drawing Control on their computers to use it.
Note:
To install the Visio Drawing Control, install Visio. The Minimal Install option of
Visio will install the Visio Drawing Control.
Demo: Drawing Control

The Office Plan Sample Application included with the Visio SDK shows how you can use the Drawing
Control to create an application that takes advantage of the drawing features of Visio in a Microsoft
Windows Form. The sample application can be used to select furniture from an inventory list and plan
the space for a conference room or office.
291
291
The sample creates a simple office floor plan that permits the end-user of the application, presumably a
corporate administrative assistant, to do the following:
Click any of three furniture shapes to add them to the drawing.

View dynamically updated information about the furniture that has been added.
View dynamically updated information about the total retail and wholesale costs of the
current contents of the office plan.
Save the results to a Visio drawing file and then re-open the file.
The code for this sample application is written in the C# programming language, and is designed to work
with Microsoft Visual Studio 2005 or Microsoft Visual Studio 2008.
Demo of Office Plan sample from the SDK.

The code for this sample is included in the Visio 2010 SDK.
Programming features implemented in the Office Plan Sample application

This sample application shows how to do the following:
Embed the Drawing Control in a Windows Form.

Use the Drawing Control interactively
Respond to various Visio events fired by user actions
Use mouse events to capture the right-click actions on a drawing shape
Use the MarkerEvent event and the EventDblClick ShapeSheet cell to respond to when
the user double-clicks shapes in the drawing.
Create a custom Windows form to display shape product information in an adjacent
DataGrid control
Use events to keep track of the shapes within the drawing and to calculate total price
information for these shapes
Save Visio drawings created by using the Drawing Control
Open Visio drawings in the Drawing Control
To build the sample code in the Office Plan Sample in Visual Studio 2005
1. Double-click OfficePlanSample.sln in the following folder:
C:\Program Files\Microsoft Office\Office14\VisSDK\Samples\Office Plan\CSharp\Visual
Studio 80.
292
292
The folder path may differ depending on where the SDK was installed.
Note:
2. In Visual Studio 2005, click Debug > Start Without debugging.

The application is started. The application image is shown below.
Add shapes to drawing

3. Click on the furniture buttons on the form. A shape is added for each click. The drop
location on the page is adjusted so that the shapes do not lie in exactly the same place.
4. As each shape is added the Total Price figures on the form are updated and the Product
data grid is updated. It maintains an accurate total of all of the shapes in the drawing.
293
293
Keyboard shortcuts are available

Many Visio keyboard shortcuts are supported in the drawing control.
5. Multi-select shapes and enter the keyboard shortcut Ctrl-G. The shapes are grouped
together.
6. Zoom in/Zoom out using Ctrl-Shift left mouse/right mouse.
7. Zoom to whole page with Ctrl-W.
Delete shapes
8. Delete an individual shape from the drawing.
9. Delete a grouped shape from the drawing. In both cases the Total Price and Products grid
are updated.
Save the drawing

10. Choose File > Save and enter a file name in the Save Visio Document dialog.
294
294
Start a new drawing

11. Choose File > New. A new blank drawing is created.
12. Choose File > Open and open the file saved earlier.
Try this! Application Architecture Review

Now lets take a look at how this application was architected. The following sections describe the
structure of the Office Plan code sample. Go through each section and view the code and shapes to see
how it works.
Embed the Drawing Control in a Windows Form.

When the application is started the frmOfficePlanSample form is displayed.
1. In Visual Studio in the Solution Explorer window, right-click frmOfficePlanSample.cs and
select View Designer. Right-click frmOfficePlanSample.cs again and choose View Code.
Both the code and design view for the form are displayed.
2. Look for the Main procedure in the code view of the form. This is the main entry point for
the application. It creates a new instance of the form.
3. Just above the Main procedure is the following code:
public OfficePlanSampleForm() {
// Initializing the components of the form is required for
// Windows Form Designer support
InitializeComponent();
}
This code is executed when the form is created. The InitializeComponent procedure is code
that is generated by the forms designer. It contains all form variable initialization, control
initializations, and menu definitions.
4. View the design view of the form. Click on the drawing control and scan its properties in
the Properties window. Note its name.
5. Click on the Events button in the Properties window for the drawing control. Scroll
through the list and note there are two event procedures defined for the drawing control:
MouseUpEvent and VisibleChanged.
295
295
The code for the VisibleChanged event is in onDrawingControlVisibleChanged. This event is

triggered initially when the form is created. Within the event procedure is a call to
setUpVisioDrawing.
Within setUpVisioDrawing is the code to establish the connection to the Visio application
object. It hides all Visio docked windows and then turns off display of rulers, grid, page
tabs, scroll bars. It then gets the viewing size of the window rectangle and does some
calculations for positioning shapes when they are created. It then initializes an event sink
to watch for Visio events with a call to initializeEventSink.
Event management
When using the Office Plan application the user is directly interacting with the Office Plan application
and indirectly interacting with Visio through the Visio drawing control. Events can be fired and listened
to for both the Office Plan application and for Visio.
For example, when the user clicks a button control in the Office Plan application, there is a click event
that is triggered. This click event instructs Visio to add the appropriate shape to the page. The action of
adding the shape to the page causes Visios shape added event to fire. The shape added event is used to
keep track of the number of shapes in the drawing and keep the product information up to date.
Why bother listening for Visios shape added event when we know that a shape is going to be added
when we click the furniture button? If everything works perfectly you might can assume that a shape
will be added and go ahead and process it, but in reality something might go wrong. For example, the
stencil that contains the shapes master may not be accessible by Visio and an error condition may be
raised. It is best not to add the product information for a new shape until you are sure that the new
shape has finished being added to the drawing. That doesnt happen until the Visio shape added event
is fired.
Respond to Visio events fired by user actions

The procedure initializeEventSink sets up for listening for events from Visio. This procedure is in
frmOfficePlanSample.cs. The following events are established in the event sink:
Shape add: OnAddProductInformation will be called when a shape is added

Shape delete: OnRemoveProductInformation will be called when a shape is deleted
Marker events: Used to trap double clicks on a shape for those shapes whose doubleclick event runs the QueueMarkerEvent addon. OnShapeDoubleClick will be called.
The VisEventProc method also listens for Visios NoEventsPending which occurs after Visio has finished
flushing its events queue. When a shape is added or deleted they are simply added to a queue of
296
296
shapes that need to be processed to update the product information. When the event
NoEventsPending is fired, the added and deleted queues are processed.
During processing of the shapes added and shapes deleted queues the totals for Retail price and
Wholesale price are updated on the form and the data grid is updated to reflect additions and deletions
from the drawing.
Use events to keep track of the shapes within the drawing and to calculate total price
information for these shapes
1. In the design view of the form select one of the furniture button controls.
2. In the property window note its name.
3. Scroll through the properties list and find the value in the Text property. This is the
master name that is retrieved from the stencil when this button is clicked.
4. Select the event procedures button in the properties window. Scroll through the list and
find the click event procedure. The event procedure is onFurnitureButtonClicked.
The onFurnitureButtonClicked method handles the event that is raised when one of the
furniture buttons is clicked. The button text field contains the corresponding name of the
master shape on the product stencil. The master is retrieved and dropped on the page.
5. When the furniture shape is dropped on the page Visios ShapeAdded event is fired. We
saw earlier how the event sink was established to listen for this event.
Use mouse events to capture the right-click actions on a drawing shape

1. In the design view of the form select the drawing control.
2. In the properties window scroll through the event list and find the MouseUpEvent. Note
that it is assigned to the procedure onDrawingControlMouseUp.
The onDrawingControlMouseUp checks for different kinds of mouse up actions which can occur when a
shape is right-clicked, such as when the user is using keyboard shortcuts to pan and zoom, or when a
user is selecting a shape. The main body of the code for onDrawingControlMouseUp is below.
// Check if the event was raised because of a right mouse button click,
// and the user is not zooming (control+shift+right mouse click)
// or selecting shapes (control+right mouse click).
if ((eventData.button == (int)VisKeyButtonFlags.visMouseRight) &&
((eventData.keyButtonState & (int)VisKeyButtonFlags.visKeyControl) ==0 )) {
// Look for a shape on the drawing page at the click location.
clickedShape = Utility.GetClickedShape(drawingControl,
297

297
eventData.x, eventData.y);
if (clickedShape != null) {
// Cancel the default processing of this event since
// it will be handled in this method.
eventData.cancelDefault = true;
// Show the shortcut menu at the click location. The
// coordinates need to be converted from the Visio page
// units that are in the event data to Windows pixel
// coordinates.
shapeShortcutMenu.Show(this,
Utility.MapVisioToWindows(drawingControl,
eventData.x, eventData.y));
}
}
Finding the shape is done inside Utility.GetClickedShape. This uses Visios SpatialSearch method of the
page to determine the closest shape to our mouse click location.
Use the MarkerEvent event and the EventDblClick ShapeSheet cell to respond to when the
user double-clicks shapes in the drawing
The detecting of when the user double clicks on a shape is handled with marker events. We saw earlier
how the event sink was set up to listen to marker events. Now lets look at how a marker event gets
fired in the first place.
1. In the design view of the form select the drawing control.
2. In the properties window scroll through the event list and note that there is no double
click event exposed for the drawing control. When you double-click on a shape within the
control, the shapes double click event fires which evaluates the EventDblClick cell in the
shapes ShapeSheet.
3. The Events section for the Office Chair shape is shown below. Note that the formula calls
RUNADDONWARGS and passes the string QueueMarkerEvent. This causes the
MarkerEvent to fire. In addition the MarkerEvent is passed the string /officeplan
/cmd=1 which is used by the marker event listener to verify that the marker event was
298
298
caused by double clicking a shape that it can recognize. Also, the RUNADDONWARGS
functions appends the string /doc=id /page=id /shape=sheet.id to the string passed to
the marker event. In our sample application this is used to get a reference to the specific
shape that was double-clicked.
4. The code trail starts with VisEventProc. This calls handleMarker, which gets a reference
to the shape that was double clicked and then calls onShapeDoubleClick.
onShapeDoubleClick displays the product detail form.
Create a custom Windows form to display shape product information in an adjacent

DataGrid control
The information displayed in the datagrid is kept in the ProductData.xml file. The master shape has
shape data fields defined, but contains no shape data except for the ProductID which is used to identify
the corresponding ProductListItem in the xml file.
The following code comes from the onAddProductInformation procedure which is called when a Visio
shape added event is fired.
// Update the total prices and the data grid
// add the information from the new shape.
TotalRetailPrice += productData.GetRetailPrice(productId);
TotalWholesalePrice +=
productData.GetWholesalePrice(productId);
productData.AddProduct(productId);
Setting TotalRetailPrice updates the retail price on the form.

Setting TotalWholesalePrice updates the wholesale price on the form.
The variable productId contains the value in the shape data cell ProductID from the shape. This is used
to associate the product id with the shape. The method productData.AddProduct updates the datagrid
with the data for this productID when a shape is added. The method productData.RemoveProduct
decrements the product information in the data grid with a shape is deleted.
The actual product data is maintained in the ProductData object after being loaded from the xml file.
299
299
The onShapeDoubleClick procedure and the onMenuProductInformationClicked procedure each display

the Product Detail form.
Save Visio drawings created by using the Drawing Control

After constructing a Visio drawing using the drawing control the user can save the drawing using the File
> Save command. This causes the click event for the menu item onMenuFileSaveClicked to execute.
This event procedure calls Utility.SaveDrawing to save the Visio drawing.
Open Visio drawings in the Drawing Control

Visio drawings can also be opened in the drawing control. This is done through the File > Open menu
and the onMenuFileOpenClicked event procedure. This sets the drawingControl.Src property to the
filename of the Visio drawing.
300
300
Lesson 2: Creating an application

The Office Plan sample provides an example of using the drawing control in a Windows forms
application. In this lesson we will explore more properties and features of the drawing control.
Lesson Objectives
Identify the features of the Visio drawing control and example use scenarios.
State best practices for using the Visio drawing control in Visio solutions.
Embed the Visio drawing control in a variety of host applications, including Microsoft
Windows Forms, Microsoft Visual Basic 6.0 forms, Microsoft Office documents, and
Microsoft Internet Explorer.
Use the properties of the Visio drawing control API.
Load Visio documents into the drawing control window and save changes.
Get a reference to the Visio Application object in order to work programmatically with
the Visio document.
Manage the display of the drawing surface.
Integrate the control with your host application user interface.
Deploy the Visio drawing control with your application.
Best Practices
Because the Visio drawing control is a programmable component, you can integrate your Visio solution
code directly into the host container application. Prior to Visio 2003, a developer writing a solution for
the Visio client application needed to package the solution code in a COM add-in, Visio solution library
(VSL), out-of-process executable, or in a Visual Basic for Applications (VBA) project in a document.
The Visio Drawing Control simplifies solution architecture and the development process by allowing
programming of the Visio Application object from the hosting application. A developer using the control
in a custom application (such as a C# application) or Internet Explorer should program against the Visio
object model directly in the host application, without separating the Visio logic into a COM add-in, VSL,
or executable. Calling a Visio COM add-in, VSL, or executable from the hosting application unnecessarily
complicates the debugging of the Visio integration.
301
301
However, if you would like to host the Visio control in a Microsoft Office System application other than
Visio, you will have to use a COM add-in. In this case, create a COM add-in for your host application
instead of for Visio. For example, if you plan to host your Visio control in a Microsoft Office Word 2003
document, create a Word COM add-in and access the Visio control through the Word add-in. Make sure
your COM add-in is targeted at the host since an Office host application will not load a Visio COM add-in
for the drawing control.
Porting existing code

When you are porting your code from an existing Visio client application solution to the Visio control,
include these design considerations in your planning.
Port VBA code. You must port all existing VBA code into a COM add-in, or more
preferably, your host application. You can keep most of your same algorithms and logic,
as long as it makes sense working within the control's SDI architecture.
Port an existing Visio solution COM add-in, executable, or VSL to the container
application. While it might be initially easier to simply use an existing COM add-in,
executable, or VSL with the host application, it is recommended that you integrate the
Visio drawing control programming directly with the host application. By taking the time
to port your code from your existing solution to your host application, you'll simplify
deployment of your solution, and streamline the development, debugging, and
maintenance process over time. You do not need to use a COM add-in unless you are
working with the control in another Office container.
Re-evaluate data storage in shapes. If your current Visio solution stores extensive data in
shapes, consider re-architecting data storage out of Visio shapes and into data structures
maintained or accessed by the host application. Visio can store as much data as you need,
but it often makes more sense to keep Visio as a presentation layer component and use
your host application as data storage or access to a data source. If the data is relatively
static, though, and used heavily for modifying the appearance and layout of shapes, it
makes more sense to store the information in the shape custom properties.
Think about event integration with the host application. Unlike a Visio client application
solution, the Visio drawing surface can respond to both user events and host application
events. Consider how you want the drawing surface to respond to events fired by the host
application, and how your host application needs to respond to events in the Visio
drawing surface.
Use marker events for COM add-ins. If you must use a COM add-in, you will need a way
to notify your COM add-in to respond to a user action in your document. Use the
302

302
QUEUEMARKER function in the ShapeSheet or a persistent event with the document to

queue a marker event to which your COM add-in responds.
The Controls SDI (single document interface)

When designing an application that uses the Visio drawing control, it's important to understand that the
Visio control supports a single document in a single window. The control's single document interface
(SDI) architecture results in the following considerations when designing the Visio drawing control
integration with your application:
Use multiple instances of the Visio drawing control to display multiple Visio documents
in your application. Unlike the Visio client application, which can display multiple
documents and windows at a time, the Visio drawing control can only display a single
document per instance of the control. If the developer wants to display multiple Visio
documents, the developer can embed multiple instances of the control in the application,
with each instance loading a separate Visio document.
Do not depend on VBA for programming logic. VBA is not included with the Visio drawing
control. As a result, documents loaded in the Visio drawing control do not execute any
VBA code associated with the document. The control's lack of a VBA run-time
environment prevents the distribution of legitimate code or malicious macros via
documents loaded by the Visio control. It also means that the user of an application
hosting the control will never see the Visio application's security dialog box warning about
macros in the document.
Use the Visio ShapeSheet programmatically. The control does not provide access to the
Visio ShapeSheet user interface, which is a separate window in the Visio application.
However, the ShapeSheet itself still exists for the Visio shapes and pages in the document
loaded in the Visio drawing control. You can still edit ShapeSheet cells for your Visio
document in the control using Visio Automation. For example, you can use the Cell
object's SRC property to add a double-click action for a Visio shape.
Note:
When programming the ShapeSheet for documents loaded in the control, you will
not be able to use the CALLTHIS function, which calls a VBA macro in the
document. The Visio drawing control does not execute VBA code, so any use of the
CALLTHIS function will fail silently. Instead, use mouse events or
QUEUEMARKEREVENT as was illustrated in the Office Plan sample program earlier.
303
303
Getting a reference to the Visio Application Object

You can access the Visio object model through the Visio drawing control's API. To get a reference to the
Visio Application object, use either the drawing control's Document or Window property.
For example, the following C# code shows how to get a reference to the Visio Application object using
the drawing control's Window property:
using Microsoft.Office.Interop.Visio;
private Microsoft.Office.Interop.Visio.Application application = null; application =
(Microsoft.Office.Interop.Visio.Application)
drawingControl.Window.Application;
You can do the same thing using the following Visual Basic 6.0 code:
Dim vsoApplication As Visio.Application
Set vsoApplication = DrawingControl.Window.Application
Loading a document
When the Visio drawing control is loaded, it displays a blank Visio drawing. If you want to display an
existing Visio document, the drawing control exposes an Src property for loading a document into the
control. You can then use the document's SaveAs method to save any changes.
Use the Visio drawing control's Src property to load a document into the control. For example, the
following C# example shows how to load a Visio drawing:
drawingControl.Src = "C:\\Drawing.vsd";
You can load any Visio file type using the Src property (for example, .vsd, .vdx, .vst, or .svg). The file can
be stored locally or on a remote file server.
Note:
To load a blank drawing into the drawing control when it initializes for the first
time, set the Src property to an empty string, but setting the Src property to an
empty string after a document has been loaded does not clear the contents of the
current document. Instead assign a blank drawing to the Src property or SelectAll
and delete to clear the contents from the current document.
304

304
Saving a document
The Visio control's Src property loads a copy of the file specified in the Src value. To persist the changes
in the control's document, you must save the Visio document using the SaveAs method. Alternatively,
you can persist changes in-stream. In both cases, however, you do not modify the original document
loaded by the Src property.
The control loads a copy of the file specified by the Src property. The file loaded through Src is not
opened for read/write operations, and therefore cannot be saved using the Save method. To save
changes to the document loaded in the Visio drawing control, call the document's SaveAs method. The
following C# example shows how you can use the drawing control Document property to call the SaveAs
method:
Visio.Document document = drawingControl.Document;
document.SaveAs("C:\\Drawing.vsd");
You cannot use the SaveAsEx method to save Visio 2003 documents to Visio 2002 format in the Visio
ActiveX control. To save a drawing loaded in the Visio drawing control to Visio 2002 format, launch an
invisible instance of Visio and call the SaveAsEx method in your Visio application instance, as
demonstrated in this Visual Basic 6.0 code that saves a Visio 2003 drawing into the Visio 2003 file
format:
Application.Documents(1).SaveAsEx("C:\Documents and Settings" & _
"\myusername\My Documents\Visio2002 file.vsd", visSaveAsWS + _
visSaveAsListInMRU)
Saving a Visio Document in the Control to Stream

Developers may want to persist changes to a drawing in the Visio drawing control without saving the
drawing to disk. For example, if a user modifies a Visio document in an embedded control in a Word
document, the changes are lost when the user forwards that Word document in an e-mail message.
When another user opens the document, the control loads the file specified by the Src property,
overwriting any modifications.
To persist changes in-stream to a Visio document in the control

1. Load the original document using the Visio control's Src property.
2. After the document loads, set the Src property to an empty string.
305

305
When the control is activated in its container document after the first initialization, the control displays
the last in-stream image rather than the original document specified by the Src property.
Note:
Persisting changes in-stream is an unsupported feature of the drawing control, but

the technique seems to work reliably.
Integrating the control with the host container

You can modify the appearance of the Visio drawing control in your application. By default, all Visio
toolbars are turned off and the stencil pane is not displayed. You can choose how the drawing control
surface appears by displaying scroll bars, rulers, or by changing the window background color.
The drawing control exposes a PageSizingBehavior property that determines how the page is displayed
within the drawing control window. You can choose to resize the page in relation to the drawing
control's size, or provide a view similar to Visio, showing a portion of the drawing page.
Because the control only supports a single window, you cannot access the ShapeSheet or windows such
as icon editor and master and group editing. The page and shape right-click menus are enabled by
default. The limited Visio UI for controlling shape behavior reflects the intent of the control to be tightly
integrated with the container application. The best approach for allowing users to modify shapes on a
document is to use a custom UI. However, if you want to use Visio menus and toolbars, the drawing
control does support menu and toolbar merging with the host application.
Most likely, your Visio drawing control application will be event-driven and respond to users clicking
buttons or menu items contained in the application. The drawing control also exposes Visio events, so
that you can respond to a user clicking within the control itself.
Managing the Drawing Surface Display

You can modify the appearance of the Visio drawing control's surface through the control's Window
property. For example, the following C# code hides the drawing control's scroll bars:
drawingControl.Window.ShowScrollBars = (short)
Visio.VisScrollbarStates.visScrollBarNeither;
306
306
This example hides both the horizontal and vertical scroll bars. Other possible values for the
VisScrollbarStates enumeration include visScrollBarBoth (display both scroll bars), visScrollBarHoriz
(display horizontal scroll bar), and visScrollBarVert (display vertical scroll bar).
By removing parts of the Visio UI, you can make the drawing control look more integrated within your
application. The following C# code hides the rulers:
drawingControl.Window.ShowRulers = 0;
You can also change the color of the window background to suit the color scheme of your application.
For example, the following C# code sets the window background color to solid red:
drawingControl.Window.BackgroundColor = (uint)
ColorTranslator.ToOle(Color.Red);
drawingControl.Window.BackgroundColorGradient = (uint)
ColorTranslator.ToOle(Color.Red);
In this example, the ColorTranslator class is used to convert a .NET color type into OLE_COLOR type,
which is how Visio Automation specifies colors.
Page sizing and zoom

Use the Visio drawing control's PageSizingBehavior property to resize the page with respect to the
control window. The default setting of this property (visNeverResizePages) provides a view similar to
that of Visio where a portion of the page is viewable within the window. The following C# code example
resizes the page to fit the control:
drawingControl.PageSizingBehavior =
Visio.VisPageSizingBehaviors.visResizePages;
When PageSizingBehavior is set to visResizePages, the page's shapes are not resized with respect to the
page. Shapes remain located relative to the coordinate system of the Visio page, which has its origin in
the lower left corner of the page. Sizing the page to fit within the control hides the page boundaries and
is useful in situations where the control is sized to the maximum extent of the drawing surface.
To rescale the entire page, including its shapes, within the drawing control window, set the Zoom
property through the control's Window property, as shown in the following C# example:
drawingControl.Window.Zoom = 2.0;
307

307
This code magnifies the window's contents by 200%. To take effect, the zoom settings must be made
after loading the document using the Src property.
To prevent the user from changing the zoom setting, set the ZoomLock property as shown in the
following C# example:
drawingControl.Window.ZoomLock = true;
You can set the extent to which Visio controls the zoom through the VisZoomBehavior property, which
can be accessed through the drawing control's Window or Document property. By default, the control
uses the current zoom setting for the document. If you want to be able to set the zoom to any level, not
just discrete settings such as 50% or 100%, without making any adjustments for the appearance, set the
VisZoomBehavior property to the VisZoomVisioExact value, as shown in the following C# example:
drawingControl.Window.ZoomBehavior = Visio.VisZoomBehavior.visZoomVisioExact;
Note:
You cannot resize the Visio drawing control in a Word document. If you resize the
drawing control and save the changes, the control will reset to its default size the
next time the Word document is opened.
Window management
You can "turn off" the Visio Shape Search window in the document's stencil pane using the Visio
ItemFromID property. To make the Shape Search window invisible in the stencil pane, set the property's
Visible property to false, such as:
Windows(1).ItemFromID(Visio.visWinIDShapeSearch).Visible = False
To expose the Shape Search window in the stencil pane, set the same value to True.
Each of the other View windows such as Size & Position Window and Shape Data Window are each
controlled separately.
308
308
Integrating menus and toolbars

The best practice when building an application using the Visio drawing control is to implement a custom
UI. If you want to display Visio menus and toolbars in your container application, set the drawing
control's NegotatiateToolbars and NegotiateMenus properties. The following C# code enables both
menu and toolbar merging:
drawingControl.NegotiateMenus = True;
drawingControl.NegotiateToolbars = True;
The best practice is to set both of these properties to the same value. The control will not support
independent negotiation of toolbars and menus.
The container application must support OLE menu merging in order to display Visio menus or toolbars.
For example, you can enable toolbar merging in a Word document. Within the Visual Basic project of the
Word document you can programmatically display Visio toolbars. The following example displays the
Layout & Routing toolbar.
vsoApplication.CommandBars("Layout & Routing").Visible = True
Important:
Important:
Do not attempt menu and toolbar merging with multiple active

instances of the ActiveX control. Multiple instances of the control share
a single underlying Visio Application object. You may get unexpected
results when trying to do menu merging with a single Application
object and multiple active instances of the control.
Do not merge menus and toolbars with the Internet Explorer user
interface. There are known issues with menu merging in Internet
Explorer (see the Microsoft Knowledge Base article 193098, PRB:
Unexpected Menu Merging Behavior in Internet Explorer).
309
309
Handling events
For easier use of Visio events, the Visio drawing control object exposes all Visio Window and Document
events. This allows developers to access the events directly from the control rather that going through
the Visio Document object.
Mouse and keyboard events are commonly used with Visio control programming. You can use mouse
events on the Visio drawing control to display custom Windows Forms and update data in your host
applications.
If you would like to "lock down" the Visio control's drawing surface and prevent end users from
modifying any content directly in the drawing, you can listen for all keyboard and mouse events and
"throw them away." If the hosting application "swallows" the mouse and keyboard events, the Visio
drawing surface won't respond to the user's typing and mouse-click actions.
Mouse and Keyboard Event Objects

Event objects created by the Visio AddAdvise method offer the best performance. You can use the Visio
mouse and keyboard events like any other Visio event with AddAdvise.
The following code sample demonstrates how to capture a mouse event using an event sink in Visual
Basic 6.0:
Implements Visio.IVisEventProc
Private Function IVisEventProc_VisEventProc( _
ByVal nEventCode As Integer, _
ByVal pSourceObj As Object, _
ByVal nEventID As Long, _
ByVal nEventSeqNum As Long, _
ByVal pSubjectObj As Object, _
ByVal vMoreInfo As Variant) As Variant
Dim strMessage As String
' Determine if mouse up event fired.
If nEventCode = visEvtCodeMouseUp Then
MsgBox ("MouseUp coordinates (" & pSubjectObj.X & ", " _
& pSubjectObj.Y & ")")
End If
310

310
End Function
The following code sample demonstrates how to create an event object for the mouse event using the
AddAdvise method.
Private mEventSink As clsEventSink
Dim vsoMouseUpEvent As Visio.Event
Dim vsoWindowEvents As Visio.EventList
Set mEventSink = New clsEventSink
Set vsoWindowEvents = DrawingControl1.Window.EventList
Set vsoMouseUpEvent = vsoWindowEvents.AddAdvise( _
visEvtCodeMouseUp, mEventSink, "", "Mouse up...")
Delegates for Mouse-Click Events

Although using event objects created with AddAdvise provides the best performance, you can also
define a C# delegate in a Windows Form to handle mouse-click events within the drawing control
window, as shown here:
this.drawingControl.MouseUpEvent += new
AxMicrosoft.Office.Interop.VisOcx.EVisOcx_MouseUpEventHandler(
this.drawingControl_MouseUpEvent);
The event handler would then have the following signature:

private void drawingControl_MouseUpEvent( object sender,
AxVisOcx.EVisOcx_MouseUpEvent eventData)
Note:
Examples of using delegates is illustrated in the Office Plan sample from the Visio
2010 SDK.
Mouse Events for Shapes

Visio mouse events are exposed on Page and Window objects. To locate a particular shape in a page or
window on which a user clicks, developers must use the Visio SpatialSearch method. The following C#
code passes in the x- and y- coordinates for the click event on the window, sets Visio constants that
311
311
dictate how to set up the selection object, and defines a small tolerance in which to search around the xand y- coordinates.
MySelection = Window.SpatialSearch(x, y, visSpatialContainedIn, 0.001,
visSpatialFrontToBack)
If the tolerance is set to a very small unit relative to the size of the shape, the selection object returned
by the SpatialSearch method will only contain one shape, the one that the end user clicked on in the
window.
Using the Visio Control with the Internet Explorer Browser

Control
Even though you cannot embed the Visio drawing control directly into another ActiveX control, you can
still use the Visio drawing control with applications that depend on the Internet Explorer browser
control.
Internet Explorer 5.0 or later provides an excellent host container for the Visio drawing control, allowing
developers to write script against the Visio object model in Microsoft Visual Basic Scripting Edition
(VBScript) or ECMAScript as defined by the specification of the European Computer Manufacturers
Association, such as JScript or JavaScript.
To integrate the Visio drawing control with an Internet Explorer browser control-based application, do
the following:
1. Add a link in your Internet Explorer browser control that launches a new Internet Explorer
process with its own window.
2. Embed the Visio drawing control in the new Internet Explorer window for the new
Internet Explorer process.
3. Program against the Visio drawing control using your preferred scripting language.
312
312
Lab 3.8: Using the Visio Drawing Control

The ScheduleBuilder solution from the previous labs has been ported to a Visual Studio 2005 application
that uses the Visio 2010 Drawing Control.
During this lab, you will make modifications to the application to enrich the functionality presented.
Before You Begin

Participants should have completed the lessons within this module before completing this
lab.
Visio 2010 installed and configured.
Visual Studio 2005 installed and configured.
All files from folder Labs\Vol3\Schedule Builder Start

o
These files present the starting point for the lab
All files from folder Labs\Vol3\Schedule Builder Finished

o
These files present a completed solution for the lab
What You Will Learn

Set the document Src property
Control windows in the Visio environment using the drawing control
Add menus and call procedures in the container application
Save the document to a Visio file
313
313
Exercise 4: Set the Src property of the document and display

the External Data window
Scenario
Depending on where you placed the Lab files on your machine, you will likely get an error when you first
start the application because the path to the Visio drawing being loaded is incorrect. You will fix that in
this step.
Tasks
1. Open the Visual Studio 2005 project Labs\Schedule Builder Start\ScheduleBuilder.sln
2. Choose Debug > Start Debugging. The program will stop with an error when trying to set
the Src property of the document.
3. Correct the path and continue.
4. The External Data window is turned off. Find the code that keeps the window off and
make it visible.
Exercise 2: Add menus to place and delete Sections

Scenario
Add menus to access functions to Delete Selection Shapes, Drop Section Shapes, and Place Selected
Shapes. These were all macros in the VBA version of this solution and have been ported to the Windows
Form application containing the drawing control.
Tasks
1. Display Form1.vb in design mode.
2. Add a second top level menu item call ScheduleBuilder
3. Add 3 menu items under ScheduleBuilder
a. Delete Section Shapes
b. Drop Section Shapes
c. Place Selected Shapes
314
4. Display Form1.vb (code view)
314
a. In the objects drop down list at the top of the form choose
DropSectionShapesToolStripMenuItem
b. In the events drop down choose the Click event. This will stub in the event
procedure for this menu
c. Add the code
Document.DropSectionShapes()
This calls the DropSectionShapes procedure in the module ScheduleDocument.vb

5. Add the Click event procedures for the other two menus. The procedures to call are in
ScheduleDocument.vb
6. Try out the code. You will find that the Delete Section Shapes does not delete the shapes
properly. Fix this error.
Exercise 3: Add SaveAs menu

Scenario
To save the drawing you will need to add a SaveAs menu.
Tasks
1. Display Form1.vb in design mode.
2. Under the File menu insert a new menu before Exit and name it SaveAs
3. In the code view of the form add the Click event for this menu
4. Add the code for the SaveAs. Look back at the sample code in this module for an
example.
315
315
Additional Resources Drawing Control

Programming with the Microsoft Office Visio 2003 ActiveX Control
Learn to integrate the Microsoft Office Visio 2003 ActiveX Control, also referred to as the Visio
drawing control, into applications. Review best practices and how to use the Visio drawing control
programmatically. (24 printed pages)
Dev Luv: Top Ten Things to Know When Using the Visio 2003 ActiveX Control
Mai-lan's Visio Blog
This is a good summary blog on common things that can trip you up when using the drawing control.
http://blogs.msdn.com/mailant/archive/2004/09/24/233928.aspx
Drawing Visio Shapes in the Visio ActiveX Control using C# and .NET
A sample program from Mike Gold to help you get started using the ActiveX Drawing Control.
http://www.csharpcorner.com/UploadFile/mgold/VisioInDotNet12032006222024PM/VisioInDotNet.aspx
About Using the Visio Drawing Control in Your Application [Visio 2003 SDK
Documentation]
Using this control, you can embed the full functionality of the Visio drawing surface into your
applications. You can take advantage of the full Visio object model (API) and you can pick the aspects of
the Visio user interface you want to expose to better integrate Visio seamlessly into the user interface of
your application.
316
316
Integrating Menus and Toolbars in Visio 2003 Drawing Control Applications

You can choose from several approaches when integrating Visio menus and toolbars in your applications
that host the Visio drawing control. This article walks you through a sample application demonstrating
these approaches, including the use of the IOleCommandTarget interface. (13 printed pages)
Visio 2007: Bug in Drawing Control

Bill Morein's Weblog
There is a bug in the Visio 2007 Drawing Control such that if you have the SRC property set and add a
new page (either through the UI or through code), Visio crashes.
http://blogs.msdn.com/wmorein/archive/2007/01/26/visio-2007-bug-in-drawing-control.aspx
Host an Interactive Visio Drawing Surface in .NET Custom Clients

Microsoft Office Visio 2003 introduces a new drawing component that allows you to embed an
interactive drawing surface into your application's user interface. You can drive the Visio drawing
component from events in your host application or with data from a Web Service and an ADO.NET data
adapter. The Visio drawing component supports the rich Visio application programming model, giving
you control over how graphics are used and displayed on the drawing surface. This article explains how
to embed the Visio drawing component into a C#-based Windows Forms client app that retrieves data
from the Fabrikam 2.0 Web Service.
http://msdn.microsoft.com/msdnmag/issues/03/12/Visio2003/
317
317
Review Visio Drawing Control

Questions
1. True or False. You can embed the Visio drawing control into an Excel VBA form.
2. What is the key difference in working with Visio embedded as an OLE object versus with
the Visio drawing control embedded in a Windows form.
3. True or False. The Visio control is installed with the Visio application setup program and
requires the Visio client application to initialize.
4. What are the steps required to upgrade an application currently using the Visio 2003
Drawing Control to use the Visio 2007 Drawing Control?
5. When using a Visio 2010 Drawing Control in a Windows Forms application the developer
should:
a. Program directly against the Visio object model
b. Create a COM add-in for the host application and have the COM add-in listen for
Visio events and then react to these events
c. Host the drawing control in Visio and use VBA to create any necessary forms so
that you have access to the Visio user interface
d. Any of these methods will work
6. When using a Visio 2010 Drawing Control in a Windows Forms application, how can the
Windows application be made to listen to events triggered in Visio?
7. A Visio drawing can be displayed in the drawing control by assigning the Src property of
the control. What happens to any VBA code that is a part of that document.
8. True or False. Since the drawing control cannot display the ShapeSheet window, you
cannot program against the ShapeSheet in application that use the drawing control.
9. True or False. There can only be a single document displayed in an application using the
drawing control.
10. What two properties of the drawing control can be used to get a reference to the Visio
Application object?
11. What property of the drawing control must be set in order to display an existing Visio
drawing in the drawing control?
12. True or False. When editing a drawing in an application using the drawing control you are
working directly on that document and can update the document with the Save method.
13. True or False. The Shape Data window cannot be displayed in an application hosting the
Visio drawing control.
318
318
14. True or False. Any host application can display Visio menus and toolbars if the
NegotiateMenus and NegotiateToolbars properties of the drawing control are set to True.
15. What Visio method can be combined with mouse events by the host application to locate
a shape on the drawing surface.
Answers
1. True. You cannot embed the drawing control into a Visio VBA form, but you can embed
into VBA forms of other applications.
2. As an embedded OLE object you are working with Visios own user interface. In working
with the drawing control on a form there is no Visio UI. The developer must build the
interface that is presented to the user.
3. True
4. The interfaces are the same so just rebuild the application.
5. a.
6. In the host application create an event sink and define the Visio events that are to be
listened for.
7. The drawing control does not support VBA. Any VBA code that is in the document cannot
execute.
8. False. Even though the ShapeSheet window cannot be displayed, you still have access to
the Visio object model and therefore can get and set cells in the ShapeSheet.
9. True. Only a single document can be displayed because of the drawing controls single
document interface.
10. Document and Window properties.
11. The Src property.
12. False. You are always working on a copy of the document when using the drawing control
and must use the SaveAs method to save changes to the drawing.
13. False. The ShapeSheet an icon editing windows cannot be displayed, but the viewing
windows can be controlled by the host application.
14. False. The host application must also support OLE menu merging.
15. SpatialSearch.
319
319
Adding the Office Fluent UI to an existing Addin

Microsoft Office 2007 introduced a new user interface called the Fluent UI or Ribbon interface; however
this new interface was not adopted in all of the Office 2007 applications. Visio 2007 and other Office
2007 applications continued to use the older CommandBars interface.
Now with the release of Microsoft Visio 2010, the Ribbon interface has been adopted allowing Visio
solution developers to build rich Ribbon based interfaces for their Visio based solutions.
This adoption does pose some issues for the Visio solution developer as this is yet another user interface
technology that is available via the Visio API, giving the Visio solution developer three choices, 1)
UIObject 2) CommandBars 3) Ribbon. The UIObject is still available however it is recommened that
solution developer not use this API as it could be deprecated in future releases. This is also the case for
CommandBars as future development investments will now be focused on the Ribbon interface.
Visio solution developers that are creating new solutions specifically targeted for Visio 2010 should
create their UI using the new Ribbon UI. Visio solution developers that currently maintain Visio
2003/2007 based solutions have a choice to make, migrate their solution to target Visio 2010 and create
their UI using the Ribbons or upgrade their solution to target both Visio 2007 and Visio 2010 and
manage both a CommandBars based UI and a new Ribbon based UI.
Figure 1 the Add-Ins tab is a catch all for UIObject and CommandBar based UIs
This article will walk you thru the process of creating a Ribbon based interface for an existing Visio 2007
add-in, providing best practices for Ribbon item state management as well as best practices for
supporting both CommandBar and Ribbon based UIs in one add-in.
320
320
Getting started
As shown in Figure 1, any UI modifications made using the UIObject APIs or the CommandBar APIs are
aggregated within a new tab on the Visio 2010 ribbon named Add-Ins. Because both the UIObject and
the CommandBars support the idea of Menus and Toolbars you see separate ribbon groups, one for
each menu and toolbar created thru these legacy APIs. This is good news for both users and solution
developers as existing add-ins are still compatible and accessible with the new Ribbon interface.
The sample projects for this section are written in C# (Visual Studio 2008) for Visio 2007 using the Visual
Studio Tools for Office (VSTO) 3.0 framework and runtime. The following software is required for this
scenario:
Visual Studio 2008

VSTO 3.0 (installed with Visual Studio 2008)
Visio 2007 with .NET Programmability Support installed (PIA)
VSTO is the preferred and supported framework for building add-ins for all Office applications. Prior to
the release of VSTO, Office add-ins were developed as COM components implementing the
IDExtensibility2 interface, commonly referred to as Shared Add-ins from the managed code world.
Either framework supports Ribbon extensibility by simply implementing the IRibbonExtensibility
interface. It is up to the host application to call the implemented interface in order to retrieve Ribbon
customizations.
Updating References
For the purpose of this article it is not necessary to reference the Visio 2010 type library. Existing Visio
2007 add-ins can continue to reference the Visio 2007 type library in order to support both Visio 2007
and Visio 2010 as well as provide a rich Ribbon based interface when running in Visio 2010.
Preparing the add-in for Ribbon support

In order for your add-in to support the new Ribbon interface when loaded by Visio 2010, your add-in
must be updated to support the IRibbonExtensibility interface. This interface is defined in the Office PIA.
Add this reference to your project if it does not already exist.
From the Add Reference menu select Office, 12.0.0.0 from the .NET tab. This is the Primary Interop
Assembly for Office Core which provides the interfaces for IRibbonExtensibility as well as the APIs and
321
321
interfaces for CommandBars, so if you are using CommandBars you probably already have this reference
in your project.
Figure 2 - Adding a reference to Office.dll
After adding the reference you will need to implement the IRibbonExtensibility interface in order to
provide the host application with an instance of an object that provides your ribbon implementation.
For a VSTO based add-in start by creating a separate class that will implement the IRibbonExtensibility
interface. I prefer to name this class Ribbon (in a separate file, Ribbon.cs). Here is a sample definition of
this class:
using Office = Microsoft.Office.Core;
[ComVisible(true)]
public class Ribbon : Office.IRibbonExtensibility
{}
A single method needs to be implemented from the IRibbonExtensibility interface:

#region IRibbonExtensibility Members
public string GetCustomUI(string RibbonID)
{
return GetResourceText("DataLinkedOrgChart.Ribbon.xml");
}
#endregion
The GetCustomUI method is used to return the XML that defines your Ribbon to the host application.
This xml is compiled into the add-in as a resource which is retrieved by the GetResourceText method.
Using this XML the host application generates the Ribbon and displays it to the user. We will generate
the XML for the ribbon later in this article.
Application level Ribbon

In order to create a single Application-Level Ribbon you need to override the CreateRibbonExtensibility
method. This method is called by the VSTO runtime to retrieve an instance of your class that implements
322
322
the IRibbonExtensibility interface, passing it to the host application which will then make the call to the
GetRibbonUI method.
protected override Microsoft.Office.Core.IRibbonExtensibility
CreateRibbonExtensibilityObject()
{
// create a new instance of our Ribbon
this.ribbon = new Ribbon();
// return the ribbon to the VSTO runtime caller
return this.ribbon;
}
As you can see this method simply creates a new instance of your Ribbon class and returns it to the
caller.
Document level Ribbon

To implement a Document-Level Ribbon you do not override the CreateRibbonExtensibility method as
described above as you will need to create an instance of your Ribbon for each document on an as
needed basis.
RegisterRibbonX and UnRegisterRibbonX are two new methods on the Visio.Application class that
allow you to attach and detach a Ribbon to a specific open document.
To create a Ribbon for a specific document you would create a new instance of the Ribbon class and
pass that along with the Visio.Documentinstance that you want to attach it to as parameters to the
RegisterRibbonXmethod.
// add our UI for this document
Globals.ThisAddIn.Application.RegisterRibbonX(
ribbon,
visioDocument,
Visio.VisRibbonXModes.visRXModeDrawing,
"My Ribbon");
It is important to perform cleanup operations as documents close so you should manage each instance
of the Ribbon class that you create and as documents are closed you should call the UnRegisterRibbonX
method.
323
323
Globals.ThisAddIn.Application.UnregisterRibbonX( this.ribbon, this.visioDocument);
Note for Shared add-ins

If you are using the Shared add-in framework you simply implement the IRibbonExtensibility interface
directly on the Connect class and provide the implementation for the GetCustomUI method as
described above.
public class Connect : Object, Extensibility.IDTExtensibility2,
Microsoft.Office.Core.IRibbonExtensibility
Creating the Ribbon

If you have created add-ins for Word or Excel you know that the add-in project template in Visual studio
provides a very easy mechanism for creating a Ribbon using the Ribbon Designer. From the Add New
Item dialog select the Ribbon Designer
Figure 3 - Adding the Ribbon (Visual Designer) to your project
And you will be able to visual design the layout of your ribbon using ribbon controls just as you would
with a WinForm.
324
324
Figure 4 - Using the Visual Designer for the Ribbon
The problem is that the project template that is used to create add-ins for Visio 2007 knows that Visio
does not support the Ribbon interface so this option is not available to you. You can skip the designer
and just write the XML from scratch but it is much easier to work with the designer and then have the
designer generate the XML when you have your ribbon laid out. To do this, create a new add-in project
for Word 2007. Then from the Add New Item dialog choose the Ribbon Designer. Once the new Ribbon
Designer is added to this temporary project you can copy the necessary files to your Visio add-in project
and discard this temporary Word add-in project.
To copy the ribbon designer files to your Visio add-in project:
1. Close and save changes to the temporary Word add-in project/solution.
2. From your Visio add-in project, choose the Add Existing Items menu and navigate to the
temporary Word add-in project folder, selecting the following files:
a. RibbonDesign.cs
b. RibbonDesign.designer.cs
c. RibbonDesign.resx
This will copy the ribbon designer files to your Visio add-in project. Once these files are added to your
Visio add-in project you can continue to the next step which would be to actually design the ribbon.
1. Double-click the RibbonDesigner.cs item in the Project Explorer window. This will open the
Visual Designer for the ribbon as shown in Figure 4
Once you are happy with the design and layout of your ribbon it is time to generate the XML that will be
embedded as a resource in your project. This is the XML that is passed to the host application from the
GetCustomUI method described above.
To generate the XML from the Visual Designer:
2. Open the Visual Designer as shown in Figure 4 above.
3. Right-click on the ribbon and from the context menu choose Export Ribbon to XML
325
325
Figure 5 - Export Ribbon to XML
This will add a new file to your Visio add-in project named Ribbon.xml. If you open this XML file in the
editor you will see that it is a very simple schema.
326
326
Figure 6 View of XML generated by the Visual Designer
After the Ribbon.xml file is generated and added to the project, verify that the Build Action for this file is
set to Embedded Resource or the call to GetCustomUI will fail to return the XML.
Figure 7 - Build Action set to Embedded Resource
Tip:
If you want to duplicate built in buttons on your Ribbon, such as the Refresh All
button, you can use the idMso attribute in your XML.
<button idMso="DataRefreshAllDialog" />
327
327
Make sure to set the Build Actions for the Ribbon Designer files to None. It you compile these files into
your project they could conflict with the Ribbon class. Make sure to set it for all three designer files:
Tip:
These files can be removed from your project once you are finished with the design
of your Ribbon or they can be left for future design changes.
Callbacks
At this point you could actually compile and run your add-in and you should see your ribbon however
the ribbon controls will not do anything (unless linked to build in commands).
In order for the ribbon controls to perform custom actions you need to implement callback methods on
the Ribbon class that can be called by the host application or the ribbon controls. These callbacks are
assigned to ribbon controls using attributes in the ribbon xml.
Figure 8 - Sample XML showing callback attributes
The onAction callback should be defined as follows:

public void OnAction(
Office.IRibbonControl control)
{
switch (control.Id)
{
case "buttonCreate":
{
// do any work necessary for the selected control
break;
}
// define a case for each button that needs a handler
328

328
}
}
Manage Ribbon control state

In addition to creating a Ribbon with controls that perform actions within your add-in, you will also want
to manage the state of the controls on your Ribbon so that users have access to each control when
appropriate.
When the host application receives the XML from the GetCustomUI method it generates a new Ribbon
tab. We can get a handle to this Ribbon when the host application creates it if we provide a callback to
the onLoad attribute of the Ribbon XML.
Callback defined in XML
Figure 9 - Sample XML showing definition for onLoad callback
Callback defined in the Ribbon class

public void Ribbon_Load(Office.IRibbonUI ribbonUI)
{
// hold on to the instance of our ribbon
this.ribbon = ribbonUI;
if (Globals.ThisAddIn.Application != null)
{
VisioEvents_Connect();
}
}
Not only do we get the instance of the Ribbon that was created by the host application but in this
callback we will connect to a few Visio events so that we can determine when Ribbon control states
need to be updated.
329
329
private void VisioEvents_Connect()

{
if (Globals.ThisAddIn.Application != null)
{
Globals.ThisAddIn.Application.AppObjActivated += new
Microsoft.Office.Interop.Visio.EApplication_AppObjActivatedEventHandler(Application_A
ppObjActivated);
Globals.ThisAddIn.Application.AfterModal += new
Microsoft.Office.Interop.Visio.EApplication_AfterModalEventHandler(Application_AfterM
odal);
Globals.ThisAddIn.Application.WindowOpened += new
Microsoft.Office.Interop.Visio.EApplication_WindowOpenedEventHandler(Application_Wind
owOpened);
Globals.ThisAddIn.Application.WindowActivated += new
Microsoft.Office.Interop.Visio.EApplication_WindowActivatedEventHandler(Application_W
indowActivated);
Globals.ThisAddIn.Application.WindowChanged += new
Microsoft.Office.Interop.Visio.EApplication_WindowChangedEventHandler(Application_Win
dowChanged);
Globals.ThisAddIn.Application.BeforeWindowClosed += new
Microsoft.Office.Interop.Visio.EApplication_BeforeWindowClosedEventHandler(Applicatio
n_BeforeWindowClosed);
}
}
Within each Visio event handler we can call the Invalidate method on our Ribbon to notify the Ribbon
that it needs to get the state for each control.
void Application_WindowChanged(Microsoft.Office.Interop.Visio.Window Window)
{
this.ribbon.Invalidate();
}
However, for each control to update its new state each control must have a callback defined that
returns true for Enabled or false for Disabled.
330
330
Callback defined in XML
Figure 10 - Sample XML showing getEnabled callback
getEnabled defined in Ribbon class

public bool GetEnabled(
Microsoft.Office.Core.IRibbonControl control)
{
bool retVal = false; // default to false until we prove this enabled
switch (control.Id)
{
case "buttonCreate":
{
// create is always available
retVal = true;
break;
}
case "buttonGenerate":
{
// only enabled if the active document is our document
retVal =
this.IsOurDocument(Globals.ThisAddIn.Application.ActiveDocument);
break;
}
// additional cases for all controls that have state
}
return retVal;
}
After Invalidate is called, each Ribbon control that has its getEnabled attribute set will execute its
callback and set its state based on the return value of the callback. At this point you can test the
ActiveDocument or the Selection to see if the control should be enabled or disabled.
331
331
Additional callbacks
getImage
If you do not find an image from Office (ex. imageMso="Refresh") to use on your control you
can provide your own. The getImage attribute can be set on each control so that it will retrieve
its own image from the specified callback in your add-in. As you can see in the sample below
you can easily add your image to your add-in project as a resource and then return it to the
caller based on the control.Id property.
public System.Drawing.Bitmap GetImage(
Microsoft.Office.Core.IRibbonControl control)
{
switch (control.Id)
{
case "buttonApplyDataGraphics":
{
return Properties.Resources.OperationsManagerProductIcon_32;
}
}
// we should not get here for these buttons
return null;
}
CommandBars and Ribbon

After implementing the Ribbon as described above there is only one more step you should take, add a
conditional statement around your existing UI code so that you do not build your legacy UI using
CommandBars if the user is running Visio 2010. To do this add this simple check when initializing your
add-in:
if (this.Application.TypelibMinorVersion <= 12)
{
// code to provide CommandBars
}
else
{
// do nothing, VSTO will call into the defined
332

332
// IRibbonExtensibility interface
}
With this check in place your add-in will now run in both Visio 2007 and Visio 2010, providing the user
with the best UI experience available to each.
Sample Code
There are four Visual Studio projects included with this training which demonstrate the above concepts.
Try it! Creating Office Fluent UI for Visio Addins

1. Using Visual Studio 2008 open the project in <install>\Samples\Office Fluent UI\ Basic Ribbon
a. Review the example
2. Using Visual Studio 2008 open the project in <install>\Samples\Office Fluent UI\ Enhanced
Ribbon
3. Using Visual Studio 2008 open the project in <install>\Samples\Office Fluent UI\
Doc Level
Ribbon
4. Using Visual Studio 2008 open the project in <install>\Samples\Office Fluent UI\ Command Bars
Only
333
333

Visio 2010 Developer Training 03 - Programming With The Visio Object Model

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Visio 2010 Developer Training 03 - Programming With The Visio Object Model

Uploaded by

Copyright:

Available Formats

Microsoft Visio 2010 Developer

Microsoft Visio 2010 Developer Training

Review: Introduction to Automation.......................................................................................................................52

Automation and Visio Technology .............................................................................................................. 53

Generating Drawings .................................................................................................................................. 78

Adding Data to Shapes ............................................................................................................................................99

Getting Data From Drawings..................................................................................................................... 104

Managing Events ....................................................................................................................................... 135

Use Formulas Over Code .......................................................................................................................................145

Automating Data Graphics ........................................................................................................................ 165

Microsoft Visio 2010 Developer Training

Managing External Data Sets .................................................................................................................... 214

Visio Software Development Kit (SDK) ..................................................................................................... 251

Visio Drawing Control ............................................................................................................................... 289

Adding the Office Fluent UI to an existing Add-in .................................................................................... 320

Preparing the add-in for Ribbon support ..........................................................................................................321

Event Driven vs. Procedure Based Programming

Visual Basic Editor

Figure 1: The Visual Basic Editor window

Demonstration: Visual Basic Editor

Microsoft Visio 2010 Developer Training

NULL Data Type

Numeric Data Types

Integer Whole numbers within the range of -32,768 to 32,767.

String Data Type

Will Produce 1214

Date/Time Data Types

Boolean Data Types

Object Data Types

Using Hungarian Notation

Microsoft Visio 2010 Developer Training

Exercise 1 Variable Manipulation

Microsoft Visio 2010 Developer Training

Dim intNumber3 As Integer

Exercise 2 String Concatenation

Microsoft Visio 2010 Developer Training

The underscore character at the end of the statement assigning a value to

Data type conversions and variable scope

Microsoft Visio 2010 Developer Training

Exercise 3 Variable Scope

2. Add the following code to the module.

Microsoft Visio 2010 Developer Training

Looping statements execute a portion of code again and again

Microsoft Visio 2010 Developer Training

'code for Write a letter

Then you must be bored.

Go out and play.

Microsoft Visio 2010 Developer Training

For Each Next

varVariable can either be the name of an array, or a collection of objects.

Microsoft Visio 2010 Developer Training

VBA Primer Conclusion

Programming a Server's Objects

Access to the properties and methods of the object is

The object always resides with its source.

Try it! TechEd

VBE Tools Menu

Review: Introduction to Automation

Automation and Visio Technology

Automation and Visio Technology

The Visio Object Model

Working with Objects, Methods, and Properties

When and How to Run Your Program