Using Universal Names and Syntax to Localize Visio 2007 Solutions

Summary:   Learn to use universal names and syntax in your code to localize custom Microsoft Office Visio 2007 solutions easily. Learn to access stencils, templates, and add-ons across differing locales. (13 printed pages)

Saul Candib, Microsoft Corporation

October 2007

Applies to:   2007 Microsoft Office System, Microsoft Office Visio 2007

Contents

• Overview of Localizing Visio Solutions

• Local and Universal Names

• Accessing Cells in the ShapeSheet Spreadsheet

• Accessing Add-Ons

• Accessing Templates and Stencils

• Universal Syntax

• Using Universal Separators

• Using Universal Units

• Using Universal Date, Time, and Currency Formatting

• Using Universal Functions

• Visio 2007 Available Languages

• Conclusion

• Additional Resources

Overview of Localizing Visio Solutions

Microsoft Office Visio 2007 is available in multiple languages for international markets. When you develop custom solutions for Visio 2007, determine whether you want to adapt or localize your solutions to work with multiple languages. Localization techniques, such as using Visio 2007 universal object names and universal syntax, save time and money.

Local and Universal Names

The names of objects in the Visio 2007 user interface (UI), such as masters, master shortcuts, pages, styles, and layers, change with each language version. Referring to these UI object names for multiple languages in your code makes localizing your solutions more time-consuming because you must change each name reference for each language version that the solution supports.

Shape, Master, MasterShortcut, Page, Style, Layer, Row, and Cell objects have both local and universal names, so you do not have to refer to UI names in your solution code. Local names are the names that appear in the UI, and they change to reflect the language version that Visio 2007 is running. Universal names remain constant. They do not change with different language versions of Visio 2007, and they cannot be changed in the UI. Refer to Visio Shape, Master, MasterShortcut, Page, Style, Layer, Row, and Cell objects by their universal names in your solution code to avoid changing the code for each supported language.

The exception to this language automation is the Visio ShapeSheet spreadsheet UI. ShapeSheet sections, rows, and cells display universal names only—not local names. If you change a row name or cell name in the ShapeSheet UI, you change its universal name.

Using Universal Names of Objects That Are Included with Visio 2007

The universal names of all masters, master shortcuts, pages, styles, and layers that are included with Visio 2007 are US English names. In the US English version of Visio 2007, the universal and local names of these objects are identical—unless you change the universal name in your solution code or change the local name in the UI.

The universal names of the ShapeSheet sections, rows, and cells for these objects are also US English names. In the US English version of Visio 2007, the universal and local names of these objects are identical.

Using Universal Names of Objects That You Create

When you create a Shape, Master, MasterShortcut, Page, Style, Layer, Row, or Cell object, either in the UI or in your solution code, and you name it for the first time, the local name and the universal name are identical. Later, if you change the name in the UI or use a different language version of Visio 2007, only the local name changes.

For example, if you insert a row named User.ABC in the User-defined Cells section in the ShapeSheet spreadsheet, User.ABC is the row's universal name and its local name. If you change the row name in the UI to User.ABCDE, the row's universal name is still User.ABC; however, the row's local name is User.ABCDE.

Getting and Setting Universal Names of Objects Programmatically

In the Automation interface, you can get a Shape, Master, MasterShortcut, Page, Style, Layer, Row, or Cell object by its universal name, or set the object's universal name, by using Visio 2007 properties or methods that have a "U" suffix. Table 1 describes these properties and methods.

For example, if you want to verify the universal name of the current Layer object, you can use the NameU property to get the universal name of the current Layer object, as shown in the following example.

Debug.Print "The current layerObj name is """ & layerObj.NameU & "."""

Table 1. Properties and methods that reference objects by their universal names

Property or Method	Objects	Description
CellExistsU property	Shape and Style	Determines whether a cell exists by using its universal name.
CellsRowIndexU property	Shape	Gets a cell's row index by using its universal name.
CellsU property	Shape and Style	Gets a cell by using its universal name.
CellU property	Row	Gets a cell by using its universal name.
ItemU property	Addon, Hyperlink, Layers, Masters, MasterShortcuts, Pages, Shapes, and Styles	Gets an object from a collection by using its universal name.
Name property Note This is the only property that is used to get a universal name that does not end with "U."	Cell	Gets the universal name of a cell. Note Use the LocalName property to get or set the local name of a cell. For more information about accessing cells, see Accessing Cells in the ShapeSheet Spreadsheet later in this article.
NameU property	Addon, Hyperlink, Layer, Master, MasterShortcut, Page, Row, Shape, and Style	Gets or sets an object's universal name.
RowNameU property	Cell	Gets or sets a row's universal name.
DropManyU method	Page, Master, and Shape	Creates one or more new Shape objects on a page, in a master, or in a group, by using universal names to identify the shapes. Returns an array of the IDs for the Shape objects that it creates.
DropManyLinkedU method	Page	Creates multiple new Shape objects on the drawing page that are linked to multiple data rows in a data recordset. Returns the number of shape instances created and an array of IDs for those shapes.
GetNamesU method	Addons, Masters, MasterShortcuts, Pages, and Styles	Gets the universal names of all items in a collection.
GetThemeNamesU method	Document	Gets an array of universal names of themes contained in a document.

