Working with Shape Objects

  • Article

The most fundamental Microsoft® Visio® object that you will work with is the Shape object. A Shape object represents a basic shape, a group, a guide or guide point, or a linked or embedded object. A Shape object can also represent the formulas of a page, master, or document. A Shapes collection represents all of the Shape objects on a drawing page, in a group, or in a master.

In this section…

Getting a Shape Object

Getting Information about a Shape

Creating and Changing Shapes

Adding Text to Shapes

Getting a Shape's Text

Identifying and Applying Styles to Shapes

Preserving Local Formatting

Creating Groups from a Program

Creating Masters

Getting a Shape Object

To get information about a shape, you need to get a reference to the Shape object. To do this, you must first get a reference to the Shapes collection of the object that contains the shape in which you are interested.

Shape object and related objects higher in the Visio object model

Shape object and related objects higher in the Visio object model

To get a Shapes collection of a page, get the Shapes property of the Page object. To get a Shapes collection of a master, get the Shapes property of the Master object. If a Shape object represents a group or the sheet for a page or master, that Shape object also has a Shapes property.

You can get a Shape object from a Shapes collection by its index within the collection, by its name, or by its unique ID.

Getting a shape by its index

The order of items in a Shapes collection is the same as the order in which the shapes were drawn. The first item in a Shapes collection is the shape farthest to the back on the drawing page (the first shape drawn), and the last item is the shape closest to the front (the last shape drawn). For example, to get the shape closest to the front on the page:

shpIndex = shpsObj.Count Set shpObj = shpsObj.Item(shpIndex)

Getting a shape by name or unique ID

A Shape object has three properties that identify the shape—Name, NameID, and UniqueID.

Name returns shapeName[.nnnn]. The name of the shape is shapeName; you can set this name either by using the Name property or by typing a name in the Special dialog box (on the Format menu, click Special).

If you do not assign a name to a shape, the Name property returns one of the following values:

  • If the shape is the first or only instance of a particular master on a page or in a group, shapeName is the name of the master with no ID number. For example, Decision.
  • If the shape is a second or subsequent instance of a particular master on a page or in a group, shapeName is the name of the master followed by the shape's ID number. For example, Decision.43.
  • If the shape is not an instance of a master, shapeName is Sheet followed by the shape's ID number. For example, Sheet.34. In this case, the Name and NameID properties of the shape return the same string.

Set shpObj = shpsObj.Item("Desktop PC")

NameID returns Sheet.n where n is an integer ID of the shape—for example, Sheet.34. This ID is assigned to the shape when it is created on a drawing page and is guaranteed to be unique within the shape's page or master. For example, to get a shape whose ID is 5:

Set shpObj = shpsObj.Item("Sheet.5")

UniqueID(visGetGUID) returns the shape's unique ID if it has one. You can work with unique IDs only from a program—you can't access them in the Visio user interface. Most often, unique IDs identify shapes that have corresponding records in a database. For example, an office floor plan might have dozens of identical desk, chair, and PC shapes, but you can use the unique ID of each shape to associate a particular shape in the floor plan with a particular record in a facilities database.

A shape doesn't have a unique ID until a program generates one for it. By contrast, a master always has a unique ID, generated by the Visio engine. A unique ID is stored internally as a 128-bit value, but the Visio engine returns this value as a string. You can pass the unique ID string with the Item property to get a shape by its unique ID. For example:

Set shpObj = shpsObj.Item("{667458A1-9386-101C-9107-00608CF4B660}")

For more details about unique IDs for shapes and masters, see Chapter 20, Integrating Data with a Visio Solution.

TOP

Getting Information about a Shape

Because a Shape object can represent more than just a basic shape, you might need to determine its type. A Shape object has a Type property that indicates the type of shape it is. The values returned by the Type property are represented by the following constants defined in the Microsoft® Visio® type library:

  • visTypeShape identifies a shape that is not a group, such as a line, ellipse, or rectangle, including shapes with multiple paths.
  • visTypeGroup identifies a group. A group can contain shapes, groups, foreign objects, and guides.
  • visTypeForeignObject identifies an object imported, embedded, or linked from another application.
  • visTypeGuide identifies a guide or guide point.
  • visTypePage identifies a shape containing properties of a page or master.
  • visTypeDoc identifies a shape containing properties of a document.

An instance of a master can be a basic shape or a group, depending on how the master was created.

In the Shapes collection of a Page object, each group counts as a single shape. However, a group has a Shapes collection of its own. The following function counts the shapes on a page, including those in groups (but not the groups themselves), by iterating through the Shapes collection of a Page object. The following function also checks the Type property of each Shape object to see whether the shape is a group. If Type returns visTypeGroup, the example retrieves the number of shapes in the group and adds that number to the total number of shapes.

