Layers

3 4

A page can have layers, which you can use to organize the shapes on a page. You assign shapes to a layer to work with named categories of shapes—to show them or hide them, print them or not, or protect them from changes—without having to place the shapes on a background page or incur the overhead of grouping them. A shape's layer is independent of its stacking order or even its membership in a group.

A master can be associated with layers. When a master with layers is dropped in a drawing, the instance of that master is assigned to those layers on the page. If the layers don't already exist, the Microsoft Visio instance creates them. When you work with layers from a program, you can find out which layers are available in a drawing page or master, and which layers a shape is assigned to in a drawing. You can assign shapes to layers, add layers, and delete layers. You can also show or hide a layer, make it printable or editable, and change other layer settings, similar to the way you set layer properties in the Layer Properties dialog box or the Layers section of a ShapeSheet window.

Identifying Layers in a Page or Master

To identify the layers defined for a page or master, get its Layers property. This property returns a Layers collection, which contains a Layer object for each layer defined for the page or master. If the page or master has no layers, its Layers collection is empty. A Layer object has a Name property that returns the name of the layer as a string. This is the default property of the object.

You access a Layer object from the Layers collection by name or by index. For example, to get a Layer object for the layer named "Plumbing":

 Set layerObj = layersObj.Item("Plumbing") 

The following example gets all the layers in a collection of the active page and prints their names in the Visual Basic Editor Immediate window:

 Sub GetLayers ()       Dim layersObj As Visio.Layers       Dim layerObj As Visio.Layer       Dim layerName As String       Set layersObj = ActivePage.Layers       For Each layerObj In layersObj              layerName = layerObj.Name             Debug.Print layerName       Next  End Sub 

As in most collections, objects in the Layers collection are indexed starting with 1. Each layer in the collection is represented by one row in the Layers section of the page or master.

A Layer object's Index property tells you the index of a layer in the Layers collection. A Layer object's Row property tells you the corresponding row in the Layers section of the page sheet. These are usually different numbers.

Identifying the Layers to Which a Shape is Assigned

Use the LayerCount property of a Shape object to get the total number of layers to which the shape is assigned, and then use the Shape object's Layer property to get a particular layer. For example, the following statement gets the second layer to which the shape is assigned:

 Set layerObj = shpObj.Layer(2) 

Check the properties of the Layer object, such as Name, to find out more about that layer.

If the shape is not assigned to any layer, its LayerCount property returns zero (0), and getting its Layer property causes an error.

Assigning Shapes to and Removing Shapes from Layers

To assign a shape to a layer, use the Add method of the Layer object. For example:

 layerObj.Add shpObj, preserveMembersFlag 

The preserveMembersFlag argument should be non-zero (True) if you're assigning a group to the layer but you don't want to affect the layer membership of shapes within that group. Otherwise, use 0 (False) to assign a single shape or a group and each of its members to that layer.

To remove a shape from a layer, use the Remove method of the Layer object. The arguments are the same for removing a layer as for adding one. For example:

 layerObj.Remove shpObj, preserveMembersFlag 

Adding Layers to and Deleting Layers from Pages and Masters

To add a layer to a page or master, use the Add method of the Layers collection of a Page object or Master object. For example, use the following statements to add a new layer named "Plumbing" to a page:

 Set layersObj = pagObj.Layers Set layerObj = layersObj.Add("Plumbing") 

The name of the new layer must be unique to the page or the master. If it succeeds, the Add method returns a Layer object that represents the new layer.

To delete a layer from a page or master, use the Delete method of the Layer object. For example:

 layerObj.Delete deleteShapesFlag 

The deleteShapesFlag argument should be non-zero (True) to delete the shapes assigned to the layer. Otherwise, use 0 (False) to retain the shapes. The shapes' layer assignments are updated so that they no longer refer to the deleted layer.

Changing Layer Settings

You can change settings in the Layer Properties dialog box to make a layer visible or printable or to set its highlight color, among other things.

You change layer settings from a program by setting the formulas of cells that control these settings. To do this, use the CellsC property of a Layer object to get the cell that controls the setting you want to change, and then set the formula of that cell.

For example, to access the cell that contains the layer's name, use a statement such as the following:

 Set layerCellObj = layerObj.CellsC(visLayerName) 

Tip

---

You can also access layer settings by using the CellsSRC property of a Shape object that represents a page sheet. The CellsSRC property represents a ShapeSheet cell identified by section, row, and column indices. For details, see Chapter 17, Automating Formulas.

To determine whether a layer is visible, use statements such as the following:

 If layerObj.CellsC(visLayerVisible).ResultIU = 0 Then       text1.Text = "invisible" Else       text1.Text = "visible" End If 

To hide a layer:

 Set layerCellObj = layerObj.CellsC(visLayerVisible) layerCellObj.Formula = False or 0 

The constants visLayerName and visLayerVisible are defined in the Visio type library. For a list of constants that control layer settings, see Appendix B, ShapeSheet Section, Row, and Cell Indices. For details about changing layer settings in Visio, see the Microsoft Visio Help (on the Help menu, click Microsoft Visio Help).