For more information about using these properties and methods and associated example code, see the Visio 2007 Software Development Kit. Or, in Office Visio 2007, on the Help menu, click Developer Reference.

Accessing Cells in the ShapeSheet Spreadsheet

When you develop solutions that support multiple languages, you should access cells by using their universal names. However, the method you use to do this depends on the type of section and row that the cell is in. The sections are described in the following paragraphs:

• Sections that have named rows.

• Sections that have a known or constant number of cells.

• Sections that have an unknown or variable number of cells.

Accessing Cells in Sections That Have Named Rows

If the cell that you want to access is in a ShapeSheet section that allows you to change the names of its rows, as shown in Table 2, use the CellsU property to access the cell by its universal name.

The following example shows how you can refer to the User.visKeywords.Value cell by its universal name.

Set cellObj = shpObj.CellsU("User.visKeywords.Value")

Table 2. Sections that have named rows and their universal row prefixes

Section	Universal row prefix	Example row name
Actions	Actions.	Actions.visOne
Connection Points Note Not all Connection Point rows are named.	Connections.	Connections.Top
Controls	Controls.	Controls.visOne
Custom Properties	Prop.	Prop.Cost
Hyperlinks	Hyperlink.	Hyperlink.HeadOffice
User-defined Cells	User.	User.visVersion

For more information about these sections and rows, see the Visio 2007 Software Development Kit. Or, in Office Visio 2007, on the Help menu, click Developer Reference.

Accessing Cells in Sections That Have a Known Number of Cells

If the cell that you want to access is in a ShapeSheet section that has a known or constant number of cells, such as those shown in Table 3, use the CellsSRC property to access the cell by its section, row, and cell index. Accessing cells by using the CellsSRC property is locale-independent because you use an index (represented by a constant declared in the Visio type library) rather than a name, and it is faster than other methods that use cell names.

For example, you can refer to the Fill Pattern cell in the Fill Format section by its section, row, and cell index (represented by constants), as shown in the following example.

Set cellObj = shpObj.CellsSRC(visSectionObject, visRowFill, visFillPattern)

Table 3. Sections with the visSectionObject constant for a section index, a known number of cells, and a row constant for a row index

For more information about these sections and rows, the cells in these sections and rows, and their constants, see the Visio 2007 Software Development Kit. Or, in Office Visio 2007, on the Help menu, click Developer Reference.

Accessing Cells in Sections That Have an Unknown Number of Cells

If the cell that you want to access is not in any of the previously mentioned ShapeSheet sections, the section that it is in has an unknown, or variable, number of cells, such as the Geometry section.

To access cells in sections that have an unknown number of cells

1. Use the RowCount property to get the number of rows in the section.

2. Iterate through the rows.

3. Get the cells associated with a row by using the CellsSRC property.

For more information about using these properties and associated example code, see the Visio 2007 Software Development Kit. Or, in Office Visio 2007, on the Help menu, click Developer Reference.

Accessing Add-Ons

Whether an Addon object has a universal name depends on the way that the object is integrated with Office Visio. There are three ways that you can make Visio recognize your add-ons:

• By publishing components.

• By using path discovery.

• By using the Add method of the Addons collection.

Publishing Components

Starting with Visio 2003, you can publish your add-ons, templates, stencils, and other files as components to be integrated with Visio. Publishing components is the preferred method of integrating add-ons and other content with Visio. It offers tighter integration with Visio and better performance for add-on discovery. The component publishing functionality in Visio enables developers to include a PublishComponent table in the Windows Installer (.msi) file that they create to install content (such as add-ons, templates, stencils, or other files). Each PublishComponent table entry contains information about how a specific file that is to be installed should be displayed in the Visio UI. During installation, these entries are published to the Visio registry. Visio uses this information to display the add-on in its UI, and to install-on-demand or repair the file as needed.

