First published on MSDN on Jan, 04 2010
Our previous post introduced the improvements we made to the ShapeSheet window for shape developers. In this post, we will continue with ShapeSheet development and dig deeper to examine the new ShapeSheet cells and functions available in Visio 2010.
New Cells
A number of new cells were added to both the PageSheet and the ShapeSheet to support new features in Visio 2010 and to expand the possibilities for shape development. We will examine each one in turn.
New PageSheet cells in Visio 2010:
| Section | Cell |
| Page Layout | AvoidPageBreaks |
| Page Properties | DrawingResizeType |
New ShapeSheet cells in Visio 2010:
| Section | Cell |
| Shape Layout | DisplayLevel |
| Actions | FlyoutChild |
| Geometry | NoQuickDrag |
| Shape Layout | Relationships |
Recall that you can view the PageSheet for a page or the ShapeSheet for a shape using the Developer tab .
AvoidPageBreaks cell
This cell takes a TRUE or FALSE value and determines whether the Auto Align and Space features attempt to avoid placing shapes on page breaks. This corresponds to the Space Shapes > Avoid Page Breaks setting under the Position button on the Home tab.
DrawingResizeType cell
This cell corresponds to the Page Auto Size feature , which is found on the Design tab. It takes three values. Values 1 and 2 correspond to Auto Size on and off, respectively.
Zero is “undefined,” which is the default state for a document created in Visio 2007 or prior, since this cell doesn’t exist in those versions. This value allows Visio to determine whether Auto Size is enabled for the user. It makes a best guess by looking at the page size relative to common paper sizes and deciding whether the page size appears to have been customized, or left at a default size. If the page is at a default size, Visio enables Auto Size so users can benefit from it; if customized, Visio assumes that a specific page size was chosen for a reason and disables Auto Size. In any case, the user can change the setting by toggling the Auto Size button on the Design tab.
DisplayLevel cell
This cell defines “bands” of Z-order and is used to determine the default global Z-order position for a shape when it is added to the page. Visio uses this to place containers behind the shapes they contain, regardless of what order they are added to the page. Shapes with a higher DisplayLevel value are displayed on top of shapes with a lower value. Each value of DisplayLevel, which ranges from –32767 to +32767, defines a band.
As an example, consider a diagram with three masters, each with the DisplayLevel value shown. Regardless of what order shapes with DisplayLevel 10, 20 or 30 are dropped, the 10s will always be behind the 20s and 30s, and so forth. The blue shape shown below is at the bottom of the Z-order and was dropped before the other two shapes at DisplayLevel 10. DisplayLevel bands do not interfere with the Z-order commands on the Home tab – Bring Forward / Send Backward and Bring to Front / Send to Back. Using Bring to Front or Send to Back will initially only move the shape to the front or back of the Z-order for its band. A subsequent use will move it to the global front or back of the Z-order.
| Start with these shapes, with the given DisplayLevel values | After pressing Bring to Front on the blue shape | After pressing Bring to Front on the blue shape again |
Notice the special –32768 value, which means that the shape has been pulled out of its band. Visio stores the previous band in a formula in the DisplayLevel cell so it can be restored. Note that changing the value of the DisplayLevel cell does not change the shape’s Z-order, but the band will be taken into account the next time Visio needs to manipulate the shape’s Z-order.
FlyoutChild cell
This cell allows Actions, or custom right-click menu items, to be nested. Any menu item whose FlyoutChild value is TRUE will appear in a flyout menu of the first row above it whose FlyoutChild is FALSE. This allows one level of nesting.
The Actions section below will show the following custom items on the right-click menu.
If the value of FlyoutChild for B and C is TRUE, then those items appears in a flyout menu under A.
NoQuickDrag cell
This cell allows a shape developer to control how click and drag inside a given geometry section of a shape works. Typically, this picks up and moves a shape. By setting this cell to TRUE, you can create a non-clickable (or non-selectable) filled geometry area that prevents picking up and moving the shape. The container shapes new to Visio 2010 use this cell to allow click and drag to select shapes in the container rather than move the container.
Relationships cell
This cell stores the relationships among containers, lists, callouts and shapes. It uses a series of DEPENDSON functions , one for each different type of relationship the object has. Note that changes to this cell will not trigger actual relationship changes; Visio only uses this as a means to store the relationship information. This cell is not intended to be modified by users or shape developers.
The types of relationships are listed below.
| Value | Meaning |
| 1 | Shapes that are members of this container |
| 2 | Shapes that are members of this list |
| 3 | Callouts that are associated with this shape |
| 4 | Containers that this shape is a member of |
| 5 | List that this list item is a member of |
| 6 | Shape associated with this callout |
| 7 | Container on the left boundary edge of which this shape sits |
| 8 | Container on the right boundary edge of which this shape sits |
| 9 | Container on the top boundary edge of which this shape sits |
| 10 | Container on the bottom boundary edge of which this shape sits |
| 11 | List that this list overlaps |
A shape named Process that is a member of a container named Container 1 would have a Relationships cell formula of this form: =SUM(DEPENDSON(4,Container 1!SheetRef())) . The container’s Relationship cell would look like: =SUM(DEPENDSON(1,Process!SheetRef())) .
If the Process shape were pinned to the left edge of the container, its Relationships cell would be: =SUM(DEPENDSON(7,Container 1!SheetRef()),DEPENDSON(4,Container 1!SheetRef())) . The container’s cell would remain as listed.
A shape that is a member of two containers would look like: =SUM(DEPENDSON(7),DEPENDSON(4,Container 1!SheetRef(),Container 2!SheetRef())) , and so forth.
New Functions
We also added ShapeSheet functions that enable new developer scenarios, particularly for integrating with new Visio 2010 features.
Containers and Lists
A number of functions are designed to enable interaction with the new container and list features.
The following functions return a Sheet reference, or a reference to the shape. (Such functions exist in Visio 2007 and previous versions, such as NAME and ID.) This return value can then be used to call another function. For example, CALLOUTTARGETREF()!HASCATEGORY(“Category”) .
| Function | Description |
| CALLOUTTARGETREF() | Returns a Sheet reference to the target shape that this callout is associated with |
| CONTAINERSHEETREF(index, category) | Returns a Sheet reference to the container shape that this shape is a member of -- The 1-based Index parameter specifies which parent container to return, where the topmost container is ordered first -- If category is specified, the container must have that category in order to be returned |
| LISTSHEETREF() | Returns a Sheet reference to the list container shape that this shape is a member of |
The following functions return the number of associated shapes.
| Function | Description |
| CALLOUTCOUNT() | Returns the number of callout shapes associated with the shape |
| CONTAINERCOUNT() | Returns the number of containers the shape is a member of |
| CONTAINERMEMBERCOUNT() | Returns the number of member shapes in the container shape |
| LISTMEMBERCOUNT() | Returns the number of member shapes in the list container shape |
The following functions
| Function | Description |
| HASCATEGORY(string) | Returns TRUE if the specified string is found in the shape's categories list |
| LISTORDER() | Returns the 1-based order for the shape within a list |
In the example below, the rectangular process shape belongs to a container. It shows the total number of shapes in the container using a text field with the formula CONTAINERSHEETREF(1)!CONTAINERMEMBERCOUNT() .
Geometry Paths
Another set of functions enable detailed interaction with individual geometry paths among different shapes. Each of these functions requires a specific Geometry section to be specified – e.g., PATHSEGMENT(Sheet.1!Geometry2.Path, 0.4) . Points on a path are given as a percentage of the distance along the path.
| Function | Description |
| ANGLEALONGPATH(section, percent, segment) | Returns the tangent angle of a point on the path defined in a geometry section |
| DISTTOPATH(section, x, y) | Returns the shortest distance from the specified coordinates to a point on the path defined in a geometry section |
| NEARESTPOINTONPATH(section, x, y) | Returns the point along the path defined in a geometry section that is nearest the specified coordinates |
| PATHLENGTH(section, segment) | Returns the length of the path defined in a geometry section |
| PATHSEGMENT(section, percent) | Returns the 1-based segment number containing a point on the path defined in a geometry section |
| POINTALONGPATH(section, percent, [offset], [segment]) | Returns the coordinates of a point on or offset from the path defined in a geometry section |
| SEGMENTCOUNT(section, percent) | Returns the number of line segments that make up the path defined in a geometry section |
These functions open up a broad set of interesting shape interactions that we’re sure shape and solution developers will love. We will write a more detailed post focusing on these functions soon.
Miscellaneous
The last group of functions are various helpers that either support the new functions or fill in gaps. The first four operate on a Sheet reference.
| Function | Description |
| BOUNDINGBOXDIST(index) | Returns the measurement for the part of the shape's bounding box specified by the Index enumeration |
| BOUNDINGBOXRECT(index) | Returns the coordinate of an edge of the shape's bounding box specified by the Index enumeration |
| IS1D() | Returns TRUE if the shape is one-dimensional |
| SHEETREF() | Returns a Sheet reference for the specified shape |
| IFERROR(expression, altExpression) | Returns the evaluated result of the expression if it is not an error; otherwise returns the evaluated result of the alternate expression |
| MSOSHADE(color, deltaLum) | Modifies the color by decreasing its luminosity by the amount specified |
| MSOTINT(color, deltaLum) | Modifies the color by increasing its luminosity by the amount specified |
| VERSION() | Returns an integer value matching the current version of the Visio application |
Index enumeration for BOUNDINGBOXDIST:
| Value | Meaning |
| 0 | Width |
| 1 | Height |
| 2 | Left edge to shape pin |
| 3 | Shape pin to right edge |
| 4 | Shape pin to top edge |
| 5 | Bottom edge to shape pin |
| 6 | Center of bounding box to PinX |
| 7 | Center of bounding box to PinY |
Index enumeration for BOUNDINGBOXRECT:
| Value | Meaning |
| 0 | Left edge |
| 1 | Right edge |
| 2 | Top edge |
| 3 | Bottom edge |
We also modified the following functions that existed in Visio 2007 and prior versions. You can continue to use these as you have in the past – e.g., NAME() – or you can use them with a Sheet reference, such as Sheet.4!NAME() or CONTAINERSHEETREF(1)!NAME() .
- DATA1, DATA2, DATA3
- ID
- MASTERNAME
- NAME
- PAGENAME, BKGPAGENAME
- PAGENUMBER, BKGPAGENUMBER
- TYPE, TYPEDESC
We hope you will find these useful in opening new opportunities for shapes and making your shape development tasks easier. As always, we’re interested in your feedback and suggestions via a comment on the blog or using Send a Smile .
