Att ArrowWayPoints

Attribute Att_ArrowWayPoints

This attribute is used in objects of class ArrowClass to encode the geometry of an arrow between two nodes on an influence diagram. It records the angles at which the arrow leaves the tail node and enters the head node, and the position of any intermediate way points the user has dragged onto the arrow to bend it.

Most arrows on an influence diagram are implicit — they arise automatically from a dependency between variables and do not have an associated ArrowClass object. An explicit ArrowClass object (and therefore an Att_ArrowWayPoints value) is created only when the user bends an arrow, restyles it, or makes it sticky. The default value (a straight arrow with floating endpoints) is the absence of any waypoints.

Format

The value is an array of numbers. The first two elements are the start and end angles; the remaining elements are pairs giving the position of each intermediate way point:

 [ startAngle, endAngle, dx₁, dy₁, dx₂, dy₂, …, dx_N, dy_N ]

startAngle: The angle in degrees at which the arrow leaves the center of the tail (source) node. Null means the tail floats — the rendering code chooses an anchor on the node's perimeter automatically based on the next way point.
endAngle: The angle in degrees at which the arrow enters the center of the head (target) node. Null means the head floats.
dx_i, dy_i: The x and y coordinate of the i^th intermediate way point, encoded as described in the next section. There are zero or more such pairs.

The total number of array elements is therefore 2 + 2×N, where N is the number of intermediate way points (often 0, 1 or 2).

Angle convention

Angles are measured in degrees using the standard atan2(Δy, Δx) convention with screen coordinates (the y-axis points downward):

0° — arrow leaves to the right of the node center.
90° — arrow leaves downward.
180° or -180° — arrow leaves to the left.
-90° — arrow leaves upward.

The start angle is computed from the tail's center to the first way point (or to the head if there are no intermediate way points); the end angle is computed from the head's center to the last way point (or to the tail).

Way point coordinates

Each intermediate way point's dx and dy uses a piecewise encoding so that points inside the bounding box of the two nodes are fractional and points outside the box are expressed in absolute pixels. Let xmin = min(tail.X, head.X) and xmax = max(tail.X, head.X) (with the analogous definitions on the y-axis). The stored value dx is interpreted as:

If 0 ≤ dx ≤ 1: dx is the fractional horizontal distance from the tail center's x to the head center's x. So dx=0 is the tail's column, dx=1 is the head's column, and dx=0.5 is halfway between.
If dx < 0: the way point is to the left of both nodes; dx is the number of pixels to the left of xmin (i.e. the actual x is xmin + dx).
If dx > 1: the way point is to the right of both nodes; (dx - 1) is the number of pixels to the right of xmax (i.e. the actual x is xmax + (dx - 1)).

The y coordinate follows the same convention along the vertical axis (with the screen y-axis pointing downward, so dy=0 is the tail's row and dy=1 is the head's row).

This piecewise encoding allows the way points to be stored independently of node size and to track the nodes if they are moved, while still allowing arrows to bend out beyond the bounding box of the two endpoints when needed. It also avoids a singularity when tail.X == head.X or tail.Y == head.Y.

Examples

A typical bent arrow with two intermediate way points, both inside the bounding box of the tail and head, with both endpoints floating:

 [Null, Null, 0.4642857142857143, 0, 0.4642857142857143, 1]

Both way points sit at about 46% of the way from the tail's x to the head's x; the first way point is at the tail's y, and the second is at the head's y. The result is an S-shaped (or right-angle) bend that exits the tail vertically and enters the head vertically.

An arrow with a single way point and explicit (anchored) start and end angles:

 [18.69898327753452, -20.85445779090173, 113, 0.5]

Here the arrow leaves the tail at roughly 18.7° (slightly below horizontal, to the right), enters the head at roughly −20.9° (slightly above horizontal, from the right), and the single way point sits at (xmax + 112, midway in y).

A straight arrow with no way points and both endpoints floating is simply:

 [Null, Null]

or equivalently no Att_ArrowWayPoints attribute at all on the ArrowClass object.

Programmatic access

The textual form above can be read with GetAttribute and written with SetAttribute (in ADE) or with the corresponding methods in the Suan / Assista APIs. From an Analytica expression the value can be read with Att_ArrowWayPoints of arrowObj and set with Att_ArrowWayPoints of arrowObj := […]. The ArrowClass object for a given pair of nodes can be located by scanning OutgoingArrows of tailNode for the entry whose Att_HeadNode equals headNode; if none exists, you can create one with CreateNewObject(Arrow, parentModule) and then set its Att_TailNode, Att_HeadNode, and Att_ArrowWayPoints.