Getting Started Developing Shapes in Visio 2003 ShapeStudio

 

Saul Candib
Microsoft Corporation

December 2004

Applies to:
    Microsoft Office Visio 2003 Editions

Summary:   ShapeStudio is a shape-development tool included in the Microsoft Office Visio 2003 SDK, providing a development and test environment that integrates with Visio. This article introduces the ShapeStudio work environment, workflow process, and various key concepts, and explains how to download, install, and set up ShapeStudio. (15 printed pages)

Contents

Developing Shapes in Visio 2003
Introducing ShapeStudio
Downloading and Installing ShapeStudio
Setting Up ShapeStudio
Starting ShapeStudio
The ShapeStudio Work Environment
Key Elements and Concepts in ShapeStudio
Workflow in ShapeStudio
Using ShapeStudio Help
Additional Resources

Developing Shapes in Visio 2003

Microsoft Office Visio 2003 is a shape-based diagramming program providing a wealth of built-in shapes that users can drag onto the drawing page to create drawings; many third-party shapes for use in Visio are available as well. Sometimes, however, when no built-in or third-party shapes exist to solve a specific drawing problem, a shape developer must create custom shapes that have a particular appearance or behave in a certain way. Once created, custom shapes become reusable components that can be assigned to Visio stencils or compiled into shape libraries. The capacity to use custom shapes is one of the features that make Visio such a powerful diagramming program.

Developing a shape involves creating the geometry of the shape and specifying and implementing its behavior. By choosing the correct combination of geometry and behavior, a shape developer can create shapes that model the objects in the real world that they represent.

Shape geometry refers to a shape's appearance, and consists of the lines, angles, and formatting of a shape, and whether a shape is rotated. It also includes the way a shape is structured—whether, for example, it is a simple shape or a complex shape (such as the bolt in Figure 1) that groups several simple shapes together. You create shape geometry by drawing a shape, using the Visio drawing tools on the drawing page. You can also create or extend shape geometry by writing formulas in the Visio ShapeSheet spreadsheet.

Figure 1. A shape that has complex geometry

Shape behavior refers to the way a shape interacts with other shapes and the drawing page, and the way users can interact with the shape. For example, shape behavior determines what a shape does when a user drags the shape onto the drawing page, double-clicks the shape, or clicks a command on the shape's shortcut (right-click) menu. As shown in Figure 2, a shape developer can create a behavior that lets users change a shape from a circle to a square by clicking a shortcut-menu command.

Figure 2. Changing a shape by clicking a shortcut-menu command (Click picture to view larger image)

The concept of shape behavior also includes custom properties assigned to a shape and data associated with the shape.

Shape behavior is usually implemented by means of formulas entered in cells in the ShapeSheet spreadsheet. (Behavior also can be implemented programmatically by using Automation.)

Of course, you can create shapes right in Visio without any additional tools, and shape developers have been doing just that since the earliest versions of Visio. Shape geometry, in fact, consists of formulas in the Visio ShapeSheet, and must be created either directly, by writing those formulas, or indirectly, by drawing on the drawing page.

However, because implementing shape behavior has always required knowledge of how to write ShapeSheet formulas, it has been one of the most difficult aspects of shape development.

Related shapes that should have consistent behavior sometimes behave differently from one another, because their behaviors have not been implemented in a systematic fashion. And testing of shapes is often done haphazardly, without the benefit of automation or scripts to improve efficiency.

For all these reasons, it would be useful to have a tool that standardizes shape development and makes it easier to specify, implement, and test shape behavior and store shape information for future reference. ShapeStudio, which is included in the Visio 2003 SDK, is just such a tool.

Introducing ShapeStudio

ShapeStudio is a development and productivity tool for people who design and develop Microsoft Office Visio shapes. ShapeStudio provides a custom work environment that integrates with Visio to make it easier to specify, create, build, test, and maintain Visio smart shapes and stencils.

