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.
Note
This article does not cover general localization issues, such as designing a localizable user interface. For more information about localization, see the Go Global Developer Center.
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.
Note
Starting with Visio 2003, the ShapeSheet displays universal names only. In versions of Visio before Visio 2003, when you use a non-US English language version of Visio, the ShapeSheet spreadsheet UI translation is inconsistent across language versions. Usually, the ShapeSheet spreadsheet UI displays a combination of local names in the user's language and universal names in US English. Sometimes the local name is the same as the universal name and other times it is not the same; it depends on the mixture of languages in the UI.
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.
Important
Because rows and cells appear in the ShapeSheet UI, which displays universal names only, if you change the names of rows or cells in that interface, you change their universal names.
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)
Note
The sections shown in Table 3 are found in Shape, Page, and Document objects. Each of these sections has the same section constant: visSectionObject.
Table 3. Sections with the visSectionObject constant for a section index, a known number of cells, and a row constant for a row index
Section |
Row constant |
---|---|
1-D Endpoints |
visRowXForm1D |
Alignment |
visRowAlign |
Document Properties |
visRowDoc |
Events |
visRowEvent |
Fill Format |
visRowFill |
Foreign Image Info |
visRowForeign |
Glue Info |
visRowMisc |
Group Properties |
visRowGroup |
Image Properties |
visRowImage |
Layer Membership |
visRowLayerMem |
Line Format |
visRowLine |
Miscellaneous |
visRowMisc |
Page Layout |
visRowPageLayout |
Page Properties |
visRowPage |
Print Properties |
visRowPrintProperties |
Protection |
visRowLock |
Ruler and Grid |
visRowRulerGrid |
Shape Layout |
visRowShapeLayout |
Shape Transform |
visRowXFormOut |
Style Properties |
visRowStyle |
Text Block Format |
visRowText |
Text Transform |
visRowTestForm |
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
Use the RowCount property to get the number of rows in the section.
Iterate through the rows.
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.
Warning
You must install the add-ons that you develop in new folders that you create to contain the add-ons, and append those new folders to the Start-up or Add-ons path. Do not place the add-ons that you develop into existing folders that contain content that was included with Visio.
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.
Note
The following code example has paragraph marks embedded to facilitate online viewing. You must remove those marks before using the code.
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)
Note
To set or determine the template and stencil paths, on the Tools menu, click Options, and then, on the Advanced tab, click File Paths. Or use the TemplatePaths and StencilPaths properties of the Application object to set template and stencil paths in your code. File paths are different for different language versions of Office Visio 2007.
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.
Note
In versions of Visio before Visio 2003, the ShapeSheet UI displays local syntax in ShapeSheet cells. And, just as the local names of objects change with different language versions of Visio 2007, the local syntax in ShapeSheet cells, such as separators, units, dates, and currency symbols, also changes.
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
Separator |
Universal syntax |
Behavior |
---|---|---|
Argument separator |
Comma (,) |
Separates arguments in formulas. |
Decimal separator |
Period (.) |
Determines how many digits are displayed to the left and right of the decimal position, and displays the decimal character defined by the system's Regional and Language Options. |
List separator |
Semicolon (;) |
Separates items in lists in formulas. |
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
Unit |
Universal syntax |
Constant |
---|---|---|
Centimeter |
CM |
visCentimeters (69) |
Ciceros |
C |
visCiceros (54) |
Ciceros and didots |
CICERO/DIDOT |
visCicerosAndDidots (52) |
Date or time |
DATE |
visDate (40) |
Degrees |
DEG |
visDegrees (81) |
Degrees, minutes, and seconds |
° (Decimal value: 0176) |
visDegreeMinSec (82) |
Didots |
D |
visDidots (53) |
Elapsed days |
ED |
visElapsedDay (44) |
Elapsed hours |
EH |
visElapsedHour (45) |
Elapsed minutes |
EM |
visElapsedMin (46) |
Elapsed seconds |
ES |
visElapsedSec (47) |
Elapsed weeks |
EW |
visElapsedWeek (43) |
Feet |
FT |
visFeet (66) |
Feet and inches |
FEET/INCHES |
visFeetAndInches (67) |
Inches |
IN |
visInches (65) |
Inches in fractions |
IN_F |
visInchFrac (73) |
Kilometers |
KM |
visKilometers (72) |
Meters |
M |
visMeters (71) |
Miles |
MI |
visMiles (68) |
Miles in fractions |
MI_F |
visMileFrac (74) |
Millimeters |
MM |
visMillimeters (70) |
Minutes |
' |
visMin (84) |
Nautical miles |
NM |
visNautMiles (76) |
Percent |
% |
visPercent (33) |
Picas |
P |
visPicas (51) |
Picas and points |
PICAPOINTS |
visPicasAndPoints (49) |
Points |
PT |
visPoints (50) |
Radians |
RAD |
visRadians (83) |
Seconds |
" |
visSec (85) |
Yards |
YD |
visYards (75) |
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
Description |
Universal syntax |
Behavior |
---|---|---|
Currency symbol format |
$ |
Formats and displays the currency symbol defined by the system's Regional and Language Options. |
Date format |
/ |
Formats and separates the date components, and displays the date separator defined by the system's Regional and Language Options. |
Time format |
: |
Formats and displays the time separator defined by the system's Regional and Language Options. |
Universal label placeholder |
uuu or UUU |
Inserts the universal, three-character currency abbreviations for all currencies after each subunit, for example, 99.00 USD for US dollars or 42.70 FRF for French francs. The uuu placeholder inserts lowercase labels, and the UUU placeholder inserts uppercase labels. |
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.
Note
In versions of Visio before Visio 2003, some universal function names differed from the US English function name, primarily with regard to capitalization, and whether the function name started with an underscore.
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.