Working with Document Objects

3 4

A Document object represents a drawing file (.vsd or .vdx), stencil file (.vss or .vsx), or template file (.vst or .vtx) that is open in a Microsoft Visio instance. When working with an existing drawing from a program, you'll often simply work with the active page of the active document—that is, the drawing displayed in the active drawing window. However, in some circumstances, your program might open a document for the user or retrieve a document that is open but not active.

Getting a Document Object

To get information about a document, you need to get a reference to a Document object.

Figure 16-1 Document object and related objects higher in the Visio object model.

Depending on the design of your solution, you can get a reference to the Document object in several ways. The following examples all assume that you have defined an object variable docObj (Dim docObj As Visio.Document).

• The global and Application objects have an ActiveDocument property that refers to the document in the active window regardless of the window's type. The following statement retrieves the active document in a Visio instance and assigns it to docObj :

•  Set docObj = ActiveDocument 

  As an alternative, if you've retrieved the active window, you can get the Document property of that Window object; it refers to the same Document object as does ActiveDocument.

  For details about the global object, see Using the Visio Global Object in Chapter 15, Programming Visio with VBA.

• If you know an open document's file name, you can retrieve it from the Documents collection, whether the document is active. For example:

•  Set docObj = Documents.Item("Hello.vsd") 

  The previous statement retrieves the document Hello.vsd from the Documents collection. If Hello.vsd is not open, attempting to retrieve it causes an error.

• You can use the Open method of a Documents collection to open a document if you know its path and file name:

•  Set docObj = Documents.Open("c:\Visio\Drawings\Hello.vsd") 

  This statement opens the document Hello.vsd as an original and adds it to the Documents collection.

You can open any Visio document—stencil, template, or drawing file—with the Open method, but this is not recommended for stencils and templates. The Open method opens the document as an original, rather than as a copy or read-only. An original document can be changed, which is undesirable for stencils and templates because nothing prevents the user from editing masters, altering the template's workspace, or making other potentially unwelcome changes.

To open a Visio document as read-only, use the OpenEx method. You can also use OpenEx to open:

• A copy of a document
• A copy of a document without adding its name to the Visio File menu
• A stencil docked in a drawing window
• A stencil minimized
• A document with Microsoft Visual Basic for Applications (VBA) macros disabled

For details, see OpenEx in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Getting Information about Documents

You can get information about a document by retrieving properties, such as Description, Keywords, Subject, and Title. These properties correspond to text boxes in the Properties dialog box for the document (on the File menu, click Properties).

A Document object has three properties you can use to get a document's file name:

• Name, which returns only a document's file name—for example, Hello.vsd. Until a document is saved, Name returns the temporary name of the document, such as Drawing1.
• FullName, which returns the drive, path, and file name of a document. For example, c:\Visio\Drawings\Hello.vsd. Like the Name property, until a document is saved, FullName returns the temporary name of the document.
• Path, which returns only the drive and path of a document's full name. For example, c:\Visio\Drawings\. Until the document is saved, Path returns a null string ( "" ).

These properties are read-only. To change the name, drive, or path of a document, use the SaveAs method to save the document under a different name or to a different drive or path.

You can get the status of a document by getting its ReadOnly or Saved property:

• ReadOnly returns True if a document is opened as read-only.
• Saved returns True if all of the changes in the document have been saved.

You can also get information about a Document object by getting the DocumentSheet property of the Document object. This property returns a Shape object whose Cells property returns Cell objects that contain the document's formulas. These Cell objects correspond to cells shown in a document's ShapeSheet window. For details about working with formulas, see Chapter 17, Automating Formulas.

Working with Styles in a Document

To determine what styles are available in a document, get the Styles property of a Document object. The Styles property returns a Styles collection, which represents the set of styles defined for a document. The Name property of a Style object returns the style name that appears in style lists and in the Define Styles dialog box (on the Format menu, click Define Styles).

The following example iterates through the document's Styles collection and lists the style names in a listbox on a user form:

 Sub ListStyles ()       Dim stylsObj As Visio.Styles Dim stylObj As Visio.Style       Dim styleName As String       Set stylsObj = ThisDocument.Styles       UserForm1.ListBox1.Clear       For Each stylObj In stylsObj             styleName = stylObj.Name             UserForm1.ListBox1.AddItem styleName       Next        UserForm1.Show End Sub 