Why Use ShapeStudio?

Some of the reasons for using ShapeStudio to develop shapes are as follows:

• Although developing a simple shape is easy, development of complex shapes or shapes with complex behavior is difficult and requires specialized knowledge. While knowledge of the ShapeSheet is important, even in ShapeStudio, you can apply numerous behaviors to the masters you create without ever opening the ShapeSheet window.
• The behaviors built into ShapeStudio are implemented by using the best practices of Visio shape development, so you can also study the ShapeSheet of masters to which you have applied behaviors in ShapeStudio to learn these best practices.
• ShapeStudio provides consistency in newly developed shapes. You could implement the same behavior in a variety of ways in the ShapeSheet (for example, by using different formulas) or in different locations (sections or cells) within the ShapeSheet. With ShapeStudio, behaviors are applied the same way every time.
• ShapeStudio stores master and stencil specifications and all data associated with shapes and projects you create independently in a database, not in a Visio document, making it easier for teams of designers, developers, and testers to work cooperatively, or for different aspects of shape creation to be handled by different teams or companies.
• Masters and stencils must be checked out before they can be edited, which provides tighter control over shape versioning.
• ShapeStudio provides extensive testing tools for ensuring that behaviors have been implemented as specified.

When to Use ShapeStudio

ShapeStudio is a powerful tool and makes shape development easier and more dependable. However, sometimes it makes more sense to create shapes directly in Visio, without making use of ShapeStudio. For example, if you are creating a one-of-a-kind shape that you know you won't need to use again, there is no reason to use ShapeStudio.

Also, remember that ShapeStudio doesn't make it any easier to create shape geometry—even in ShapeStudio, you must still create shape geometry by using standard Visio tools on the drawing page.

Use ShapeStudio when you want to do any of the following:

• Create shapes that have complex attributes and behaviors, such as multi-state shapes.
• Create shapes that are part of a hierarchy of similar shapes or sets of shapes that have minor variations.
• Create libraries of shapes and maintain them over time, including making changes to numerous shapes at the same time.
• Be able to test shapes you have developed to ensure they implement specified behaviors correctly.
• Create shapes as part of a shape-development team that divides labor amongst shape designers, developers, and testers, or outsource parts of the shape development process to other organizations.
• Store shape information independently rather than in the Visio documents in which the shapes are used.

Downloading and Installing ShapeStudio

ShapeStudio is included as part of the downloadable version of the Visio 2003 Software Development Kit (SDK).

To install ShapeStudio, download the executable file vissdk.exe and run it. (You must already have Visio 2003 installed on your computer before you install the SDK. In addition, you must have access to either Microsoft SQL Server or MSDE—see the next section for details.)

Setting Up ShapeStudio

Before you can use ShapeStudio, a database administrator must create the ShapeStudio database that will contain ShapeStudio projects. The ShapeStudio database can be either a SQL Server database located on a server or an MSDE (Microsoft SQL Server Desktop Engine) database on a user's local computer. ShapeStudio provides the ShapeStudio Database Administration tool to assist database administrators in this task.

The ShapeStudio Database Administration tool creates an MSDE database running on the user's computer.

Note   MSDE 2000 Release A is available as a free download.

To help you set up a SQL Server database, the Visio 2003 SDK also includes a SQL script file named SStudio.sql, which a database administrator must run. The SQL Server script file is included so that database administrators may examine it and modify it for their own purposes. However, the only modifications allowed in the script are those that create a global ShapeStudio project that has units and version different from the default. (See the comments at the end of the SQL script.)

The ShapeStudio Database Administration tool does not actually run that script file, but rather runs a copy of the script file (containing the same SQL statements) that is linked to the executable for the tool, thereby ensuring that a valid database is always created, even if the script was changed or deleted.

The SQL Server script file does the following:

• Creates a ShapeStudio database.

• Creates tables.

• Creates and executes stored procedures.

