Optional and named parameters

Most of the arrow functions take a record argument of optional parameters (see Faking optional named parameters) of type ArrowOpts. These functions typically have a companion function that does not take an options record, and uses a default set of ArrowOpts. For example, arrow' takes an options record parameter, and arrow does not. In this tutorial, whenever we mention a function with a single quote (') at the end, note there is also a companion function without the quote that uses a default set of options.

Scale invariance

Arrowheads and -tails are the canonical example of scale invariant objects: they are not affected by scaling (though they are affected by other transformations such as rotation and translation). The scale-invariance section of the user manual has a good example showing why scale-invariance is necessary for the creation of arrowheads; detailed documentation explaining scale invariant objects is in Diagrams.TwoD.Transform.ScaleInv. It turns out that this module is no longer used internally for the creation of arrowheads, the technical details of how arrows are actually created is beyond the scope of this tutorial. The most important consequence for day-to-day diagramming with arrows is that only the length of arrowheads and -tails contribute to the envelope of an arrow (the width does not). This is analogous to the way line width does not contribute to the envelope of a line.

The head and tail shape

The arrowHead and arrowTail fields contain information needed to construct the head and tail of the arrow, the most important aspect being the shape. So, for example, if we set arrowHead to spike and arrowTail to quill,

> arrowBetween' (with & arrowHead .~ spike
>                     & arrowTail .~ quill
>                     & lengths   .~ veryLarge)
>   sPt ePt

then the arrow from the previous example looks like this:

The Arrowheads module exports a number of standard arrowheads including tri, dart, spike, thorn, dart, lineHead, and noHead, with dart being the default. Also available are companion functions like arrowheadDart that allow finer control over the shape of a dart style head. For tails, in addition to quill are block, lineTail, and noTail. Again for more control are functions like, arrowtailQuill. Finally, any of the standard arrowheads can be used as tails by appending a single quote, so for example:

> arrowBetween' (with & arrowHead .~ thorn & arrowTail .~ thorn'
>                     & lengths  .~ veryLarge) sPt ePt

yields:

The shaft

The shaft of an arrow can be any arbitrary Trail V2 n in addition to a simple straight line. For example, an arc makes a perfectly good shaft. The length of the trail is irrelevant, as the arrow is scaled to connect the starting point and ending point regardless of the length of the shaft. Modifying our example with the following code will make the arrow shaft into an arc:

> shaft = arc xDir (1/2 @@ turn)
>
> example = ( sDot <> eDot
>          <> arrowBetween' (with & arrowHead .~ spike & arrowTail .~ spike'
>                                 & arrowShaft .~ shaft
>                                 & lengths .~ veryLarge) sPt ePt
>           # frame 0.25

Arrows with curved shafts don't always render the way our intuition may lead us to expect. One could reasonably expect that the arc in the above example would produce an arrow curving upwards, not the downwards-curving one we see. To understand what's going on, imagine that the arc is Located. Suppose the arc goes from the point \((0,0)\) to \((-1,0)\). This is indeed an upwards curving arc with origin at \((0,0)\). Now suppose we want to connect points \((0,0)\) and \((1,0)\). We attach the arrow head and tail and rotate the arrow about its origin at \((0,0)\) until the tip of the head is touching \((1,0)\). This rotation flips the arrow vertically. To make an arc that runs clockwise from its starting point, use a negative Angle.

> shaft = arc xDir (-1/2 @@ turn)

Here are some exercises to try.

Lengths and Gaps

The fields headLength and tailLength are for setting the length of the head and tail. The head length is measured from the tip of the head to the start of the joint connecting the head to the shaft. The tail length is measured in an analagous manner. They have type Measure Double and the default is normal. headGap and tailGap options are fairly self explanatory: they leave space at the end or beginning of the arrow and are also of type Mesure Double; the default is none. Take a look at their effect in the following example:

> sPt = p2 (0.20, 0.50)
> mPt = p2 (1.50, 0.50)
> ePt = p2 (2.80, 0.50)
>
> spot  = circle 0.02 # lw none
> sDot = spot # fc blue  # moveTo sPt
> mDot = spot # fc green # moveTo mPt
> eDot = spot # fc red   # moveTo ePt
>
>
> leftArrow  = arrowBetween' (with & arrowHead  .~ dart  & arrowTail .~ tri'
>                                  & headLength .~ large & tailLength .~ normal
>                                  & headGap    .~ large) sPt mPt
>
> rightArrow = arrowBetween' (with & arrowHead  .~ spike & arrowTail .~ dart'
>                                  & shaftStyle %~ lw ultraThick
>                                  & tailLength .~ veryLarge & headLength .~ huge
>                                  & tailGap    .~ veryLarge) mPt ePt
>
> example = ( sDot <> mDot <> eDot <> leftArrow <> rightArrow)
>           # frame 0.25

Our use of the lens package allows us to create other lenses to modify ArrowOpts using the same syntax as the record field lenses. lengths is useful for setting the headLength and tailLength simultaneously and gaps can be used to simultaneously set the headGap / tailGap.

A useful pattern is to use lineTail together with lengths as in the following example:

> dia = (rect 5 2 # fc lavender # alignX (-1) # showOrigin # named "A")
>        === strutY 2 ===
>       (rect 5 2 # fc pink # alignX (-1) # showOrigin # named "B")
>
> ushaft = trailFromVertices (map p2 [(0, 0), (-0.5, 0), (-0.5, 1), (0, 1)])
>
> uconnect tl setWd =
>   connect' (with
>           & arrowHead  .~ spike
>           & arrowShaft .~ ushaft
>           & arrowTail  .~ tl
>           & setWd)
>
> example =
>   hcat' (with & sep .~ 1.5)
>   [ dia # uconnect noTail   (headLength .~ veryLarge) "B" "A"  -- looks bad
>   , dia # uconnect lineTail (lengths    .~ veryLarge) "B" "A"  -- looks good!
>   ]
>   # frame 0.25

The style options

By default, arrows are drawn using the current line color (including the head and tail). In addition, the shaft styling is taken from the current line styling attributes. For example:

> example = mconcat
>   [ square 2
>   , arrowAt' (with & headLength .~ veryLarge) origin unitX
>     # lc blue # lw thick
>   ]
>   # dashingG [0.05, 0.05] 0

The colors (or more generally textues) of the head, tail, and shaft may be individually overridden using headTexture, tailTexture, and shaftTexture in conjunction with the solid function. More generally, the styles are controlled using headStyle, tailStyle, and shaftStyle. For example:

> dashedArrow = arrowBetween' (with & arrowHead .~ dart & arrowTail .~ spike' & lengths .~ veryLarge
>                                   & headTexture .~ solid blue & tailTexture .~ solid orange
>                                   & shaftStyle %~ dashingG [0.04, 0.02] 0
>                                   . lw thick) sPt ePt
>

Note that when setting a style, one must generally use the %~ operator in order to apply something like dashingG [0.04, 0.02] 0 which is a function that changes the style.