Planning a Visio Solution

3 4

The easiest kind of solution to implement is a standardized drawing that uses the content supplied with Microsoft Visio, along with shapes, stencils, and templates that you create. If you want to provide more assistance to users for creating specific types of drawings, you might want to add programming with the solution in the form of Microsoft Visual Basic for Applications (VBA) code, a COM (Component Object Model) add-in, or a Visio add-on. If the drawings to be created follow a strict set of rules, a solution might include an application that uses data from another source to generate drawings that the user can modify. If a solution is to provide more than just drawings, it will involve integration with an external database and possibly with external applications (either off-the-shelf or developed in-house).

Planning the Development Process

One developer can often create a simple Visio solution that consists of custom shapes, a template, and a small amount of code. More elaborate solutions, however, can require a team of developers, each with particular skills. For example, the team could consist of the following members:

• A system architect, who understands software system design and has a good understanding of Visio, its architecture, and general capabilities. The system architect owns the technical vision and design of a Visio solution.
• Shape developers, who understand what makes shapes usable in the solution being developed and are thoroughly familiar with the Visio drawing tools and the ShapeSheet window. Shape developers need a solid understanding of mathematics and geometry, because much of their work will involve creating formulas to control shape behavior.
• Automation developers, who are skilled in the programming language that will be used to develop the solution (VBA, Microsoft Visual Basic, or C++, depending on the type of integration that the solution will require). Automation developers need a basic understanding of Visio shapes and formulas and should be thoroughly familiar with the Visio object model.
• Subject matter experts, who have extensive knowledge and experience in the domain of the solution. A subject matter expert advises the team on industry or corporate standards, processes, usability, and exceptions to the rules.

Once the team is assembled, the following steps are suggested for the development process:

• Interview users to understand their requirements and identify the objects in the domain of the solution.

Ask users what steps they follow to accomplish their tasks. Collect examples of current drawings that your solution will automate or improve. In a large project, consider documenting requirements so that other users and developers can review them and understand what is needed.

• Develop the solution incrementally and involve the user at each stage to get feedback.

Incremental development and integration of Visio capabilities in a solution usually leads to a better result. It allows the user to use the solution sooner, and is a good way to get feedback to improve the solution during development.

• Start by developing shapes and allowing your users to try them, and then revise the shapes based on users' feedback.

The usability of a solution starts with how usable and relevant the shapes are going to be. For example, should you provide the user with many individual shapes, or schedule the time required to create multishapes (shapes that are designed to change appearance based on a setting)? Some users might find a few versatile shapes that can be manipulated into many different configurations more functional and less overwhelming than a stencil with many shapes to choose from; others might prefer a large assortment of single-purpose shapes.

• Once users are satisfied with the initial set of shapes, develop any drawing assistants or add-ons that the user might need to construct drawings, and, if necessary, fine-tune the shapes to work smoothly with them.

Standardized drawings alone can deliver much of the benefit users are looking for. Beware of over-engineering a solution; just because Visio is programmable doesn't mean a solution must include programming.

• Finally, if your solution's shapes and add-ons will interact with a database or other applications, determine exactly how to make this work early in the development process, so you can design shapes and add-ons accordingly.

The approach to this step will depend on the kind of solution you are developing. For details, see Integrating a Visio Solution with a Database and Choices for Implementing Automation later in this section.

Planning Shapes and Stencils

Start developing your solution by building the shapes it will need, and put as much shape functionality as possible in formulas. There are two important reasons to start with shapes:

• Shapes can be smart—you can use the intrinsic capabilities of Visio shapes to handle much of the graphic functionality that you'd otherwise have to code.
• Shapes are independent of code that controls them. Once you develop the masters your solution will use, you can change the shapes without having to recompile your code, and vice versa.

If the shape behavior you want is predictable and can be accomplished with formulas (for example, automatic sizing or scaling), put it in the shape using the ShapeSheet. If the behavior changes dynamically at run time—for example, the text in a shape or the arrangement of shapes in a drawing may change—handle that behavior in a program such as in VBA code in a document, an ActiveX control, a Visio add-on, or a COM add-in. You can control the appearance and behavior of shapes with great precision by setting shape formulas. If you can create a stencil of masters to accompany your solution, users might not need to draw anything with the Visio drawing tools.

