Lesson 4: Performance [Visio 2003 SDK Documentation]

  • Article

The Microsoft Visual Basic® .NET project files that accompany this lesson can be found at \Samples\Tutorial\VBNet\Lesson4.

Table of contents

Scenario

Implementation

Setting Shape Properties

Using SetFormulas

Summary: Performance

Scenario

As shown in Lesson 3: Data Input, you can use the TutorialAddin sample wizard to customize the shape master and to customize properties such as shape text, fill color, line color, and hyperlink.

Instead of setting shape properties individually on the Shape object, resulting in two calls per property for each shape, you can use the Microsoft® Visio® SetFormulas method to modify ShapeSheet® cells in a single call by specifying an array of values and cells.

In this lesson, we will show you how to:

  • Set shape properties by using Visio 2003 object model properties and ShapeSheet formulas.
  • Improve application performance by combining multiple calls to set ShapeSheet formulas into a single call using the SetFormulas method.

Implementation

To see the implementation of the sample application for this lesson, open the solution using Microsoft Visual Studio® .NET. The solution is found in the Lesson4 folder and is named Lesson4.sln.

Setting Shape Properties

In Lesson 3, the master specified by the user was used to create a shape. The CreateDrawing method sets each remaining shape property in one of two ways; it sets a Visio object model property or it sets a ShapeSheet formula.

Some of the more general shape properties can be set by properties on the Visio 2003 Shape object. For example, the following code sets the shape text:

shape.Characters.Text = shapeProp.Text

Other shape properties are defined using ShapeSheet formulas. The following code sets the shape fill color:

cell = shape.CellsSRC( _
    CShort(VisSectionIndices.visSectionObject), _
    CShort(VisRowIndices.visRowFill), _
    CShort(VisCellIndices.visFillForegnd))
cell.FormulaU = GetPalletColorFromShapeColor(shapeProp.FillColor)

The CellsSRC property returns a Cell object that represents a ShapeSheet cell identified by section, row, and column indices. Setting the FormulaU property for the Cell object modifies the color of the shape.

Using SetFormulas

The SetFormulas method extends your ability to set ShapeSheet formulas by allowing you to pack the values for multiple formulas into a single call. The SetFormulas method expects an array of 2 byte integers that specify the section, row, and column indices for cells in each shape.

We want to modify our code to use the SetFormulas method to specify the fill color, line color, and hyperlink. Because we have three shape cells and three indices to uniquely identify each cell, we size the array to nine elements, with each element 2 bytes long, as follows:

Dim sourceStream (8) As Short

Next, we set the section, row, and column indices for the fill color, line color, and hyperlink properties using corresponding ShapeSheet constants as follows:

sourceStream (0) = CShort(VisSectionIndices.visSectionObject)
sourceStream (1) = CShort(VisRowIndices.visRowFill)
sourceStream (2) = CShort(VisCellIndices.visFillForegnd)

sourceStream (3) = CShort(VisSectionIndices.visSectionObject)
sourceStream (4) = CShort(VisRowIndices.visRowLine)
sourceStream (5) = CShort(VisCellIndices.visLineColor)

sourceStream (6) = CShort(VisSectionIndices.visSectionHyperlink)
sourceStream (7) = CShort(VisRowIndices.visRow1stHyperlink)
sourceStream (8) = CShort(VisCellIndices.visHLinkAddress)

The preceding code specifies (in order) the fill color, line color, and hyperlink. Note that there is no ShapeSheet formula for the shape text, so we will continue to use the Text property of the Shape object to set that property.

The next step is to set the value of each property. The following declaration defines an array for each formula value:

Dim formula(2) As Object

The formulas are set as follows:

formula(0) = GetPaletteColorFromShapeColor(shapeProp.FillColor)
formula(1) = GetPaletteColorFromShapeColor(shapeProp.LineColor)
formula(2) = StringToFormulaForString(shapeProp.Hyperlink)

It is important to set the formulas in exactly the same order that the ShapeSheet indices are defined in. The formula parameter of the SetFormulas method is defined in the Visio Automation interface as an array of Variant types containing a string. The Visio Primary Interop Assembly (PIA) defines them as an Array type of Object types, which is the way that variants are marshaled through COM Interop. Although the SetFormulas method signature specifies a generic Object type, Visio 2003 expects the formula value to be a string.

The StringToFormulaForString function takes an input string and formats it into a formula string by replacing each quotation mark (") with a pair of quotation marks ("") and adding quotation marks around the entire string. By calling StringToFormulaForString, we ensure that string formulas are correctly formatted.

Finally, we call the SetFormulas method, passing both arrays as parameters:

shape.SetFormulas(CType(sourceStream, Array), _
    CType(formula, Array), _
    CShort(VisGetSetArgs.visSetUniversalSyntax))

Summary: Performance

Using the SetFormulas method to combine multiple method calls to set ShapeSheet formulas into a single method call results in better performance. Our sample code replaces six method calls with a single call. However, the performance savings are even more significant when using the Visio PIA.

As discussed in the topic "About COM Interop and the Visio PIA" in Lesson 1: Visio COM Add-in Creation in Visual Basic .NET, the COM add-in does not call the Visio 2003 type library directly, but rather uses the Visio PIA. The Visio PIA acts as .NET wrapper, which in turn calls the Visio 2003 type library. This overhead is inevitable when using COM Interop, because .NET types must be marshaled into COM types, or vice versa.

Thus, when using the Visio PIA, and COM Interop in general, examine your code to see when you can remove unneeded method calls that require COM Interop.