• Adds the standard Visio ShapeStudio behaviors.

• Creates a single global project. One and only one global project can be in each database.

• Sets the default Visio version and the default measurement unit for the global project.

  Note   As provided, the script sets up the database so that stencils created in projects in the database are designed to be used in Visio 2003 and use US units. To modify these values, comment out the line at the bottom of the script file that specifies this combination of version and units and remove the comment markers from the line that specifies the combination of version and units you want.

• Creates an open database connectivity (ODBC) data source name (DSN) connection for the database. This connection becomes the default ShapeStudio DSN connection if one does not already exist.

The ShapeStudio Database Administration tool (Figure 3) has the filename SSadmin.exe, and if you install the SDK to the default location, the tool is installed in the following folder: C:\Program Files\Microsoft Office\Visio11\SDK\ShapeStudio\.

Figure 3. The ShapeStudio Database Administration tool window (Click picture to view larger image)

Starting ShapeStudio

ShapeStudio is a Visio add-on (VSL). To use ShapeStudio, you must have Visio 2003 installed and running.

For Microsoft Windows 2000 operating systems only, ShapeStudio requires Microsoft Data Access Components (MDAC) 2.6.

To start ShapeStudio

1. Start Visio 2003.
2. On the Tools menu, click ShapeStudio.
3. In the ShapeStudio dialog box, select the data source that you want to connect to and the project you want to work in.

The ShapeStudio Work Environment

Because ShapeStudio is a Visio add-on, it runs within the Visio window (Figure 4), but it provides its own distinctive workspace.

Figure 4. The ShapeStudio work environment (Click picture to view larger image)

The ShapeStudio workspace includes four windows that are unique to ShapeStudio.

• Project Explorer window

  The Project Explorer window contains a tree view of your project, showing the hierarchical relationships between all the objects in the project. The window has two different views: base masters and masters are displayed in the Masters view (Figure 5); stencil specifications are displayed with their assigned masters in the Stencils view. You can right-click any object in the tree to access commands that are relevant to the context, such as the Check Out command, which checks out masters so that you can work on them.

  

  Figure 5. Masters view in the Project Explorer window

• Specification window

  The Specification window (Figure 6) displays the list of behaviors that you assign to base master, master, and stencil specifications. You can use this window to specify the behaviors that you want to include in an object's specification.

  Click Modify to open the Modify Specification dialog box, where you can view the list of behaviors you can assign to the specification, assign new behaviors to the specification, or modify or remove behaviors already assigned to the specification.

  

  Figure 6. The Master specification window

• Validation window

  All validation and error information appears in the Validation window (Figure 7). Use this view to resolve validation errors.

  Double-click the name of a base master, master, or stencil specification in the Validation window to resolve validation errors. Or, you can right-click anywhere in the Validation window text area to access the commands that are relevant to the context.

  

  Figure 7. The Validation window

• Output window

  All project log information appears in the Output window (Figures 8).

  You can right-click anywhere in the Output window text area to open the log file or access the other commands that are relevant to the context.

  

  Figure 8. The Output window

In addition, the workspace includes three windows that are common to all Visio drawings: the document stencil, the document page, and the master-editing window.

• Document stencil

  When you check out a base master or master to edit its behavior specification or shape geometry, it appears in the document stencil (Figure 9). When you double-click a master in the document stencil, Visio opens an editing window where you can edit the shape geometry of the master. You can drag a master from the document stencil to the document page to experiment with its instance. You can also open read-only copies of base masters or masters in the document stencil and drag them to the page for the same purpose.

  

  Figure 9. Checked-out and read-only masters in the document stencil

  When you open a base master or master as read-only, its specification also is in read-only mode. The text "[read-only]" is prepended to the name of a master when it is placed on the document stencil to help you distinguish it from masters that are checked out.

• Drawing page

  The drawing page window in ShapeStudio is identical to the Visio drawing page window. On the drawing page, you can experiment with instances of the masters you create.