As you build masters for a program, test them in a Visio instance by manually creating the kinds of drawings you intend the program to automate. This will give you a good idea of the code you'll need to write and the data you'll need to provide. It will also show you if your shape is working the way you expect.

Finally, remember that the stencil that contains your masters is an important part of your solution's user interface. As such, you'll want to:

• Make sure masters are arranged in the stencil so that users can find them easily.
• Consider organizing related masters in different stencils, especially if you might use them in more than one solution.

For details about creating masters and stencils, see Chapter 3, Visio Masters, Stencils, Templates, and Documents. For details about distributing stencils in a Visio solution, see Chapter 13, Packaging Stencils and Templates.

Planning Templates

A template provides a common workspace for users. It facilitates standardization by making it easy for the user to create standardized drawings by choosing from sets of shapes.

A template can include styles and set up drawing pages using a uniform grid and measurement system. A template can set up drawing pages with shapes already on them and open one or more stencils so a user can add more shapes. A template can also provide drawings with their own user interface by including ActiveX controls, such as command buttons and text boxes, custom controls that perform special tasks, and VBA code that allows a user to interact with the drawing through the controls. Providing a template with a Visio solution can yield the following benefits:

• If your solution is designed to create new Visio drawings, you can save both programming effort and execution time by storing your program as VBA macros in a Visio template, or by providing a template as a stand-alone file with a Visual Basic or C/C++ program.
• When a template is used to create a document, Visio copies the template's styles, document properties, and VBA macros, modules, and user forms to the new document. You don't need to set the document properties or define styles with Automation unless you want them to differ from the template, nor do you need to distribute a separate VBA program unless your code is complex or you expect to update it in the future.
• If your solution customizes the Visio user interface, make those customizations in the template document rather than to Visio itself. That way, the user can use Visio for other tasks, and your solution's user interface will appear only when the user is actually using your solution.
• Using a template can prevent some translation difficulties if your program refers to styles and will be used with multiple languages.

Note

---

Although providing VBA code in a template simplifies the files you need to distribute with a solution, it complicates fixing bugs or enhancing the code, because every document created from the template receives a copy of the code. For more flexibility, you might prefer to put the VBA code in a stencil or other document that accompanies your solution, so that you can distribute updates more easily. For details about creating templates, see Chapter 3, Visio Masters, Stencils, Templates, and Documents. For details about distributing templates in a Visio solution, see Chapter 13, Packaging Stencils and Templates.

Automating Shapes and Templates

After you develop your solution's masters and template (if any), you can use Automation to implement the rest of your solutions. Exactly what this entails depends on the purpose of your solution and the context in which it will run. However, you'll typically use Automation to do the following:

• Implement your solution's user interface.

Most stand-alone programs will need a dialog box or wizard page to advise the user what to do and prompt for any information that the program needs to execute.

• Store and retrieve data.

Shapes can have custom properties, which can be configured to prompt the user to enter data or shape properties when, for example, a master is dropped on the drawing page. However, to preserve data types and protect data from unplanned changes, you might want your solution to store data in and retrieve it from an external database.

• Place shapes, set their properties, or connect them.

If your solution creates a drawing, it will need to determine which masters to drop and where to drop them, set the shapes' text and apply styles, and connect shapes. If your solution reads drawings or works with existing shapes, it will need to find the shapes, make sure they're appropriate for the program, and get and set shape properties and formulas.

Remember that a shape can have formulas that resize or reorient it appropriately when your program moves or resizes it—just as if you moved or resized the shape yourself, using the mouse in a Visio drawing window. If you find yourself writing a lot of complex code that manipulates shapes, take a step back and think about whether that functionality can be handled by shape formulas.

For special considerations of distributing a Visio solution that includes Automation, see Chapter 26, Packaging a Visio Automation Solution.

Integrating a Visio Solution with a Database

Integrating a Visio solution with a database requires some planning to synchronize the drawings with the database. It's important to decide which database should be used, what should be changed and how, and when the changes should occur.

For example, in the security system solution described earlier in this chapter, each component (camera, sensor, control unit, and so on) is a numbered part in the manufacturer's catalog. By storing a part number as a custom property of each master, it is easy to look up part information in a version of the parts catalog stored as a database.

