ShapeRange Collection

ShapeRange Collection
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

ShapeRange

Represents a shape range, which is a set of shapes on a document. A shape range can contain as few as one shape or as many as all the shapes in the document. You can include whichever shapes you want — chosen from among all the shapes in the document or all the shapes in the selection — to construct a shape range. For example, you could construct a ShapeRange collection that contains the first three shapes in a document, all the selected shapes in a document, or all the freeform shapes in a document.

Note   Most operations that you can do with a Shape object, you can also do with a ShapeRange object that contains only one shape. Some operations, when performed on a ShapeRange object that contains more than one shape, will cause an error.

Using the ShapeRange Collection

This section describes how to:

• Return a set of shapes.
• Return a ShapeRange object within a selection or range.
• Align, distribute, and group shapes in a ShapeRange object.

Return a set of shapes

Use Shapes.Range(index), where index is the index number of the shape or an array that contains index numbers of shapes, to return a ShapeRange collection that represents a set of shapes in a publication. You can use Visual Basic's Array function to construct an array of index numbers. The following example sets the fill pattern for shapes one through three on the active publication.

  Sub ChangeFillPattern()
    ActiveDocument.Pages(1).Shapes.Range(Array(1, 2, 3)) _
        .Fill.PresetGradient Style:=msoGradientDiagonalDown, _
        Variant:=1, PresetGradientType:=msoGradientHorizon
End Sub

Although you can use the Range method to return any number of shapes, it's simpler to use the Item method if you want to return only a single member of the collection. For example, Shapes(1) is simpler than Shapes.Range(1).

Return a ShapeRange object within a selection or range

Use Selection.ShapeRange(index), where index is the index number of the shape, to return a Shape object that represents a shape within a selection. The following example selects the first two shapes on the first page of the active publication and then sets the fill for the first shape in the selection.

  Sub ChangeFillForShapeRange()
    ActiveDocument.Pages(1).Shapes.Range(Array(1, 2)).Select
    Selection.ShapeRange(1).Fill.ForeColor.RGB = RGB(255, 0, 0)
End Sub

This example selects all the shapes on the first page of the active publication, then adds and formats text in the second shape in the range.

  Sub SelectShapesOnPageOne()
    ActiveDocument.Pages(1).Shapes.Range.Select
    With Selection.ShapeRange(2).TextFrame.TextRange
        .Text = "Shape Number 2"
        .ParagraphFormat.Alignment = pbParagraphAlignmentCenter
        .Font.Size = 25
    End With
End Sub

Align, distribute, and group shapes in a ShapeRange object

Use the Align, Distribute, or ZOrder method to position a set of shapes relative to each other or relative to the document. This example specifies a shape range and left-aligns and vertically distributes the shapes on the page.

  Sub AlignDistibuteShapes()
    Dim rngShapes As ShapeRange
    Set rngShapes = ActiveDocument.Pages(1).Shapes.Range

    With rngShapes
        .Align AlignCmd:=msoAlignLefts, RelativeTo:=msoFalse
        .Distribute DistributeCmd:=msoDistributeVertically, RelativeTo:=msoTrue
    End With
End Sub

Use the Group, Regroup, or Ungroup method to create and work with a single shape formed from a shape range. The GroupItems property for a Shape object returns the GroupShapes object, which represents all the shapes that were grouped to form one shape. This example specifies a shape range and left-aligns and vertically distributes the shapes on the page.

  Sub GroupShapes()
    Dim rngShapes As ShapeRange
    Set rngShapes = ActiveDocument.Pages(1).Shapes.Range
    rngShapes.Group

    rngShapes(1).Fill.OneColorGradient _
        Style:=msoGradientFromCenter, _
        Variant:=2, Degree:=1
End Sub