LocToLoc, LocToPar and Just Plain PAR ShapeSheet Functions

[visProcessEng]

It seems to me these key functions ("LocToLoc", "LocToPar" and Just Plain "PAR") are not well documented.  I imagine there is tremendous power lurking somewhere in the following seemingly meaningless and or redundant Descriptions and examples from MSDN (Thanks Guys!).  I have not been able to find anything more helpful than this so here we go.

==================From MSDN ==================

LOCTOLOC Function [Visio 2003 SDK Documentation]
Returns a transformed point in local coordinates in the destination coordinate system.

LOCTOLOC(srcPoint, srcRef, dstRef)

srcPoint A point in local coordinates in the source coordinate system.

srcRef A reference to a cell in the source object.

dstRef A reference to a cell in the destination object.

Remarks
The LOCTOLOC function converts a point from local coordinates in a source shape to local coordinates in a destination shape. You can use this function to construct a shape, for example, in terms of a point from another coordinate space. You can also use this function to transform a local point to page coordinates, or vice versa.

This function works even when the source and destination shapes are within groups. It also adjusts for rotation and flips in the intermediate transformation.

The source and destination coordinates must be on the same page.

Example
LOCTOLOC(PNT(LocPinX, LocPinY), Width, ThePage!PageWidth)

Converts the local pin of the shape associated with the formula to a point on the page.




LOCTOPAR Function [Visio 2003 SDK Documentation]
Returns a transformed point in parent coordinates in the destination coordinate system.
==============================

LOCTOPAR(srcPoint, srcRef, dstRef)

srcPoint A point in local coordinates in the source coordinate system.

srcRef A reference to a cell in the source object.

dstRef A reference to a cell in the destination object.

Remarks
Converts a point from local coordinates in a source shape to parent coordinates in a destination shape. You can use the LOCTOPAR function to set parent coordinates in cells, such as PinX, PinY, BeginX, and BeginY in a shape using another point from another coordinate system.

This function works even when the source and destination shapes are within groups. It also adjusts for rotation and flips in the intermediate transformation.

The source and destination coordinates must be on the same page.

If the destination is a page, which has no parent, the result is expressed in the page's local coordinates.

Example
LOCTOPAR(PNT(LocPinX, LocPinY), Width, Sheet.4!Width)

Converts the local pin of the shape associated with the formula to parent coordinates of Sheet.4.

=======================================

Lastly for Just Plain "PAR" here is at least a decent explaination of "PNT" the understanding of which is a prerequisit for what follows.

PAR Function [Visio 2003 SDK Documentation]
Returns the x,y coordinates of a point in the coordinate system of the shape's parent.

PAR(point)


Remarks
In Microsoft Office Visio, a point is a single value that embodies a pair of x- and y-coordinates. If the shape is in a group, its parent is the group. If the shape is not in a group, its parent is the page.

Example
PAR(PNT(PinX,PinY))

In this expression, PNT converts a pair of coordinates in the current shape into a point. PAR then converts the point into a pair of coordinates in relation to the lower-left corner of the page or group that contains the current shape.




Before I continue,  I will share somthing which I discovered about the long forgotten "Scratch" section.  References made in the ScratchX and Y seem to be shown in Parent Coordinate Reference.  Anyway in what follows I will be using "Scratch" sections.  I suspect that what follows would work if the formulas used are entered in say a Geometry Section, but I find the additional translation difficult to follow (Pea Brained).

If you are interested in following along.  Please open a new visio drawing page.  To this page add a single circle THEN add a single rectangle.  Open that circles ShapeSheet, within the ShapeSheet add a Geometry Section (we will use it for something). Then add a Scratch Section. 

Into the Geometry 2 section (Geometry2.X1) moveto cell X insert =Geometry1.X1

Into the Geometry 2 section (Geometry2.Y1) moveto cell Y insert =Geometry1.Y1