• Master-editing window

  When you double-click a master in the document stencil, Visio opens the master-editing window, where you can create or edit the shape geometry of the master. You must create master-shape geometry before you can apply any behaviors to a master.

Key Elements and Concepts in ShapeStudio

ShapeStudio consists of various elements and concepts, some familiar from Visio or from other applications and tools, such as projects and stencils; and others unique to ShapeStudio, such as behaviors and sets.

Projects

Projects in ShapeStudio provide a method for organizing and managing your shape development work. You can organize your projects in the way that best suits your needs. For example, a project could contain the shape information for a particular solution area or content domain, such as network equipment. Each project you create is stored in the database you specified for ShapeStudio. Projects have properties, which you can assign in the Project Properties dialog box (ShapeStudio menu.). For more information about projects, see the topic "About Workflow and Roles in ShapeStudio" in ShapeStudio Help.

Base Master and Master Specifications

A base master specification or master specification is a formal definition that includes the intended behaviors and shape-specific details for base masters and masters, respectively. When you create a project, it is a good idea to create base masters as templates for groups of masters that should share similar behaviors.

ShapeStudio masters correspond to the actual master shapes that are available on the stencil in Visio after you build a stencil file from the completed stencil specification. Base masters, however, are simply classification mechanisms that make it easier for you to categorize masters and create groups of similarly specified masters. Base masters never appear outside of ShapeStudio.

In addition to masters associated with base masters, ShapeStudio provides for baseless masters, which are masters not associated with any base master. You might create a baseless master, for example, if you want to include a master that does not inherit undesired behaviors from a base master. For more information about base master and master specifications, see the topic "About Master and Base Master Specifications" in ShapeStudio Help.

Stencil Specifications

A stencil specification is a virtual assembly of existing masters. It includes the name and properties of the stencil you want to create, a list of the masters you want to assign to the stencil, and any notes you want to make about the stencil.

You can assign to the stencil specification any of the masters (but not the base masters) that you have created in a project. Although only one version of any master exists in ShapeStudio, a master can belong to more than one stencil.

When you generate a stencil file, the stencil specification is used to build the .vss or .vsx file that Visio recognizes as a stencil file and that contains the actual masters. For more information about stencil specifications, see the topic "About Stencil Specifications" in ShapeStudio Help.

Behaviors

ShapeStudio introduces the concept of assigning behaviors to shapes as a way of simplifying the process of making smart shapes. A behavior is an abstract definition of a characteristic you want a shape to have—for example, that the shape has a certain ScreenTip associated with it. Rather than having to figure out and program various complexities of ShapeSheet formulas, cell references, or property settings for frequently needed shape functionality, you can assign behaviors to a master that describe how shapes that are instances of that master should behave. ShapeStudio then creates that behavior, using a best-practice implementation provided by Visio shape developers.

ShapeStudio makes it easier to implement the following common master attributes and behaviors, among others:

• Callout lines
• Connection points
• Shortcut menus
• Dynamic glue (shape connections that adjust automatically as shapes are moved)
• Control handles
• Drag-and-drop response
• Layer membership
• Sizing and resizing
• Shape structure
• Multi-state
• Smart tags
• ScreenTips

For more information about behaviors, and for a detailed list of behaviors in ShapeStudio, see the topic "About Behaviors in ShapeStudio" in ShapeStudio Help.

Sets

Sets are custom groupings of properties that can be used by behaviors. You can define sets of shortcut menu and smart tag menu commands (actions), custom properties, layer memberships, and ShapeSheet user-defined cells, and then assign them to your shapes in various combinations, making the shapes you create more modular. For more information about sets, see the topic "About Sets in ShapeStudio" in ShapeStudio Help.

Testing and Validation

In ShapeStudio, you can validate base masters and masters to verify that the objects developed in a project still conform to the specification settings originally intended by the project manager or shape designer. When you validate an object's current settings with its specification, any deviations from the specification are flagged as errors. You can then ignore the errors, in which case they will continue to be flagged as errors, or you can reapply the specification values to the object and thereby resolve the errors.