The Visio 2007 Software Development Kit (SDK) includes the Solution Publishing Tool, which can help make publishing Visio solutions easier. For more information about this method and the Solution Publishing Tool, see Publishing Visio 2007 Solutions. To download the Visio 2007 SDK and the Solution Publishing Tool, see the Visio 2007: Software Development Kit.

Using Path Discovery

Visio recognizes your add-ons if you add the path where these files are installed to the Visio Start-up or Add-ons paths.

To add the path to the installed files

• On the Tools menu, click Options.

• On the Advanced tab, click File Paths.

Using the Add Method of the Addons Collection

You can add the files for your add-ons to the collection of add-ons in a Visio instance by using the Add method of the application's Addons collection. This option is available only programmatically. Visio 2007 Addon objects for path-discovered add-ons do not have local and universal names. They have only one name that you can get, but not set, by using the Name property. The method that you use for different locales depends on how your add-on is called:

• If your add-on is called from the Add-Ons submenu of the Tools menu, you must translate the name for every language version of Visio 2007 that you support.

• If your add-on is called from a shape's ShapeSheet cell by using the RUNADDONWARGS function, from a persisted document event, or by using an object's AddonName property, you do not have to translate the name. In this situation, the name of the add-on is essentially a universal name.

• If your add-on is in a Visio library (.vsl) file and is called in multiple ways, you can create two copies of your add-on (.vsl files support multiple add-ons). One copy of the add-on has a name that is localized and added to a resource string in your .vsl file; this add-on appears on the Add-Ons menu. The other copy is a "hidden" add-on that has a name that you do not need to localize, which is the universal name. You call this add-on in other ways, such as from a shape's ShapeSheet cell by using the RUNADDONWARGS function, from a persisted document event, or by using an object's AddonName property. This add-on never appears on the Add-Ons menu.

For more information about Visio add-ons, see Overview of Add-ons and COM Add-ins in Visio 2007.

Accessing Templates and Stencils

Visio 2007 Document objects do not have local and universal names. They have only one name; however, you can use the AlternateNames property to simulate universal names.

When Visio 2007 opens a document, such as a template or stencil, or accesses the Documents collection, and it cannot find the document name in the template path, in the stencil path, or in the Documents collection, it looks for the alternate document names.

• If the document is component-published, the alternate names are specified as part of the PublishComponent table entry for that document. (Any alternate names specified in the document itself are ignored.)

• If the document is path-discovered, Visio looks for the alternate names (that you set by using the AlternateNames property) in the Templates path, in the Stencils path, or in the Documents collection.

If the appropriate location contains all possible names for your template or stencil, or at least contains the name that you use to access the document in your code, Visio 2007 can find the document, no matter what language you are using.

For example, the following names are the alternate names for the Basic Flowchart Shapes (US Units) stencil that is included with Visio 2007.

BasFlo_U.vss;Basic Flowchart Shapes (US units).vss;BasFlo_M.vss;Basic Flowchart Shapes.vss;
<Begin Localize>;Basic Flowchart Shapes 2.vss;Basic Flowchart Shapes With Vertical Text.vss;
Basic Flowchart Shapes.vss;Flowchart Shapes 2.vss;Flowchart Shapes.vss

You can use the following code to open the Basic Flowchart Shapes (US Units) stencil (in the docked position and read-only mode) in any language version of Visio 2007 because the name used in the following code is also included in the alternate names listed previously.

Documents.OpenEx("Basic Flowchart Shapes.vss", visOpenDocked+visOpenRO)

For more information about the AlternateNames property and associated example code, see the Visio 2007 Software Development Kit. Or, in Office Visio 2007, on the Help menu, click Developer Reference.

Universal Syntax

The key to controlling shape actions is to write ShapeSheet formulas that define the behavior that you want. Formulas are expressions that contain constants, functions, operators, and cell references. Office Visio 2007 evaluates these formulas and then converts the result to the appropriate units and syntax for the ShapeSheet cell that contains the formula. Different countries and regions often use different syntax—or formats—for dates, time, currency, and units. For example, people in the United States use month, day, and year syntax for dates, while many other countries and regions use day, month, and year syntax. And, most people in the world use the Gregorian calendar, but some countries and regions, such as Japan, Korea, Thailand, and some Middle Eastern countries and regions use different calendar types.

In Office Visio 2007, the ShapeSheet UI displays universal syntax in ShapeSheet cells. It is equally important to use universal syntax in formulas in your solution code as it is to use universal names for objects in your solution code.

Getting and Setting Formulas by Using Universal Syntax