This starts the Line that will be drawin by Geometry 2 from the center of the Circle (it is ok if you choose to draw an ellipse, but I don't want to type ellipse over and overagain so just forget HS Geometry for a minute). 

Now we turn our attention to the Scratch and the subject at hand. 

Let me for a moment laud one other thing about Scratch, when you add rows they add from the top (I LOVE That, not sure why but I do).

Let's use the examples lifted from MSDN and see what happens.
In Scratch Row 1 insert Example 1,  by inserting exactly this forumula into both Scratch.X1 and Scratch.Y1 you will see that the values are different. 

LOCTOLOC(PNT(LocPinX, LocPinY), Width, ThePage!PageWidth)

Are you supprised to see the PinX and PinY respectively?  I wish I really understood the use of width and the page width, but I am learning as we go here.

Now let's try the second example (inserting a row into scratch and once again; In Scratch Row 1 insert Example 2,  by inserting the forumula as shown below into both Scratch.X1 and Scratch.Y1 you will see that the values are different (please note that I have changed the reference to "SHEET.2" instead of "Sheet.4" as above. 

LOCTOPAR(PNT(LocPinX, LocPinY), Width, SHEET.2!Width)
Now even I am supprised to see PinX and Pin Y respectively.  Can this be really useful?

Ok so let's try the last example
PAR(PNT(PinX,PinY))
WOW! what is that???
Set the Lineto in Geometry 2 as follows.

Geometry2.X2=Scratch.X3-Scratch.X1
Geometry2.Y2=Scratch.Y3-Scratch.Y1

The Line should go from the center of your circle to the lower left corner of the page.  So what good is that since you already know the pinx, piny, locpinx and locpiny so you could have calculated easily.


Let's now try somthing with LocToPar

Insert formulas
Scratch.X1=LOCTOPAR(PNT(LocPinX,LocPinY),Sheet.2!Width,Width)
Scratch.Y1=LOCTOPAR(PNT(LocPinX,LocPinY),Sheet.2!Width,Width)

Geometry2.X2=Scratch.X1-Scratch.X3
Geometry2.Y2=Scratch.Y1-Scratch.Y3

Ok now that looks promising, see how the line now connects the center of the circle to the lower left corner of the rectange (note that this is Sheet.2).
 
Also note that I switched the second and third parameters, I wish I understood what these are supposd to mean.

srcRef A reference to a cell in the source object = Sheet.2!Width
dstRef A reference to a cell in the destination object = Width

Of course if you add the Sheet.2!LocPinX and Sheet.2!LocPinX to the Geometry2.X2 and Geometry2.Y2 respectively the line will connect the centers of the two shapes.

I wish I had untied this knot, I fear I have only put a bow on top of a granny.  I am hoping to learn from Ya'll.

Best regards
Steve

[Visio Guy]

Hi Steve,

Those funny arguments at the end of the functions serve to tell Visio "from which shape" and "to which shape" you want to transform.

There is no "Sheet identifier" in the ShapeSheet that can stand on its own. I.e. you can't just write "Sheet.2" in a ShapeSheet cell or function. So they've written "Sheet.2!Width", but the function really only cares that it needs to do something with Sheet.2s coordinate system. It could have been "Sheet.2!FlipX" or anything.

[visProcessEng]

Thank you very much for your kind response.

I had suspected that what you say is true, however I was never able to quite seal the deal.  Thought I would attempt that here and see what come of it.

In the example above we have

LOCTOLOC(PNT(LocPinX, LocPinY), Width, ThePage!PageWidth)

As noted this yeilds the PinX and PinY of the shape (circle) containing the cell which contains the formula above (because width does not point to another shape, Visio knows the source shape is assumed to be the circle. The destination coordinate system is specified as "ThePage" with the reference to the PageWidth cell of ThePage.  I am good with that.

The fact that I am getting PinX and PinY (which I had always imagined as the origin of the shape) instead of LocPinX and LocPinY is because LocPinY and LocPinY actually IS the origin of the Shape and the PinX and PinY is shifted by  LocPinX to the right and LocPinY up.  This is why when you rotate the circle it spins around its center instead of around some stupid corner (which is the origin).

I still have questions, for example why does...
LOCTOLOC(PNT(PinX, PinY), Width, ThePage!PageWidth)
result in a very different point from that above (with LocPinX-Y) I would have expected the results to be offset by the Value of LocPinX and LocPinY, but in fact they are nowhere near, nor is the relationship between these easy to observe.

but I will sleep on it.

Thanks again Visio Guy!

[Visio Guy]

Hi Valve Man

The Pin of a shape is the rotation point. Since this pin passes through the shape and sticks in the page, it has two locations.

Relative to the shape, where the hole is , is LocPinX/Y. These are the local coordinates of the shape, where (0, 0) is the lower-left corner.

PinX/Y is where the pin sticks to the paper, so to sepak. These cooridnates are relative to the page, which has an origin in the lower-left corner as well.

This illustration shows how the mythical pin passes through the shape and hits the page:

(you can download the Visio file: PinAndLocPin.zip)

When I glance at your formulas, they almost look like they are transforming the LocPinX/Y in such a way as to yield PinX/Y (ie: no need to do that!) But admittedly, I haven't tried them or looked to carefully.

[vojo]

Hey guys....instead of waxing poetic about obscure functions that I, for one, have never figured out how to use...way way way way too confusing and from at least some admittedly dumb attempts at playing around with them, could never figure out of what use they would ever be....perhaps a sample diagram showing the various function behaviors you want to present might be much more useful helpful.

[visProcessEng]

Once agian thank you VisioGuy for your clarification.  The presentation of LocPinX(Y) vs PinX(Y) is much more intuative than any of the others I have seen. 

It is a rare thing that I give up on something, but I don't think I am going to get LocToLoc to work.  At least not in a way which makes any sence.  In this I am in agreement with Vojo. 

The last example give in my original post is a solution to the problem I was seeking to address; that being how to draw a line from one shape to another.  Specifically I wanted to add a leader (like an arrow pointing to a shape) to a text shape and I wanted the leader to stick to the shape if the text is moved.  The specifics are a bit tedious.  While I am sure there are hundreds of ways to atchieve the same end, the natural function seemed to be LocToLoc (I still suspect there is an explaination out there) but as mentioned LocToPar (with some additional massage) yeilds the desiered result.

I hope you will read some of my other posts, I will try to restrain my poetic tendency.  However I must warn you the alternative is painfully efficient, you will probably see what I am talking about.

In response to VG's comments on the formulas yeilding PinX and PinY.  You are Right!  the final version of the formula reads.

Distal end of LineToX
LOCTOPAR(PNT(LocPinX,LocPinY),Sheet.1!Width,Width)-PinX+Sheet.1!LocPinX

Distal end of LineToY
LOCTOPAR(PNT(LocPinX,LocPinY),Sheet.1!Width,Width)-PinY+Sheet.1!LocPinY

It works, it may not be elegant but is far cleaner than the alternative.  Again there are details that I have omitted so you are going to have to trust me.

If anyone has a working example of what LocToLoc does, I would love to see it or hear about it.

[munnke]

I would like to thank this post for helping me solve a problem I had.

I was trying to control 3 shapes using 1 control point, with 2 of them offset from it and unable to group them lest I rewrite a dozen macros. By using LocToPar or LocToLOC, I could take the coordinates of the control point in the shape's parrent's coordinate system and convert it to the page's. From there, I add the offset and use LocToPar to conver it back from the page's to the shape's parrent, and use that value in PinX and PinY.

The end result looked like:

--line breaks added by visguy for clarity--

=GUARD(LOCTOPAR(PNT
(
PNTX(LOCTOLOC(PNT(Sheet.2125!Controls.X5,Sheet.2125!Controls.Y5),Sheet.2125!Width,ThePage!Width)),
PNTY(LOCTOLOC(PNT(Sheet.2125!Controls.X5,Sheet.2125!Controls.Y5),Sheet.2125!Width,ThePage!Width))-0.25
)
,ThePage!Width,Width))

As for how LocToLoc works, it is odd, but has a point. I think that one of the problems that you may have when using it is knowing what values are in the shape's coordinate system and which ones are in its parrents. PinX and PinY for instance are values in the shape's parren'ts coordinate system. Control point coordinates, however, are in the shapes coordinate system. So if I was trying to convert a point on the page to a coordinate for a control point, I could use:

LocToLoc(pnt(x,y),ThePage!width,Width)

this will return a value based off of the offset between the point and the 0,0 for the shape.

for example, if you used 1,1, and the shape 0,0 was a 5,6 on the page, the value would be -4,-5.

These functions can be very useful because they perform the conversion from any shape on the page to any other shape on the page. Shapes can be in different groups while still maintaining relationships to eachother.

as for what was shown above;

LOCTOLOC(PNT(PinX, PinY), Width, ThePage!PageWidth)

I get the locpins if its master is the page, and a very wierd value if it is not. Overall, most of the uses I have found for these has been to convert things into the shape or the shape's parrent's coordinates.