Working with Sections and Rows

You can change certain characteristics of a shape, style, page, master, or document by adding and deleting sections and rows. You can also iterate through sections or rows to perform the same operation on each item, such as listing all of a shape's Geometry formulas.

In this section�

Adding Sections and Rows

Adding a Geometry Section to a Shape: an Example

Deleting Sections and Rows

Changing the Type of a Segment

Iterating through a Collection of Sections and Rows: an Example

Adding Sections and Rows

In many cases, you'll want to add an entire section to a shape. For example, you might add a Geometry section to create a shape with multiple paths, or a Scratch section to serve as a working area for building complex formulas. Before you can use a newly added section, you need to add at least one row to the section. Depending on the kind of row you add, you might also need to set the formulas of cells in the row.

To add a section, use the AddSection method of a Shape object. For example, to add a Scratch section to a shape:

shpObj.AddSection visSectionScratch

To add a row to a section, use the AddRow method and specify the section, row, and row tag. When you add a row to a Geometry section, the row tag indicates the type of row to add—for example, visTagLineTo indicates a LineTo row. The row tag argument is primarily used to add rows to the Geometry section. For most other sections, use a row tag of zero (0) as a placeholder. For example, to add a row to a Scratch section:

shpObj.AddRow visSectionScratch, visRowScratch + 0, 0

Row tag constants are defined in the Visio type library in VisRowTags.

Row tags and the rows they represent in a Geometry section

A shape can have only one of each kind of section except for Geometry. If a shape already has a particular section and you attempt to add it, you'll get an error. You can use the SectionExists property to find out whether it has a section, and then add one if necessary.

Note You cannot add or delete rows from visSectionCharacter, visSectionParagraph, visSectionTextField, or visSectionTab.

TOP

Adding a Geometry Section to a Shape: an Example

A basic shape in a Visio drawing consists of zero or more components, or paths. Each path is a sequence of connected segments. In most shapes, a segment is either a line segment or an arc segment, which can be an elliptical arc. Each path is represented by a Geometry section, and each segment is represented by a row in a Geometry section.

To add a Geometry section to a shape, use the AddSection method with visSectionFirstComponent to insert the section before existing Geometry sections, or visSectionLastComponent to append the section after existing Geometry sections. For example, to add a Geometry section after existing Geometry sections:

shpObj.AddSection visSectionLastComponent

After adding a Geometry section, you must add at least two rows (rows are not added automatically to a section added from a program). Use the AddRow method with the following row tags:

• visTagComponent determines display properties of the component defined by the Geometry section. This should be the first row of every Geometry section.

• visTagMoveTo, visTagEllipse, or visTagInfiniteLine determines the first vertex, or starting point, of the component. This should be the second row of every Geometry section. A visTagEllipse or visTagInfiniteLine row will also be the final row because ellipses and infinite lines are represented by single-row sections.

You can add additional vertex rows using the row tags visTagLineTo, visTagArcTo, visTagEllipticalArcTo, visTagMoveTo, visTagPolylineTo, or visTagNURBSTo. Each vertex row defines the local coordinates of a vertex and the type of segment that connects the vertex with the previous one.

You can add spline rows using the row tags visTagSplineBeg and visTagSplineSpan. Precede the spline start row (visTagSplineBeg) with a start row (visTagMoveTo) or a vertex row, and use visTagSplineSpan to add spline knot rows.

The following procedure inserts a Geometry section before other existing Geometry sections of a shape. It adds the component row, the MoveTo row, and four LineTo rows. (These are the rows you typically need to define a straight line.) It then sets cell formulas in each row to draw the line diagonally across the shape's width-height box.

Sub AddGeometry ()     Dim shpObj As Visio.Shape     Dim iSection As Integer     Dim i As Integer     'Set an error handler to catch the error if no shape is selected     On Error GoTo errNoShp     Set shpObj = ActiveWindow.Selection(1)     On Error GoTo 0     iSection = shpObj.AddSection(visSectionFirstComponent)     shpObj.AddRow iSection, visRowFirst + 0, visTagComponent     shpObj.AddRow iSection, visRowVertex + 0, visTagMoveTo     For i = 1 To 4         shpObj.AddRow iSection, visRowVertex + i, visTagLineTo     Next i     shpObj.CellsSRC(iSection, visRowVertex + 0, visX).Formula = "Width * 0.25"     shpObj.CellsSRC(iSection, visRowVertex + 0, visY).Formula = "Height * 0.5"     shpObj.CellsSRC(iSection, visRowVertex + 1, visX).Formula = "Width * 0.5"     shpObj.CellsSRC(iSection, visRowVertex + 1, visY).Formula = "Height * 0.25"     shpObj.CellsSRC(iSection, visRowVertex + 2, visX).Formula = "Width * 0.75"     shpObj.CellsSRC(iSection, visRowVertex + 2, visY).Formula = "Height * 0.5"     shpObj.CellsSRC(iSection, visRowVertex + 3, visX).Formula = "Width * 0.5"     shpObj.CellsSRC(iSection, visRowVertex + 3, visY).Formula = "Height * 0.75"     shpObj.CellsSRC(iSection, visRowVertex + 4, visX).Formula = "Geometry1.X1"     shpObj.CellsSRC(iSection, visRowVertex + 4, visY).Formula = "Geometry1.Y1"     'Exit the procedure bypassing the error handler     Exit Sub errNoShp:     MsgBox "Please select a shape then try again.", vbOKOnly, DVS_TITLE End Sub

