### 5.4.6 Spanners

Many objects of musical notation extend over several notes or even several bars. Examples are slurs, beams, tuplet brackets, volta repeat brackets, crescendi, trills, and glissandi. Such objects are collectively called “spanners”, and have special properties to control their appearance and behaviour. Some of these properties are common to all spanners; others are restricted to a sub-set of the spanners.

All spanners support the spanner-interface. A few, essentially those that draw a straight line between the two objects, support in addition the line-spanner-interface.

#### Using the spanner-interface

This interface provides two properties that apply to several spanners.

#### The minimum-length property

The minimum length of the spanner is specified by the minimum-length property. Increasing this usually has the necessary effect of increasing the spacing of the notes between the two end points. However, this override has no effect on many spanners, as their length is determined by other considerations. A few examples where it is effective are shown below.

 a'~ a' a' % increase the length of the tie -\tweak minimum-length #5 ~ a'

 \relative \compressMMRests { a'1 R1*23 % increase the length of the rest bar \once \override MultiMeasureRest.minimum-length = #20 R1*23 a1 }

 \relative { a' \< a a a \! % increase the length of the hairpin \override Hairpin.minimum-length = #20 a \< a a a \! }

This override can also be used to increase the length of slurs and phrasing slurs:

 \relative { a'( g) a -\tweak minimum-length #5 ( g) a\( g\) a -\tweak minimum-length #5 \( g\) }

For some layout objects, the minimum-length property becomes effective only if the set-spacing-rods procedure is called explicitly. To do this, the springs-and-rods property should be set to ly:spanner::set-spacing-rods. For example, the minimum length of a glissando has no effect unless the springs-and-rods property is set:

 % default e' \glissando c'' % not effective alone \once \override Glissando.minimum-length = #20 e' \glissando c'' % effective only when both overrides are present \once \override Glissando.minimum-length = #20 \once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods e' \glissando c''

The same is true of the Beam object:

 % not effective alone \once \override Beam.minimum-length = #20 e'8 e' e' e' % effective only when both overrides are present \once \override Beam.minimum-length = #20 \once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods e'8 e' e' e'

#### The to-barline property

The second useful property of the spanner-interface is to-barline. By default this is true, causing hairpins and other spanners which are terminated on the first note of a measure to end instead on the immediately preceding bar line. If set to false, the spanner will extend beyond the bar line and end on the note itself:

 \relative { a' \< a a a a \! a a a \break \override Hairpin.to-barline = ##f a \< a a a a \! a a a }

This property is not effective for all spanners. For example, setting it to #t has no effect on slurs or phrasing slurs or on other spanners for which terminating on the bar line would not be meaningful.

#### Using the line-spanner-interface

Objects which support the line-spanner-interface include

• DynamicTextSpanner
• Glissando
• TextSpanner
• TrillSpanner
• VoiceFollower

The routine responsible for drawing the stencils for these spanners is ly:line-spanner::print. This routine determines the exact location of the two end points and draws a line between them, in the style requested. The locations of the two end points of the spanner are computed on-the-fly, but it is possible to override their Y-coordinates. The properties which need to be specified are nested two levels down within the property hierarchy, but the syntax of the \override command is quite simple:

 e''2 \glissando b' \once \override Glissando.bound-details.left.Y = #3 \once \override Glissando.bound-details.right.Y = #-2 e''2 \glissando b'

The units for the Y property are staff-spaces, with the center line of the staff being the zero point. For the glissando, this is the value for Y at the X-coordinate corresponding to the center point of each note head, if the line is imagined to be extended to there.

If Y is not set, the value is computed from the vertical position of the corresponding attachment point of the spanner.

In case of a line break, the values for the end points are specified by the left-broken and right-broken sub-lists of bound-details. For example:

 \override Glissando.breakable = ##t \override Glissando.bound-details.right-broken.Y = #-3 c''1 \glissando \break f''1

A number of further properties of the left and right sub-lists of the bound-details property may be modified in the same way as Y:

Y

This sets the Y-coordinate of the end point, in staff-spaces offset from the staff center line. By default, it is the center of the bound object, so a glissando points to the vertical center of the note head.

For horizontal spanners, such as text spanners and trill spanners, it is hardcoded to 0.

attach-dir

This determines where the line starts and ends in the X-direction, relative to the bound object. So, a value of -1 (or LEFT) makes the line start/end at the left side of the note head it is attached to.

X

This is the absolute X-coordinate of the end point. It is usually computed on the fly, and overriding it has little useful effect.

stencil

Line spanners may have symbols at the beginning or end, which is contained in this sub-property. This is for internal use; it is recommended that text be used instead.

text

This is a markup that is evaluated to yield the stencil. It is used to put cresc., tr and other text on horizontal spanners.

 \override TextSpanner.bound-details.left.text = \markup { \small \bold Slower } \relative { c''2\startTextSpan b c a\stopTextSpan }

stencil-align-dir-y
stencil-offset

Without setting one of these, the stencil is simply put at the end-point, centered on the line, as defined by the X and Y sub-properties. Setting either stencil-align-dir-y or stencil-offset will move the symbol at the edge vertically relative to the end point of the line:

 \override TextSpanner.bound-details.left.stencil-align-dir-y = #-2 \override TextSpanner.bound-details.right.stencil-align-dir-y = #UP \override TextSpanner.bound-details.left.text = "ggg" \override TextSpanner.bound-details.right.text = "hhh" \relative { c'4^\startTextSpan c c c \stopTextSpan }

Note that negative values move the text up, contrary to the effect that might be expected, as a value of -1 or DOWN means align the bottom edge of the text with the spanner line. A value of 1 or UP aligns the top edge of the text with the spanner line.

arrow

Setting this sub-property to #t produces an arrowhead at the end-points of the line.

This sub-property controls the space between the specified end point of the line and the actual end. Without padding, a glissando would start and end in the center of each note head.

The music function \endSpanners terminates the spanner which starts on the immediately following note prematurely. It is terminated after exactly one note, or at the following bar line if to-barline is true and a bar line occurs before the next note.

 \relative c'' { \endSpanners c2 \startTextSpan c2 c2 \endSpanners c2 \< c2 c2 }

When using \endSpanners it is not necessary to close \startTextSpan with \stopTextSpan, nor is it necessary to close hairpins with \!.