API for Themes in the new Visio

In a previous blog post, we introduced the new themes, variants, and styles feature in the new Visio.

Not only does this feature make it easy and fast for users to create professional looking diagrams, it also fully supports programmatic access. This post will focus on how to use the new API methods to apply modern and vibrant looks to any diagram.

You can find more information on other new API in our blog post on new APIs in the new Visio. You can also see a full list of all new API in the What's new for Visio 2013 developers article on MSDN.

Working with Themes

The new Visio supports the new themes, variants, and styles with three new methods: Page.SetTheme, Page.SetThemeVariant, and Shape.SetQuickStyle. With these methods, a developer can set the theme of a given page, apply a variant of the theme, and customize a shape with a style.

Page.SetTheme(varThemeIndex, varColorScheme, varEffectScheme, varConnectorScheme, varFontScheme)

Sets the specified components of a theme on the given page. The varThemeIndex argument is the primary argument that applies one of the built-in themes to the given page. The other four optional arguments allow for further customization by utilizing alternate definitions for color and style sourced from other built-in themes. Choosing different indexes for these four optional arguments gives you a unique combination of properties that is not found in the built-in list. All five arguments are specified as indexes representing the set of built-in themes. The indexes of all five arguments start at 17 for "Visio Theme 1", and end at 32 for "Visio Theme 16". Please note that these index values are only relevant to the preview build and are subject to change for the final release.

Arguments:

• varThemeIndex: Required parameter specifying the index of the theme.
• varColorScheme: Optional parameter specifying the index of the colors used by the theme.
• varEffectScheme: Optional parameter specifying the index of the shape styles for two-dimensional shapes used by the theme.
• varConnectorScheme: Optional parameter specifying the index of the shape styles for one-dimensional shapes used by the theme.

• varFontScheme: Optional parameter specifying the index of the text styles used by the theme.

Page.SetThemeVariant(variantColor, variantStyle, embellishment)

Sets the specified variant component indexes and the embellishment setting on the given page. A variant is composed of two components: color and style. Using the same indexes for both will produce a variant that is accessible through the Variants gallery in the Ribbon's Design tab. Using a different index for each will produce a unique combination variant that is not found in the UI. The embellishment setting corresponds to the settings in the Variants gallery's flyout menu, and the setting can range from "low", to "medium", and finally to "high". The variant component indexes starts at 0 for "Variant 1" and ends at 3 for "Variant 4". The embellishment setting's index starts at 1 for "low" and ends at 3 for "high".

Arguments:

• variantColor: Required parameter specifying the index of the colors used by the variant.
• variantStyle: Required parameter specifying the index of the shape styles used by the variant (inclusive of two-dimensional, one-dimensional, and connector shapes).

• embellishment: Optional argument specifying the embellishment setting's index.

Shape.SetQuickStyle(lineMatrix, fillMatrix, effectsMatrix, fontMatrix, lineColor, fillColor, shadowColor, fontColor)

Sets the specified shape style on the given shape. Shape styles are controlled by eight indexes which stipulate colors and formatting for lines, fills, effects, and text. All shape styles found in the Shape Styles gallery in the Home tab on the ribbon can be set using this method. In addition, this method also allows each index to be controlled independently to produce unique shape style combinations not found in this gallery.

Arguments:

• lineMatrix: Specifies the formatting index controlling which line formatting properties (e.g. dash type, weight) to retrieve from the active theme and variant.
• fillMatrix: Specifies the formatting index controlling which fill formatting properties (e.g. fill type, gradient stops) to retrieve from the active theme and variant.
• effectsMatrix: Specifies the formatting index controlling which effects formatting properties (e.g. shadows, bevels) to retrieve from the active theme and variant.
• fontMatrix: Specifies the formatting index controlling which font formatting properties (e.g. style) to retrieve from the active theme and variant.
• lineColor: Specifies the color index controlling which color to retrieve from the active theme and variant for use in line formatting.
• fillColor: Specifies the color index controlling which color to retrieve from the active theme and variant for use in fill formatting.
• shadowColor: Specifies the color index controlling which color to retrieve from the active theme and variant for use in shadows.
• fontColor: Specifies the color index controlling which color to retrieve from the active theme and variant for use in shape text.

You can choose to set shape styles from either the "Variant Styles" section or the "Theme Styles" section of the Shape Styles gallery in the Home tab on the ribbon:

To set shape styles from the "Variant Styles" section:

Style and color indexes run from left to right, starting with 100 for the left-most selection and ending with 103 for the right-most selection. The following illustrates the indexes for the "Variant Styles" section, where style indexes are represented by blue colored text and color indexes are represented by red colored text:

To set shape styles from the "Theme Styles" section:

Style indexes correspond to the rows of the "Theme Styles" section of the Shape Styles gallery. Style indexes start from 1 for the top-most row and end at 6 for the bottom-most row. Color indexes correspond to the columns. Color indexes starts from 100 for the left-most column and ends at 106 for the right-most column. The following illustrates the indexes for the "Theme Styles" section, where style indexes are represented by blue colored text and color indexes are represented by red colored text:

Let's try it out!

Here is a diagram that we will be formatting:

 Using the methods listed above, we will apply themes, variants, and shape styles to this diagram. In each step, we will show you the C# code along with a screenshot of how it changed the diagram.

Note: In the code snippets below, page refers to the active drawing page.

First, let's apply a theme to the diagram using the SetTheme method:

// Apply Visio Theme 16 to the diagram page

page.SetTheme(32)

This yields the following result:

Second, let's apply the third variant of this theme to the diagram using the SetThemeVariant method:

// Apply the third variant to the diagram page

page.SetThemeVariant(2, 2);

This yields the following result:

Finally, let's apply a shape style to the "Finished Product" shape to highlight it against the rest of the diagram. I have chosen the bottom-right shape style in the "Theme Styles" section of the Shape Styles gallery, which in this theme and variant combination is a bright orange, solid-filled shape style:

// Get the "Finished Product" shape

Visio.Shape finishedProductShape = page.Shapes.get_ItemU("Custom 3");

// Apply the right-most shape style on the bottom row

finishedProductShape.SetQuickStyle(

// Specify the indexes of line, fill, effect, and font formatting

6, 6, 6, 6,

// Specify the indexes of line, fill, shadow, and font colors. Integer values can also be used.

106, 106, 106, 106);

This yields the following result:

In Summary

The new themes, variants, and styles feature allows both end-users and developers to quickly and easily format a diagram with professional and modern designs. We're interested to hear what developers think of this API functionality.

The Visio Answers forum and the Visio MSDN forum are also available to discuss Visio. And don't forget to use Send a Smile or Send a Frown to let us know what you think of our changes.