This is a quick post on how radial gradient stops work in Visio.
In Visio, gradient stop positions are set as a percentage value:
If you're applying a linear gradient then that percentage is a position on virtual ray that has a start and end point and is determined by the FillGradientAngle. So the following image shows a linear gradient with two stops (a white one at 0% and a blue one at 100%) and an angle of 0 degrees (shown by the orange arrow):
For a radial gradient the FillGradientAngle is not used and the start end points are determined based on the value of the FillGradientDir cell. Setting a value of 3 sets the begin point to the center of the shape and the end point becomes the corner of the shape.
Here's a shape that demonstrates this and uses a (yellow) control handle to set the gradient position. (I've also added another orange arrow to show the direction of the gradient ray)
Just in case you're wondering where the gradient part is in these solid colours, I've set adjoining stops to the same values, which produces a hard transition (ie no gradient). This is useful a) to see where the stop positions actually are and b) as a technique to allow for multiple colours in a single shape. You can see another example of this in a traffic light post I did a little while ago.
The stops in the above shape are defined as follows:
...and then User.PathPercentage is calculated by taking input from the Control handle, pushing it into the User.RawX/Y cells, working out the radius and angle and then using those values (User.CalcX/Y) back in the Control handles. Here's the Control handle's XY cells:
The result is that you can change the position of the stops via a control handle in the shape:
One caveat to bear in mind is that you cannot lock gradient stops so you run the risk of users either deleting or overwriting the stops via the controls in the UI. One option to protect them is to lock formatting of the whole shape using the LockFormat cell. It would be great to have a LockFillGradientStops but alas that doesn't exist currently.
And finally, a very handy tip from Chris Roth - if you're having trouble selecting gradient stops that are close together in the UI, you can use the arrow keys to navigate between them, allowing you to not mess up the positions but set all of the other stop properties.