New ShapeSheet Cells and Functions in Visio 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.

image 

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.

image

 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.

image

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.

image   image   image
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.

 image image

If the value of FlyoutChild for B and C is TRUE, then those items appears in a flyout menu under A.

image 

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().

image 

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.