Understanding EventXFMod

[Visisthebest]

When gluing 2D shapes via their connection points, I see formulas like these:

=LOCTOPAR(PNT(Rectangle!Connections.X1+0 mm,Rectangle!Connections.Y1+18.5758 mm),Rectangle!EventXFMod,EventXFMod)

The part I don't grasp is the EventXFMod shapesheet "function", Microsoft writes:
https://learn.microsoft.com/en-us/office/client-developer/visio/eventxfmod-cell-events-section

That's too abstract for me, in the formula above what is it used and useful for. Other uses are also good to know to understand better the how and why of EventXFMod.

Thank you for sharing your insights!

[wapperdude]

The Event references do nothing.  They are not evaluated.  Check out the syntax of the LocToPar() fcn.  Their presence merely establishes the identity of the source and destination shapes.  Consider, for example, LOCTOPAR(PNT(LocPinX, LocPinY), Width, Sheet.4!Width).  This is about evaluating the LocPin  values.  The width values of either shape are inconsequential... never evaluated.

[vojo]

I thought the sheet references in your example is to let visio calculate and translate from on ordinal system to the other ordinal system.

Width cell to Width cell is used as an absolute scaling ratio.
I do not believe just doing a pin to pin can give an absolute scale in and of itself.

[wapperdude]

Perhaps an example or two would be helpful.  Attached file has two examples.  Example two is shown in PNG file attachment.

Couple things of note:
1) the formulas for source and destination shapes do not have to be identical cells.
2) the referenced cells do not have to have formulas or values or be dimensional entries.

Open the shapesheet of the purple shape and look at the entries referenced. 

@Vojo:  I would agree that there must be some correspondence factor between the two systems.   It would need to be 2-dimensional.  However, the syntax doesn't allude to 1 or more dimensionality.  The formula doesn't supply that information.  Visio gets it by some other means.  I think the examples show that to be the case.   It took me quite awhile to reconcile the operation of the LocToPar and LocToLoc fcns.

[Visisthebest]

Thank you Wapperdude, and good to understand EventXFMod is just used like a simple boilerplate reference for functions like LOCTOPAR that require such references.

[vojo]

cells like width or height have implied dimensions.  I dont believe you could use  user.srce and user.dest as the reference cells in loc<xxx> functions because they do not guarantee a dimensionality to the value.

I dont know if one gets real creative with the setatref<xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx> functions where you could force a dimensionality on some user cells because the value can be echoed to some user cell.......never tried that.

[wapperdude]

i dont understand your reply.  There are no User.srce/dest  cells.  The User rows are merely placeholders for entire LocToPar functions.
These entries allow comparison of results and to exploration of LocToPar functionality.  Look at the Visio file.  The results are both clear and surprising.  There is no dimensionality in the formula.  There is no requirement to refer to cells that have dimensionality.  Indeed, it is perfectly fine to refer to cells that are empty, void of any content.  Or, unlikely, I discovered a major, fundamental bug.

Note, on 1st page example, there is a data formatting error for LocPinX value in 2nd row.  All values had format set to 3 decimal places except that singular result.  So, it appears a bit different in value, but in actuality, it is not.

[wapperdude]

John Goldsmith does one of the better discussions on Visio transform functions in this article:  https://visualsignals.typepad.co.uk/vislog/2023/01/loctoloc-and-loctopar-understanding-visio-transform-functions.html

[vojo]

the loctopar (a,b,x,y) or loctoloc (a,b,x,y)....use x,y to translate the local to remote "space"

The whole thing about setatexpref is about the trick of using that to do two things in 1 formula
1) set the value for some actual behvior
2) take that value and also place it in a cell....user, scratch, etc

Example1
Let's say that a shape has a custom property called Width, and that the Width cell in the Shape Transform section contains the following formula:

=SETATREF(Prop.Width)

If a user were to change the shape's width in the UI, the new value is assigned to the Prop.Width cell, not to the Width cell in the ShapeTransform section; the formula in the Width cell remains unchanged. You can also set the shape's width by using shape data.

Example2
Visio solutions often have shapes that have a hierarchical relationship, requiring child shapes to move when a parent shape is moved. Following is an example of how you might manage this relationship using the SETATREF function in the ShapeSheet.

The following formulas are contained in the Shape Transform section of the child shape. Also, we define user cells called User.DeltaX and User.DeltaY, which track the offset dimension from ParentShape. This allows the child shape to move when the parent shape is moved, and also to preserve the hierarchical relationship if the child shape is moved.

PinX =SETATREF(User.DeltaX, SETATREFEVAL(SETATREFEXPR() - ParentShape!PinX)) + ParentShape!PinX

PinY =SETATREF(User.DeltaY, SETATREFEVAL(SETATREFEXPR() - ParentShape!PinY)) + ParentShape!PinY

When the child shape is moved using the UI, the new PinX and PinY values are set as the parameter in the SETATREFEXPR function. The SETATREF function evaluates the formula enclosed in SETATREFEVAL and replaces PinX and PinY with their results, and then the resulting formula is assigned to the user cells referenced in the SETATREF function—User.DeltaX and User.DeltaY. Lastly, the values returned by SETATREF (User.DeltaX or User.DeltaY) are added to the pin

[hidden layer]

We do not glue 2 shapes on each other we glue one shape to another. In other words: "  the child choose it's parent by moving (its own connection point to the parent's connection point) ". If we move the parent the child follows. If we move the child the parent doesn't.
The EventXFMod will be triggered by visio if one of the shapes change its position, size or orientation.
That's why the formula is like this - it triggers visio to check the child's position and orientation if the parent has been moved or rotated.
A bit more colloquial?

That doesn't explain (to me) why the child's EventXFMod - cell will be triggered as well, but that's could explain the LocToPar function.

[wapperdude]

The EventXFmod explanation sounds logical, but doesn't explain why substitute entries, e.g., width, fillforegnd, also work.  Plus, nor why non-identical cell references are fine.  The LoctoPar function plainly defines the two entries
  > srcRef:  A reference to a cell in the source object.
  > dstRef:  A reference to a cell in the destination object.

Those entries are merely a means to establish whom the source and destination shapes are.  The mechanism of how the function works is buried in its underlying code.  But all of the preceding examples/tests show that the chosen cell is neither significant nor evaluated.  The cell merely specifies the reference shape.