After designing the interactions between a solution and a database, a solution can make changes by:

• Handling Visio events that signal when the database should be updated or synchronized with the drawing.
• Creating an external program that queries the Visio drawing to extract the data when needed—for example, when the user requests it.
• Storing all of the solution's data in an external database and using data associated with Visio shapes, such as a custom property, as a key attribute to access records in the external database.

The Database Wizard provided with Visio can define user-defined cells and link custom property cells to database fields for simple solutions or for prototyping more complex solutions. You can use the DAO (Data Access Object) library provided by Microsoft to access databases through ODBC (Open Database Connectivity) or use the Jet database engine. Or, your Visio solution might call an Automation server that actually updates and synchronizes the database, which provides more control over the integrity of the database.

For details about Visio solutions and databases, see Chapter 20, Integrating Data with a Visio Solution.

Choices for Implementing Automation

The kind of program you write depends on what you're trying to do. You could write a VBA macro in a Visio document or another Automation controller application, or a stand-alone program in Visual Basic or C/C++. You could write a dynamic-link library (DLL) for a COM add-in, or another special kind of DLL that runs with Visio, called a Visio library (VSL). Users might run your program from the Microsoft Windows desktop or Windows Explorer, or they might run it from Visio, by choosing a command added to a Visio menu, a button added to its toolbar, or even by double-clicking or right-clicking a shape in a drawing. Or you could design your program to run automatically when a certain event happens, such as when a document is opened or created.

There are four basic ways to implement Automation in a Visio solution. You can implement the following:

• A stand-alone executable or EXE file, which is typically written in Visual Basic or C++, but can be written in any language that supports creation of an ActiveX Automation client.

An EXE file is easy to build, can be written in many different languages, and is fairly robust. However, an EXE file must execute in a different process from the Visio instance it is controlling and must be loaded each time it is executed, which can affect performance.

• A Visio library, which is a standard Windows DLL with a prescribed Visio entry point and a .vsl file name extension.

A VSL is much faster than an EXE file because it executes in the same process as a Visio instance and is loaded once, and then executed from memory. You can also determine, within context, when the VSL is visible to the user. However, a VSL is not as robust as an EXE file—if it crashes, the Visio instance usually does too—and it must be written in C++. Also, a VSL is faster than an EXE file only if most of its processing time is spent controlling the Visio instance; if the VSL spends half or more of its time controlling another application, then a program that executes in the process of the other application might be a better choice.

• VBA macros. VBA is included with Visio products and can be used to write macros, create dialog boxes, or create class modules. Other VBA clients, such as Microsoft Word and Microsoft Excel, can be used to control Visio also.

Like a VSL, VBA macros execute in the same process as a Visio instance and are easier to write, so programmers can accomplish more in less time. VBA macros are easy to distribute, which is both an advantage and a disadvantage. Every drawing contains a copy of the VBA code, which complicates fixing bugs and adding new features.

When you use VBA macros in Microsoft Visio 2002, be sure to consider security issues. You should plan on obtaining a digital certificate and signing your VBA project with it. For details on digital certificates and digital signatures, see Using Digital Certificates to Produce Trusted Solutions in Chapter 15, Programming Visio with VBA.

• A COM add-in, which is a standard Windows DLL that is specially registered to be loaded by Visio or any Microsoft Office or Office XP application.

You can build COM add-ins with any of the Office applications in Microsoft Office Developer (version 2000 or later). If you have a Microsoft Office Developer license, you can also build COM add-ins using VBA in Visio. In addition, you can create COM add-ins with Visual Basic or C++. Like VSLs and VBA macros, COM add-ins execute in the same process as a Visio instance and are fairly easy to write.

• A hybrid approach that uses VBA in a Visio instance to load and execute Automation servers (either DLLs or EXE files) created in other languages.

The hybrid approach supports in-process execution if the Automation server is created as a DLL, and it supports a wide range of architectures. However, a hybrid approach tends to require more careful system design.

Programming Visio with VBA is discussed in chapters 14 through 26 of this guide. For details about using Visual Basic with Visio, see Chapter 27, Programming Visio with Visual Basic. For details about programming Visio with C++ and writing VSLs, see Chapter 28, Programming Visio with C++.