ShapeStudio provides two test tools that can help determine whether masters meet specifications and help find bugs that might cause masters to fail validation.

• Standard Shape Tests tool   This tool provides 28 pre-defined tests that check various settings for masters. You can run all of these tests (the default) or any combination of them. Generally, these tests check whether ShapeSheet cells or Automation properties are set properly, according to the specifications in the master. Standard tests are read-only: they check settings but do not change them. You can use the Find and Replace Cells and Set Cells tools to change properties in multiple masters.
• Custom Shape Tests tool   This tool lets you create custom test scripts that can run one or more custom tests that you design. You can run the script either on selected master specifications in Masters view of the Project Explorer window, or on selected stencil specifications in Stencils view. When you test stencils, you test all of the masters assigned to those stencils. You can save the test scripts you create (as XML files) so that you can run them again and modify them if necessary.

For a detailed list of all the tests available in ShapeStudio, see the topic "About Tools in ShapeStudio" in ShapeStudio Help.

Reports

ShapeStudio provides a variety of reports, including project reports, stencil reports, master reports, and check-out reports. For more information about reports, see the topic "About Reports in ShapeStudio" in ShapeStudio Help.

Reference Drawings

You can attach reference drawings to a ShapeStudio project to provide developers a model from which to work when implementing shapes. For example, reference drawings can contain pictures of the shape, bitmaps of the shape's icon, or other instructional notes and requirements that can't be easily specified as behaviors. To learn how to attach a reference drawing to your project, see the topic "Add a Reference Drawing to a Project" in ShapeStudio Help.

Styles

Styles, a feature found in Visio, make it easier to apply the same formatting to multiple shapes. ShapeStudio does not provide a user interface specifically for styles, but rather it tracks styles in your document, stores them in the database, and manages them as part of the checking out and checking in of masters.

Workflow in ShapeStudio

Workflow in ShapeStudio typically consists of the following phases:

1. Setup and project management
2. Specification and design
3. Development
4. Validation and testing

Figure 10 shows the relationship between these phases and project roles and activities.

Figure 10. A graphical representation of ShapeStudio workflow, roles, and activities (Click picture to view larger image)

The following steps suggest the general workflow to use in ShapeStudio, after the database administrator has set up the global project.

1. Open Visio, and then open ShapeStudio.

2. Create a project. This step includes naming the project and specifying the database for the project.

   Note   If the database administrator has created global base masters and masters in the global project, your project inherits them. If you intend to use global masters or global base masters in your project, ensure that the project unit and Visio version settings in your project match the global project unit and Visio version settings.

3. Create base masters to be used as "templates" for the masters you want to create. Then assign behaviors to the base masters that you want their associated masters to inherit.

4. Create masters based on a particular base master and assign behaviors to the masters in addition to inherited behaviors.

5. Add shape geometry for each master in its master drawing window.

6. Validate the current behaviors of masters against specified behaviors and resolve errors.

7. Create stencil specifications and assign masters to various stencils.

For more information about workflow in ShapeStudio, see the topic "About Workflow and Roles in ShapeStudio" in ShapeStudio Help.

Using ShapeStudio Help

ShapeStudio has a built-in Help system that explains many of the subjects addressed in this article in more detail and provides directions to help you perform many common procedures. To access ShapeStudio Help, you must be running Visio and have a ShapeStudio project open. Then click Help on the ShapeStudio menu to open the Microsoft Office Visio 2003 Help window.

Additional Resources

For additional help on developing shapes in Visio, see the following resources:

• Step-by-Step Guide to Building Shapes in Visio 2003 ShapeStudio
• Microsoft Office Visio 2003 SDK (online version)
• Microsoft Office Visio 2003 SDK (download version; includes ShapeStudio)