Tip

---

You can change the default styles for a Document object in the Visual Basic Editor. Select the ThisDocument object in the Project Explorer and change the styles listed in the Properties window. The styles in the Properties window are: DefaultFillStyle, DefaultLineStyle, DefaultStyle, and DefaultTextStyle.

Creating a Style for a Document

To create a style from a program, use the Add method of a Styles collection and specify the name of the new style. You can optionally specify the name of a style on which to base the new style and whether the style includes text, line, and fill attributes.

For example, to create a new style named Caption based on the Normal style that includes only text attributes:

 Set stylObj = stylsObj.Add("Caption", "Normal", 1, 0, 0) 

To create a new style that is not based on another style, with text, line, and fill attributes:

 Set stylObj = stylsObj.Add("Street Sign","", 1, 1, 1) 

You can change the style's name by setting its Name property, or change whether it includes text, line, or fill attributes by setting its IncludesFill, IncludesLine, or IncludesText property. For details about creating styles, see the Microsoft Visio Help (on the Help menu, click Microsoft Visio Help). A Style object has a Cells property you can use to set formulas for ShapeSheet cells that define the style. This property returns a Cell object that corresponds to a cell in a style.

For example, to change the font size of a style:

 Set fontsizeCellObj = stylObj.Cells("Char.Size") fontsizeCellObj.Formula = "18 pt" 

For details about working with formulas, see Chapter 17, Automating Formulas.

Printing and Saving Documents

Your program can print or save the drawing it creates. For users who are comfortable with the Visio menu commands, you'll probably create the drawing from your program and leave printing and saving to the user. If not, you can handle these steps from your program.

Printing documents and pages

You can print a document or a page in a document by using the Print method.

To print all of the pages of a document, use Print with a Document object. This is equivalent to clicking All in the Print dialog box (on the File menu, click Print). To print just one page, use the Print method with a Page object. This is similar to displaying that page and clicking Current page in the Print dialog box.

When printing from Microsoft Visual Basic for Applications (VBA) or Visual Basic, you must:

• Apply the method to a variable of type Object. You cannot use a specific Visio object type.
• Apply the Print method's result to a dummy variable.

For example, to print a document:

 Dim docObj As Visio.Document Dim docObjTemp As Object Dim dummy As String Set docObj = ThisDocument Set docObjTemp = docObj dummy = docObjTemp.Print 

Saving documents

To save a document from a program, use the Save or SaveAs method of a Document object.

Use the SaveAs method and supply a file name and path to save and name a new document, to save a copy of an existing document under a different name, or to save an existing document to a different drive or path. For example:

 ThisDocument.SaveAs "c:\visio\drawings\myfile.vsd" 

Use the Save method only if the document has already been saved and named. For example:

 ThisDocument.Save 

Unlike the Save menu command in the Visio user interface, which displays the Save As dialog box if a document is unnamed, using the Save method on an unnamed document won't invoke the SaveAs method—it will cause an error.

To find out whether a document has ever been saved, check its Path property, which returns the drive and path of the document's full name or a null string ( "" ) if the document hasn't been saved. To find out whether a document has been saved since changes were made to it, check its Saved property.

Displaying Pages of a Document

In Visio, the pages of a document are displayed in a window. To display a particular page using Automation, you might expect to use a method or property of a Document object. However, to change the page that is being displayed by Visio, you actually use the Page property of the Window object. For example:

 ActiveWindow.Page = NameOfPageToDisplay 

where NameOfPageToDisplay is the valid name of a page in the document.

Note

---

You do not have to display a page in Visio in order to access it through Automation. All pages of a document are accessible from the Pages collection of the Document object regardless of whether they are displayed.

The following example displays the last page of the active document in the active window:

 Sub TurnToLastPage()       Dim szPageName As String       Dim iPageCount As Integer       'Get the page count       iPageCount = ActiveDocument.Pages.Count       'Get the name of the last page       szPageName = ActiveDocument.Pages(iPageCount).Name       'Display the last page in the ActiveWindow       'i.e. "Turn" the page       ActiveWindow.Page = szPageName    End Sub