Export (0) Print
Expand All
0 out of 1 rated this helpful - Rate this topic

Using Universal Names and Syntax to Localize Visio 2007 Solutions

Office 2007

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

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.

Bb902804.note(en-us,office.12).gifNote:

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.

Bb902804.note(en-us,office.12).gifNote:

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.

Bb902804.Important(en-us,office.12).gifImportant:

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

Bb902804.note(en-us,office.12).gifNote:
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.

Bb902804.note(en-us,office.12).gifNote:
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

Bb902804.note(en-us,office.12).gifNote:
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)
Bb902804.note(en-us,office.12).gifNote:

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

  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.

Bb902804.Caution(en-us,office.12).gifCaution:

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.

Bb902804.note(en-us,office.12).gifNote:

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)
Bb902804.note(en-us,office.12).gifNote:

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.

Bb902804.note(en-us,office.12).gifNote:

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.

Bb902804.note(en-us,office.12).gifNote:
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.

Bb902804.note(en-us,office.12).gifNote:

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.

Additional Resources

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.