When programming in Visio it is important to realize that many Visio objects have more than one name. Objects such as Pages, Masters, Cells and others have a local name and a universal name. Why two names? To address the problems that arise when combining the needs of localization (translating strings into multiple languages) with the needs of solution development (having a constant way to refer to things).
The local name is a friendly name that is displayed in the Visio user interface. For Visio’s own content, this is a string translated for the product sku of Visio (i.e. German strings in German Visio). Users have the ability to rename Page and Master and Cell objects, and that changes the local name. Local names allow users to see things in a language that makes sense to them.
The universal name is hidden from the user interface and can only be updated through automation. This keeps a universal name consistent across product versions and user edits. A constant name allows solution developers to refer to objects by an identifier that makes sense to them. This identifier works no matter what is displayed for the local name.
When working with Visio objects, developers should always use universal names to reference their objects. This advice applies to more than names. A number of properties and methods in the Visio API have universal syntax equivalents. If you find a property and notice the same property exists but ending in a ‘U’, use the universal property. A classic example is to use the FormulaU property to get and set formulas instead of Formula.
There is one special case where setting the local name of an object will automatically update the universal name to match. When the name of an object is changed the first time, both the Name and NameU properties are set to the new name. All subsequent changes to Name do not affect the NameU property. The sample code below illustrates this behavior.
Public Sub NameUDemo()
'Create a new master shape
Dim vsoMaster As Visio.Master
Set vsoMaster = ActiveDocument.Masters.Add
'Check the default Name and NameU property
Debug.Print "Initial Name/NameU:", vsoMaster.Name, vsoMaster.NameU
'Set the name of the master for the first time
vsoMaster.Name = "Apple"
'Check the current Name and NameU property
Debug.Print "Current Name/NameU:", vsoMaster.Name, vsoMaster.NameU
'Set the name of the master for the second time
vsoMaster.Name = "Banana"
'Check the current Name and NameU property
Debug.Print "Current Name/NameU:", vsoMaster.Name, vsoMaster.NameU
End Sub
Output:
Initial Name/NameU: Master.0 Master.0
Current Name/NameU: Apple Apple
Current Name/NameU: Banana Apple