The following illustration shows the shape before and after inserting the Geometry section.

Inserting a Geometry section in a shape

Notice that visRowVertex with no offset, or with an offset of zero (0), refers to the MoveTo row. When adding vertex rows, always add an offset of 1 or more to visRowVertex so you don't inadvertently replace the MoveTo row, which can cause the shape to behave in unexpected ways. You can insert additional MoveTo rows in a single Geometry section to create a gap. For details about working with formulas in the Geometry section, see Chapter 5, Controlling Shape Geometry with Formulas or search for "Geometry section" in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

TOP

Deleting Sections and Rows

Deleting a section automatically deletes all of its rows and cells. You can delete any section except visSectionObj, although you can delete rows in that section. To delete a section, use the DeleteSection method of a Shape object. For example, the following statement deletes the Scratch section of a shape:

shpObj.DeleteSection visSectionScratch

Deleting a nonexistent section does not cause an error.

You can also delete a row from a section. For example, you can remove a vertex from a shape by deleting the row that defines the vertex from the shape's Geometry section. The following statement deletes the last vertex of a rectangle:

shpObj.DeleteRow visSectionFirstComponent + 0, visRowVertex + 3

Note You cannot add or delete rows from visSectionCharacter, visSectionParagraph, visSectionTextField, or visSectionTab.

Deleting a vertex row

1. This vertex is represented by visRowVertex + 3.

1. After deleting the vertex row, the shape changes in appearance.

TOP

Changing the Type of a Segment

You can define a segment as a line, arc, elliptical arc, spline, ellipse, infinite line, polyline, NURBS (nonuniform rational B-spline), or MoveTo row by setting the type of row or rows that represent the segment. From a program, you can do this by setting the RowType property of a Shape object.

For example, the following statement converts the first segment of a shape to a line segment.

shpObj.RowType(visSectionFirstComponent + 0, visRowVertex + 1) = visTagLineTo

Changing the row type of a vertex row

1. This arc segment is represented by visRowVertex + 1.

1. After the row type is changed, the shape changes in appearance.

TOP

Iterating through a Collection of Sections and Rows: an Example

You can perform the same operation on multiple sections or rows by iterating through them, using the following Shape object properties to limit the iteration loop:

• GeometryCount represents the number of Geometry sections for a shape.

• RowCount represents the number of rows in a section.

• RowsCellCount represents the number of cells in a row.

The following example iterates through the rows and cells in a shape's Geometry section and uses the CellsSRC property to retrieve each cell. It then displays each cell's formula in a listbox on a user form.

'This example assumes the active 'page contains a shape Sub IterateGeometry ()     'Shape object     Dim shpObj As Visio.Shape     'Section number for accessing Geometry section     Dim curGeomSect As Integer     'Loop variable for Geometry sections     Dim curGeomSectIndx As Integer     'Number of rows in section     Dim nRows As Integer     'Number of cells in row     Dim nCells As Integer     'Current row number (0 based)     Dim curRow As Integer     'Current cell index (0 based)     Dim curCell As Integer     'Number of Geometry sections in shape     Dim nSects As Integer

    Set shpObj = ActivePage.Shapes(1)     UserForm1.ListBox1.Clear     nSects = shpObj.GeometryCount     For curGeomSectIndx = 0 To nSects - 1         curGeomSect = visSectionFirstComponent + curGeomSectIndx         nRows = shpObj.RowCount(curGeomSect)         For curRow = 0 To (nRows - 1)             nCells = shpObj.RowsCellCount(curGeomSect, curRow)             For curCell = 0 To (nCells - 1)                 UserForm1.ListBox1.AddItem _                 shpObj.CellsSRC(curGeomSect, curRow, curCell).LocalName & _                 ": " & shpObj.CellsSRC(curGeomSect, curRow, curCell).Formula             Next curCell         Next curRow     Next curGeomSectIndx     UserForm1.Show End Sub

For a list of logical position constants, see Appendix B, ShapeSheet Section, Row, and Cell Indices.