Since Visio imports these text files via the File > Open command, it is possible to be mistaken -- as I was, initially -- that the Text Files option is for the mass importation of text. Not at all; this option actually is a clever disguise for a sophisticated conversion program. The program converts instructions written in the text file into shapes and connectors in the Visio drawing.

shape tab katrina tab furniture tab tab 4.25 tab 5.5

The documentation provided by Visio, the corporation, says you gotta use commas in text files that end in .CSV and tabs in text files that end in .TXT. It turns out that Visio, the software, isn't that fussy. While the file extension must be CSV or TXT, the field separator can be a comma, or a tab, or a semi-colon. (During importation, Visio displays a dialog box that lets you specify.) If you use a file extension other than CSV or TXT, Visio will complain variously "File not found" and "File is corrupt."

You must use a specifically-defined format of words and commas. Here is a summary of the text file format:

• Each line in the text file is a record or a comment, with one exception: you can have blank lines, which simply aid the readability of the text file.
• Each record line must conform to a specific format -- a record name, followed by one or more field values, like this:

record-name,field-value,field-value,field-value

• There is no fixed number of fields in a record; the number of fields depends on the record. For example, the Template record has a single field but the Shape record can have as many as seven or more fields.
• Some fields are optional. If you want to leave out a field, simply type the comma (or tab), such as:

master,,circle,basic.vss

You don't need the commas (or tabs) after the last field with an entry. For example, the Shape record can have seven or more fields. You can type shape,,,,,,,,, or shape -- either form of record draws a 1"x0.5" rectangle in the center of the drawing.

• You make comments in the text file by prefixing the text with a semi-colon (the default), as follows:

or these other punctuation marks: hash mark (#), exclamation (!), slash (/), or backslash (\). During importation, Visio displays a dialog box that lets you specify.

• Every record-name and field-value must be separated from the next by a comma in a CSV file, or by a tab in a TXT file.
• Quotation marks are optional. Visio interprets everything -- whether text or number -- in quotation marks as text. You may use double ( " ) or single ( ' ) quote marks; during importation, Visio displays a dialog box that lets you specify. If you don't use quotation marks, Visio interprets text as text and numbers as numbers.

Visio recognizes 12 record names in the text file. These are: Master, Shape, Link, AvenueSize, BlockSize, Gridding, LineToLineClearance, NodeToLineClearance, PlacementStyle, RoutingStyle, Property, and Template. Some of these records are required in the text file. And they must be used in the text file in this order:

Master. Specifies the VSS stencil file holding the masters.

Shape. Specifies the master to use and assigns a unique name to the shape.

Link. Specifies the names of shape pairs that have a link drawn between them.

All Master records should occur before all Shape records; all Shape records should occur before all Link records. That's because Visio has to load the stencil file (VSS) holding the masters before it can place the shapes. And Visio has to place the shapes before it can link them.

At the very minimum, the text file contains a single Shape record. When the master record is left out or cannot be found, Visio draws the shapes as a plain rectangle. As well, it is common to have shapes without links in a drawing.

The remaining records are optional and fall into two groups. Some records specify parameters for the Lay Out Shapes grid (which is a Visio option for automatically laying out the shapes in an array):

Gridding. Specifies whether to turn on the Lay Out Shapes grid. Visio automatically turns on the grid when you do not provide x,y-coordinates for the shapes.

NodeToLineClearance. Specifies the minimum distance between shape (nodes) and connectors by the Lay Out Shapes grid.

AvenueSize. Specifies the width and height of avenues in the Lay Out Shapes grid.

BlockSize. Specifies the block size in the Lay Out Shapes grid.

LineToLineClearance. Specifies the minimum distance between connectors in the Lay Out Shapes grid.

PlacementStyle. Specifies the layout style for the Lay Out Shapes grid.

RoutingStyle. Specifies the connector routing style for the Lay Out Shapes grid.

And these records have nothing to do with the grid:

Property. Defines (or redefines) custom properties for a master.

Template. Specifies the name of a Visio template file (VST) that defines the drawing's defaults, such as the size of page, the grid spacing, and number formats. A text file must contain only one Template record.

shape,shapeid,mastername,shapetext,shapex,shapey,
width,height,property1,property2,...,propertyn

Let's examine this record, bit by bit, to see what it means. The Shape record is used for any shape that is not a connector (you use the Link record for connectors).

The ShapeID is a name you give the shape. It can be as simple as the name of the person in an organizational chart. The only catch is that the name must be unique. For example, you could call the shape "Katrina" and there must be: (1) only one Shape record in the entire file with the id of Katrina; and (2) only one shape in the entire drawing called Katrina. For example:

The MasterName refers back to the name defined in the Master record. The Master record does three things: (1) lets you select the VSS stencil file; (2) lets you select the master in the stencil; and (3) lets you give a name to that master. When this field is blank or Visio cannot find the master, Visio draws the shape as a rectangle. For example:

The ShapeText is text that gets display in the shape, just as if you were to double-click the shape and type some text. This text can be anything you want and might be the name of the desk's occupant. For example:

ShapeX and ShapeY are the shape's x- and y-coordinates. These are equivalent to the PinX and PinY cells of the ShapeSheet. The x- and y-distances are measured from the page's lower-left corner to the center (typically but not always) of the shape's alignment box. To place a shape at the center of a standard 8-1/2"x11" page, specify 4.25 and 5.5. For example:

shape,katrina,furniture,Katrina Nicole,4.25,5.5,

If you don't want to spend the time figuring out the correct x,y-coordinates of each and every shape, simply leave these two fields blank -- and let Visio do the work. When the two fields are blank, Visio sets up the Lay Out Shapes grid to automatically position the shapes. For example:

shape,katrina,furniture,Katrina Nicole,,,

Width and Height define the width and height of the shape's alignment box. You can leave either or both of these fields empty, in which case Visio uses the default sizes. For example:

shape,katrina,furniture,Katrina Nicole,4.25,5.5,,,

The Propertyn field is optional. It defines one or more values for the Custom Properties section of the shape. In the previous chapter, we defined a furniture shape with three custom properties: Type, Width, Depth. You use this field to specify those properties, such as:

shape,katrina,furniture,,4.25,5.5,,,Desk,5,2.5

As we worked through the fields of the Shape record, I progressively added on to the example field values. We ended up with:

shape,katrina,furniture,,4.25,5.5,,,Desk,5,2.5

By now you should be able to read the meaning of that line of text: place a shape (with the user-defined name of katrina) using the Furniture master with no text (,,) at location x=4.25, y=5.5 on the page, using its default width and height (,,,), and filling in the Custom Property cells with the Desk label, 5 wide, and 2.5 deep.

Recall that the Furniture master's custom properties define the text label and the size of the furniture. For this reason, I left the ShapeText, Width, and Height fields empty in this record.

Earlier in this article, I noted that either shape,,,,,,,,, or shape draws a 1"x0.5" rectangle in the center of the drawing. Now you know why.