LilyPond Notation Reference: 5.4.6 Spanners

### 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

>     a1
>     \compressFullBarRests
>     R1*23
>     % increase the length of the rest bar
>     \once \override MultiMeasureRest #'minimum-length = #20
>     R1*23
>     a1

>     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:

>     a( a)
>     a
>     -\tweak #'minimum-length #5
>     ( a)

>     a\( a\)
>     a
>     -\tweak #'minimum-length #5
>     \( a\)

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
>     e8 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
>     e8 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:

>     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-interface::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:

>     e2 \glissando b
>     \once \override Glissando #'(bound-details left Y) = #3
>     \once \override Glissando #'(bound-details right Y) = #-2
>     e2 \glissando b

The units for the `Y` property are `staff-space`s, 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
>     c1 \glissando \break
>     f1

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-space`s 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 }
  >     c2\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"
  >     c4^\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 of the line.

`padding`

  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.

>     \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 `\!`.

#### See also

Internals Reference: TextSpanner, Glissando, VoiceFollower, TrillSpanner, line-spanner-interface.

其它语言：deutsch, español, 日本語。

#### LilyPond — Notation Reference