Function ShapesCount (root As Object) As Integer     'Return value     Dim iCount As Integer     'Shapes collection    Dim shpsObj As Visio.Shapes
    'Shape object
    Dim shpObj As Visio.Shape

    iCount = 0     'Assumes root.Shapes is a group or a page     Set shpsObj = root.Shapes             For Each shpObj In shpsObj         If shpObj.Type = visTypeGroup Then             iCount = iCount + ShapesCount(shpObj)         Else             iCount = iCount + 1         End If     Next     ShapesCount = iCount End Function

TOP

Creating and Changing Shapes

Most of the work your program does will be with shapes—creating new shapes or changing the way shapes look. You'll often create shapes by dropping masters onto a drawing page, as described in Chapter 18, Drawing with Automation.

Creating new shapes

You can draw lines, ellipses, and rectangles from a program by using the DrawLine, DrawOval, and DrawRectangle methods of a Page object. When you draw lines, ovals, and rectangles instead of dropping a master, you supply coordinates for the two opposite corners of the width-height box for the new shape.

Creating shapes with the DrawLine, DrawRectangle, and DrawOval methods

Creating shapes with the DrawLine, DrawRectangle, and DrawOval methods

  1. pagObj.DrawLine 1,9,3,10
  1. pagObj.DrawRectangle 1,6,3,7
  1. pagObj.DrawOval 1,3,3,4

The order in which you specify the corners doesn't really matter when you draw ellipses and rectangles. However, the order does matter for lines. It's often important to know which end of a line is the begin point and which is the end point.

For example, you might want to apply a line style that formats a line's end point with an arrowhead, or glue a line's begin point to another shape. When you draw a line from a program, the first x,y coordinate pair determines the line's begin point, and the second x,y coordinate pair determines the line's end point—the same as when you draw a shape with the mouse.

You can also draw shapes using the DrawBezier, DrawNURBS, DrawPolyline, and DrawSpline methods. For details about these methods, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Modifying shapes

You can also draw original shapes and modify existing shapes, or change a shape's appearance and behavior, by setting its formulas. A Shape object has a Cells property that returns a Cell object containing a formula.

For example, to hide the text of a shape:

Set celObj = shpObj.Cells("HideText") celObj.Formula = "True"

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

Copying, cutting, deleting, and duplicating shapes

You can copy, cut, delete, and duplicate shapes using the Copy, Cut, Delete, and Duplicate methods of a Shape object. These methods work in the same way as the corresponding menu commands in the Visio user interface. You can use these methods with a Shape object whether or not the corresponding shape is selected in the drawing window.

To duplicate a shape at a particular location on the page, use the Drop method for a Page object. You supply a reference to the shape you want to duplicate and to the coordinates where you want to position the shape's pin. For example:

Set shpObj = pagObj.Shapes("Sheet.1") pagObj.Drop shpObj,1,2

To paste shapes from the Clipboard, use the Paste method of a Page object. For details about pasting from the Clipboard, see the Paste method in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

TOP

Adding Text to Shapes

You'll often set a shape's text from the program rather than provide it as part of a master. You can add text to a shape or change existing text by setting the Text property of a Shape object to a string expression. For example:

shpObj.Text = "Twinkle"

To include quotation marks in the text, use two quotation mark characters ("") to enclose the string. For example:

shpObj.Text = """Are you currently a customer of XYZ?"""

To control where lines break in text, use the Microsoft® Visual Basic® Chr$ function to include an ASCII linefeed with the string. For example:

shpObj.Text = "Twinkle," & Chr$(10) & "twinkle" & Chr$(10) & "little star"

Set the Text property of a Shape object to add text to the corresponding shape

Set the Text property of a Shape object to add text to the corresponding shape.

To work with part of a shape's text, get the shape's Characters property, which returns a Characters object. You set the Begin and End properties of the Characters object to mark the range of text with which you want to work.

A shape's text is contained in its text block and is positioned in its own coordinate system relative to the shape. You can control the size and position of a shape's text block by setting formulas in the shape's Text Transform section. For details about working with formulas, see Chapter 17, Automating Formulas. For techniques you can use in Visio to change a shape's text block and control text behaviors, see Chapter 9, Designing Text Behavior.

TOP

Getting a Shape's Text

The Text property of a Shape object returns a string containing the text displayed in the shape. If a shape's text contains fields, such as a date, time, or custom formulas, the string returned by the shape's Text property contains an escape character (hex 1E, decimal 30), not the expanded text that is displayed for the fields.

