Using Universal Names and Syntax to Localize Your Visio Solutions
Microsoft Corporation
December 2003
Applies to:
Microsoft Office System
Microsoft Office Visio 2003
Summary: Learn how to use universal names and syntax in your code, which enables custom Microsoft Office Visio 2003 solutions to be easily localized. You will also learn how to access stencils, templates, and add-ons across locales. (13 printed pages)
Contents
Introduction
Local and Universal Names
Universal Syntax
Additional Information
Introduction
Microsoft Office Visio 2003 is available in multiple languages for international markets. When developing custom solutions for Visio, determine whether you want to adapt or localize your solutions to work with multiple languages. Localization techniques, such as using universal Visio 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, visit the Microsoft Global Software Development Web site.
Local and Universal Names
For the various language versions of Visio, the language displayed in the user interface changes. Names of objects in the user interface, such as masters, master shortcuts, pages, styles, and layers, change with each language version. Referring to these object names for multiple languages in your code makes localizing your solutions needlessly time-consuming; each name reference must be changed for each language version that the solution supports.
Shape, Master, MasterShortcut, Page, Style, Layer, Row, and Cell objects have local and universal names so it is not necessary to refer to user interface names in your solution code. Local names are the names that appear in the user interface and they change to reflect the language version that Visio is running. Universal names remain constant. They do not change with different language versions of Visio, and cannot be changed through the user interface. Refer to 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 ShapeSheet user interface, which currently displays only universal names. All ShapeSheet rows and cells display universal names only. If you change a row or cell name in the ShapeSheet interface, you are changing its universal name.
Using Universal Names of Objects that are Included with Visio
The universal names of all masters, master shortcuts, styles, and layers included with Visio are their English names. In the English version, the universal and local names of these objects are the same—unless you change the universal name through your solution code or the local name through the user interface.
The universal names of all the ShapeSheet sections, rows, and cells for these objects are also the English names. In the English version, the universal and local names of these objects are identical.
**Note **The ShapeSheet displays only universal names. For previous versions of Visio, when you use a non-English language version of Visio, the ShapeSheet spreadsheet's user interface translation is inconsistent across language versions; it usually displays a combination of local names in the user's language and universal names in English. Sometimes the local name may be the same as the universal name and other times it may not; it depends on the mixture of languages in the user interface.
Using Universal Names of Objects that You Create
When you create a new Shape, Master, MasterShortcut, Page, Style, Layer, Row, or Cell object, through either the user interface or your solution code, and name it for the first time, the local and universal names are identical. After the initial creation, if you change the name through the user interface or use a different language version of Visio, only the local name changes. For example, if you insert a row in the User-defined Cells section in the ShapeSheet spreadsheet, and then name the row User.ABC, that name is the row's universal and local name. If you change the row name 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 through Code
Through the Automation interface, you can get a Shape, Master, MasterShortcut, Page, Style, Layer, Row, or Cell object by its universal name, or set its universal name, using properties or methods that have a "U" suffix. These properties and methods are shown in the Table 1.
**Note **Because rows and cells appear in the ShapeSheet user interface, which displays only universal names, if you change the names of rows or cells in that interface, you are changing their universal names.
For example, if you want to verify the universal name of the current Layer object, you could use the NameU property to get the current Layer object's universal name, as shown in the following example.
Debug.Print "The current layerObj name is """ & layerObj.NameU & "."""
Table 1. Properties and methods that refer to objects by their universal name
| Property or Method | Objects | Description |
|---|---|---|
| CellExistsU property | Shape and Style | Determines whether a cell exists using its universal name.
Note If you change the name of a cell through the ShapeSheet user interface, you are changing the universal name. |
| CellsRowIndexU property | Shape | Gets a cell's row index using the cell's universal name. |
| CellsU property | Shape and Style | Gets a cell using its universal name. |
| CellU property | Row | Gets a cell using its universal name. |
| ItemU property | Addon, Hyperlink,Layers, Masters, MasterShortcuts, Pages, Shapes, and Styles | Gets an object from a collection using its universal name. |
Name property
Note This is the only property that is used to get a universal name that doesn't 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 details on accessing cells, see the Accessing Cells in the ShapeSheet Spreadsheet section. |
| 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 using universal names to identify the shapes, and it returns an array of the IDs for the Shape objects it creates. |
| GetNamesU method | Addons, Masters, MasterShortcuts, Pages, andStyles | Gets the universal names of all items in a collection. |
For more information on using these properties and methods and associated example code, search the Developer Reference in Visio.
Accessing Cells in the ShapeSheet Spreadsheet
When you develop solutions that support multiple languages, access cells using their universal names. However, the method you use to do this, depends on the type of section and row the cell is in.
Accessing Cells in Sections with Named Rows
If the cell that you want to access is in a ShapeSheet section in which you can change the names of its rows, as shown in the following table, use the CellsU property to access the cell by its universal name.
The following example shows how you could refer to the User.visKeywords.Value cell by its universal name.
Set cellObj = shpObj.CellsU("User.visKeywords.Value")
Table 2. Sections with named rows and their universal row prefix
| Section | Universal row prefix | Example row name |
|---|---|---|
| Action | Action. | Action.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 on these sections and rows, search the Developer Reference in Visio.
Accessing Cells in Sections with a Known Number of Cells
If the cell that you want to access is in any of the ShapeSheet sections that have a known or constant number of cells, as shown in the Table 3, use the CellsSRC property to access the cell by its section, row, and cell index. Accessing cells 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's faster than other methods that use cell names.
For example, you could 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 the following table are found in Shape, Page, and Document objects.
Table 3. Sections with a known number of cells, section constant, and row constant
| Section | Section constant | Row constant |
|---|---|---|
| 1-D Endpoints | visSectionObject | visRowXForm1D |
| Alignment | visSectionObject | visRowAlign |
| Document Properties | visSectionObject | visRowDoc |
| Events | visSectionObject | visRowEvent |
| Fill Format | visSectionObject | visRowFill |
| Foreign Image Info | visSectionObject | visRowForeign |
| Glue Info | visSectionObject | visRowMisc |
| Group Properties | visSectionObject | visRowGroup |
| Image Properties | visSectionObject | visRowImage |
| Layer Membership | visSectionObject | visRowLayerMem |
| Line Format | visSectionObject | visRowLine |
| Miscellaneous | visSectionObject | visRowMisc |
| Page Layout | visSectionObject | visRowPageLayout |
| Page Properties | visSectionObject | visRowPage |
| Print Properties | visSectionObject | visRowPrintProperties |
| Protection | visSectionObject | visRowLock |
| Ruler and Grid | visSectionObject | visRowRulerGrid |
| Shape Layout | visSectionObject | visRowShapeLayout |
| Shape Transform | visSectionObject | visRowXFormOut |
| Style Properties | visSectionObject | visRowStyle |
| Text Block Format | visSectionObject | visRowText |
| Text Transform | visSectionObject | visRowTestForm |
For more information on these sections and rows, and on the cells in these sections and rows, and their constants, search the Developer Reference in Visio.
Accessing Cells in Sections with 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 with 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 using the CellsSRC property.
For more information about using these properties and associated example code, search the Developer Reference in Visio.
Accessing Add-ons
Whether an Addon object has a universal name depends on the way that it was integrated with the Visio application.
There are three ways to have the Visio application recognize add-ons:
**Publish component.******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. 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 MSI (Microsoft 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 that is to be installed should be displayed in the 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.
**Path discovered.******The Visio application will also recognize your add-on if you add the path where these files are installed to the Start-up or Add-ons paths (on the Tools menu, click Options, and then on the Advanced tab, click FilePaths). Install the add-ons that you develop in new folders 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 folders containing Visio content.
Add method. You can also add the files to the collection of add-ons in a Visio instance using the Add method of the application's Addons collection. This option is only available programmatically. Addon objects for path-discovered add-ons don't have local and universal names. They have only one name that you can get, but not set, using the Name property. The method that you use to work with this for different locales depends on how your add-on is called:
If your add-on is called from the Add-on submenu, you must translate the name for every language version of Visio that you support.
If your add-on is called from a shape's ShapeSheet cell using the RUNADDONWARGS function, from a persisted document event, or using an object's AddonName property, you don't 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 don't need to localize, which is the universal name. You call this add-on other ways, such as from a shape's ShapeSheet cell using the RUNADDONWARGS function, from a persisted document event, or using an object's AddonName property. This add-on never appears on the Add-Ons menu.
For more information on Visio add-ons, see About Microsoft Office Visio Add-ons and COM Add-ins.
Accessing Templates and Stencils
Document objects don't have local and universal names. They have only one name; however, you can use the AlternateNames property to simulate universal names.
When Visio opens a document, such as a template or stencil, or accesses the Documents collection, and it cannot find the document name in the template or stencil path or in the Documents collection, it looks for the alternate document names:
- If the document was 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 was path-discovered (that is, placed in the Templates or Stencils file paths), Visio looks for the alternate names (that you set using the AlternateNames property) in the template and stencil path or in the Documents collection.
And, as long as 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 through your code, Visio should always find the document no matter what language you are using.
For example, the following names are the alternate names for the Basic Flowchart Shapes stencil that is included with Visio.
Basic Flowchart Shapes.vss;Basic Flowchart Shapes (US Units).vss;<Begin
Localize>;Basic Flowcharts Shapes2.vss;Basic Flowchart Shapes With
Vertical Text.vss;Basic Flowchart Shapes.vss;Flowchart
Shapes2.vss;Flowchart Shapes.vss;FLOWCHRT.VSS;FLOWCHT2.VSS
You can use the following code to open the Basic Flowchart Shapes stencil (in the docked position and read-only mode) in any language version of Visio 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 on the Advanced tab click the File Paths tab. Or use the TemplatePaths and StencilPaths properties for the Application object to set template and stencil paths in your code. File paths are different for different language versions of Visio.
For more information on the AlternateNames property and associated example code, search the Developer Reference in Visio.
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. Visio evaluates these formulas, and then converts the result to the appropriate units and syntax for the ShapeSheet cell that contains the formula. Different countries/regions often use different syntax—or formats—for dates, time, currency, units, and so on. For example, people in the United States use month, day, and year syntax for dates while many other countries/regions use day, month, and year syntax. And, most people in the world use the Gregorian calendar, but some countries/regions such as Japan, Korea, Thailand, and some Middle Eastern countries/regions use different calendar types.
In Visio, the ShapeSheet user interface displays universal syntax in ShapeSheet cells. It is equally important to use universal syntax in your formulas in your solution code as it is to use universal names for objects in your solution code.
**Note **In previous versions of Visio, the ShapeSheet user interface displays local syntax in ShapeSheet cells. And, just as the local names of objects change with different language versions of Visio, the local syntax in ShapeSheet cells, such as separators, units, dates, and currency symbols, also changes.
Getting and Setting Formulas Using Universal Syntax
You can get or set formulas or cell results in your custom Visio solutions using universal syntax with the properties and methods as shown in the following table. For example, set a Cell object's formula 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 using universal syntax. |
| FormulaForceU property | Cell | Sets a formula using universal syntax even if the formula is protected with a GUARD function. |
| FormulaU property | Cell | Gets or sets a formula 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 using universal syntax. |
| SetFormulas method | Master, Shape, Style, and Page | Sets the formulas for one or more cells. Use the visSetUniversalSyntax flag to use universal syntax. |
| SetResults method | Master, Shape, Style, and Page | Sets the results (values) for one or more cells. Use the visSetUniversalSyntax flag to use universal syntax. |
For more information on using these properties and methods and associated example code, search the Developer Reference in Visio.
Cross-Referencing Cells in Formulas 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 calculates a value for one cell based on another cell's value. When you develop custom solutions for multiple languages, make sure that you use universal cell names when cross-referencing cells in formulas. For example, the universal name of the ShapeSheet spreadsheet for a page is the ThePage, and the universal name for the ShapeSheet spreadsheet for a document is TheDoc. You could use the example code, shown as follows, to refer to the PageWidth cell for the page in a formula using the page's universal name.
cellobj.FormulaU = "ThePage!PageWidth*.25"
Using Universal Separators
Different countries/regions use different separators to separate lists, such as arguments, numbers, values, and so on, in formulas. For example, in the United States, a period (.) is the decimal separator; however, in most European countries/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, use the universal separators shown in the following table 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 Settings. |
| 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 change with each language version of Visio. If you want your solution to work with multiple languages, use the universal syntax, shown in the Table 6, for units of measure.
You can also use the unit constants, shown in Table 6, to format cell values using a Cell object's Result property or the Application object's FormatResult method.
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 | ° |
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) |
Date formats, time formats, and currency symbols also vary for different countries/regions, and change with each language version of Visio. 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 your solution displays the correct date, time, and currency formatting in different language versions of Visio.
For example, you could use the following example code to display the currency symbol defined by your system's Regional settings in any language version of Visio.
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 Settings. |
| Date format | / | Formats and separates the date components, and displays the date separator defined by the system's Regional Settings. |
| Time format | : | Formats and displays the time separator defined by the system's Regional Settings. |
| 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. All universal function names are the same as the English names.
**Note **In previous versions, some universal function names differed from the English function name, primarily in regards to capitalization, and whether the function name started with an underscore.
Additional Information
Microsoft Office Visio 2003 is available in the following languages:
- English
- Japanese
- French
- German
- Spanish
- Italian
- Korean
- Traditional Chinese
- Simplified Chinese
- Dutch
- Brazilian Portuguese
- Danish
- Swedish
- Norwegian
- Finnish
For more information on the different language versions of Visio, visit the Microsoft Office Visio Web Site.
For more information on any of the objects, properties, and methods in this article, search the Developer Reference in Visio.