You can get or set formulas or cell results in your custom Office Visio 2007 solutions by using universal syntax with Automation properties and methods, as shown in Table 4. For example, you can set the formula of a Cell object by using the FormulaU property and the universal decimal syntax (.), as shown in the following example.

cellobj.FormulaU = "Width*1.75"

Table 4. Properties and methods used to get and set universal syntax in formulas

Property or method	Objects	Description
FieldFormulaU property	Characters	Gets a field's formula by using universal syntax.
FormulaForceU property	Cell	Sets a formula by using universal syntax, even if the formula is protected with a GUARD function.
FormulaU property	Cell	Gets or sets a formula by using universal syntax. Note The decimal point is always "."; the delimiter is always ","; and you must use universal units.
GetFormulasU method	Master, Shape, Style, and Page	Gets the formulas for more than one cell by using universal syntax.
ResultStrU property	Cell	Gets the value of a ShapeSheet cell expressed in universal syntax.
SetFormulas method	Master, Shape, Style, and Page	Sets the formulas for one or more cells. Use the visSetUniversalSyntax constant to specify universal syntax.
SetResults method	Master, Shape, Style, and Page	Sets the results (values) for one or more cells. Use the visSetUniversalSyntax constant to specify universal syntax.

For more information about using these properties and methods and associated example code, see the Visio 2007 Software Development Kit. Or, in Office Visio 2007, on the Help menu, click Developer Reference.

Cross-Referencing Cells in Formulas by Using Universal Cell Names

In a cell's formula, you can refer to a cell of the same object or another object, such as a document or page, so that Visio 2007 calculates a value for one cell based on another cell's value. When you develop custom Visio 2007 solutions for multiple languages, make sure that you use universal cell names when you cross-reference cells in formulas.

For example, the universal name of the ShapeSheet spreadsheet for a page is ThePage, and the universal name of the ShapeSheet spreadsheet for a document is TheDoc. You could use the following example code to reference the PageWidth cell for the page in a formula that uses the page's universal name.

cellobj.FormulaU = "ThePage!PageWidth*.25"

Using Universal Separators

Different countries and regions use different separators to separate lists, such as arguments, numbers, and values, in formulas. For example, in the United States, a period (.) is the decimal separator; however, in most European countries and regions, the comma (,) is used as a decimal separator. To make sure that you use a separator that works with any language version of Visio 2007, use the universal separators shown in Table 5 in your solution code.

Table 5. Universal separator syntax and behavior

Using Universal Units

In formulas, you often specify units of measure for values, and the set of recognized units changes with each language version of Office Visio 2007. If you want your solution to work with multiple languages, use the universal syntax shown in Table 6 for units of measure.

You can also use the unit constants shown in Table 6 to format cell values by using the Result property of a Cell object or the FormatResult method of the Application object.

Table 6. Universal unit syntax and constants

Using Universal Date, Time, and Currency Formatting

Date formats, time formats, and currency symbols vary for different countries and regions and change with each language version of Visio 2007. For example, some currency symbols precede the amount and others follow the amount. Use the universal syntax shown in Table 7 in your solution code to ensure that your solution displays the correct date, time, and currency formatting in different language versions of Visio 2007.

For example, you can use the following example code to display the currency symbol defined by your system's Regional and Language Options in any language version of Visio 2007.

cellobj.FormulaU = "$250"

Table 7. Universal date, time, and currency syntax and behavior

Using Universal Functions

Formulas can contain functions, and functions also have universal names. In Office Visio 2007, all universal function names are the same as their US English names.

Visio 2007 Available Languages

Microsoft Office Visio 2007 is available in the following languages:

• US English

• Japanese

• French

• German

• Spanish

• Italian

• Korean

• Traditional Chinese

• Simplified Chinese

• Dutch

• Brazilian Portuguese

• European Portuguese

• Danish

• Swedish

• Norwegian

• Finnish

• Arabic

• Polish

• Hebrew

• Russian

• Czech

• Turkish

• Hungarian

For more information about the different language versions of Office Visio 2007, see the Visio Home Page on Microsoft Office Online.

For more information about any of the objects, properties, and methods in this article, see the Visio 2007 Software Development Kit. Or, in Office Visio 2007, on the Help menu, click Developer Reference.

Conclusion

This article explains how to use universal names and syntax in your code, making it possible to localize custom Visio 2007 solutions easily. It also shows how to access stencils, templates, and add-ons across differing locales and lists the languages in which Visio 2007 is available.

Additional Resources

• Visio 2007: Software Development Kit

• Publishing Visio 2007 Solutions