If you want the shape's text with fields fully expanded to what they display in the drawing window, get the shape's Characters property and then get the Text property of the resulting Characters object. You can also get a subset of the shape's text by setting the Begin and End properties of the Characters object.

Fields in a shape's text evaluate to the results of formulas you can view in the shape's Text Fields section. Use the FieldFormula and related properties of the Characters object to control fields in a shape's text.

Note In versions earlier than Visio 2000, the string returned by a shape's Text property contained a 4-byte field code that began with an escape character. The next three bytes contained the FieldCategory, FieldCode, and FieldFormat values for the field. Beginning with Visio 2000, only a single escape character is stored and FieldCategory, FieldCode, and FieldFormat are stored in the Fields.UICat[i], Fields.UICod[i], and Fields.UIFmt[i] cells in the shape's Text Fields section. (These cells do not appear in the ShapeSheet window.) Field code constants are defined in the Visio type library under visFieldCodes.

In addition to the text displayed in the shape, there are other parts of a shape that may contain text:

  • A shape may contain text in user-defined cells or custom properties. To access this text, use the Formula property of the Cell object that contains the text.
  • A shape may contain text in its Data1, Data2, and Data3 fields, which appear in the Special dialog box for that shape (on the Format menu, click Special). To access this text, use the Data1, Data2, and Data3 properties of the Shape object.

TOP

Identifying and Applying Styles to Shapes

A Shape object has properties that identify the text, line, and fill styles applied to that shape:

  • TextStyle identifies a shape's text style.
  • LineStyle identifies a shape's line style.
  • FillStyle identifies a shape's fill style.

You can get these properties to determine a shape's text, line, or fill style, or you can set these properties to apply styles to the shape.

You can also set the Style property to apply a multiple-attribute style to a shape. If you get a shape's Style property, however, it returns the shape's fill style, because a property cannot return multiple objects. For more details, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

TOP

Preserving Local Formatting

Your program or your user can apply specific formatting attributes to a shape in addition to its text, line, or fill styles. This kind of formatting is called local formatting. If you apply a style to that shape later, the style overrides the local formatting unless you preserve it.

To preserve local formatting when applying a style from a program, use one of the following properties instead of FillStyle, LineStyle, or TextStyle:

  • FillStyleKeepFmt
  • LineStyleKeepFmt
  • TextStyleKeepFmt
  • StyleKeepFmt

These properties correspond to selecting the Preserve local formatting check box in the Style dialog box (on the Format menu, click Style).

TOP

Creating Groups from a Program

A group is a shape composed of other shapes. To create a group from a program, use the Group method of a Window object or a Selection object. The following statement creates a group from the selected shapes in a drawing window:

winObj.Group

The Group method creates a group from selected shapes

The Group method creates a group from selected shapes.

To add a shape to a group, use the Drop method of a Shape object that represents the group, with a reference to the shape you want to add and to a position inside the group. For example:

grpObj.Drop shpObj, 0.375, 0.125

Use a group's Drop method to add a shape to the group

Use a group's Drop method to add a shape to the group.

  1. 0,0
  1. 0.375, 0.125
  1. grpObj
  1. shpObj
  1. grpObj after grpObj.Drop

The coordinates 0.375, 0.125 are expressed in local coordinates of the group. If the shape that's being dropped is a Master object, the pin of the master is positioned at those coordinates. If the shape that's being dropped is a Shape object, the center of the shape's bounding box is placed at these coordinates.

You can control the behavior of a group by setting formulas in the shape's Group Properties section. For details about working with formulas, see Chapter 17, Automating Formulas.

TOP

Creating Masters

To create masters from a program, you drop a shape from a drawing page into a document (often a stencil), as you do when creating a master with the mouse. Supply a reference to the Shape object that you want to make into a master using the document's Drop method. Before you can drop a Shape object in a stencil, the stencil must be opened as an original rather than read-only, as is typically the case when a stencil is opened by a template (.vst or .vtx) file. To open a stencil as an original, use the Open method. For example:

Dim stnObj As Visio.Document Dim shpObj As Visio.Shape Set stnObj = Documents.Open("Basic Shapes.vss") stnObj.Drop shpObj, 0, 0

A master often consists of several components, which, for best performance, should be grouped. You are not required to group components of a master in a stencil. However, if they are not, the Visio engine automatically groups the shapes when the master is dropped in a drawing. This increases the time required to create an instance of the master.

Note In addition to Shape and Master objects, the Drop method accepts Selection objects, or any object that provides an IDataObject interface. For details about the Drop method, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).