From 7bb357a9554bcf9277eb003eccaab224dea78978 Mon Sep 17 00:00:00 2001 From: Han-Wen Nienhuys Date: Fri, 26 Jan 2007 02:16:45 +0100 Subject: [PATCH] document new line-spanner. --- Documentation/user/advanced-notation.itely | 126 +++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely index 42cdb7bdae..a35d81eb09 100644 --- a/Documentation/user/advanced-notation.itely +++ b/Documentation/user/advanced-notation.itely @@ -40,6 +40,7 @@ saved as UTF-8. For more information, see @ref{Text encoding}. @menu * Text scripts:: +* Text and line spanners:: * Text spanners:: * Text marks:: * Text markup:: @@ -105,6 +106,131 @@ In this manual: @ref{Text markup}. Program reference: @internalsref{TextScript}. +@node Text and line spanners +@subsection Text and line spanners + +Some performance indications, e.g., @i{rallentando} and +@i{accelerando} and @i{trills} are written as text and are extended +over many measures with lines, sometimes dotted or wavy. + +These all use the same routines as the glissando for drawing the texts +and the lines, and tuning their behavior is therefore also done in the +same way. It is done with a spanner, and the routine responsible for +drawing the spanners is @code{ly:new-line-interface::print}. This +routine creates determines the exact location of the two @i{span +points} and draws a line in between, in the style requested. + +Here is an example of the different line styles available, and how to +tune them. + +@lilypond[relative=2,ragged-right,verbatim,fragment] +d2 \glissando d'2 +\once \override Glissando #'dash-fraction = #0.5 +d,2 \glissando d'2 +\override Glissando #'style = #'dotted-line +d,2 \glissando d'2 +\override Glissando #'style = #'zigzag +d,2 \glissando d'2 +\override Glissando #'style = #'trill +d,2 \glissando d'2 +@end lilypond + +The information that determines the end-points is computed on-the-fly +for every graphic object, but it is possible to override these. + +@lilypond[relative=2,ragged-right,verbatim,fragment] +e2 \glissando f +\once \override Glissando #'bound-details #'right #'Y = #-2 +e2 \glissando f +@end lilypond + +The @code{Glissando} object, like any other using the +@code{ly:new-line-interface::print} routine, carries a nested +association list. In the above statement, the @item value for @code{Y} +is set to @code{-2} for association list corresponding to the right +end point. Of course, it is also possible to adjust the left side with +@code{left} instead of @code{right}. + +If @code{Y} is not set, the value is computed from the vertical +position of right attachment point of the spanner. + +In case of a line break, the values for the span-points are extended +with contents of the @code{left-break} and @code{right-break} +sublists, for example + +@lilypond[relative=2,ragged-right,verbatim,fragment] +\override Glissando #'breakable = ##T +\override Glissando #'bound-details #'right-break #'Y = #-3 +\override Glissando #'bound-details #'left-break #'Y = #3 +c1 \glissando \break +f1 +@end lilypond + +The following properties can be used for the + +@table @code +@item Y +This sets the Y-coordinate of the end point, in staff space. By +default, it is the center of the bound object, so for a glissando it +points to the vertical center of the note head. + +For horizontal spanners, such as text spanner and trill spanners, it +is hardcoded to 0. + +@item attach-dir +This determines where the line starts and ends in X-direction, +relative to the bound object. So, a value of @code{-1} (or +@code{LEFT}) makes the line start/end at the left side of the note +head it is attached to. + +@item X +This is the absolute coordinate of the end point. It is usually +computed on the fly, and there is little use in overriding it. + +@item 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 to use @code{text}. + +@item text +This is a markup that is evaluated to yield stencil. It is +used to put @i{cresc.} and @i{tr} on horizontal spanners. + +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +\override TextSpanner #'bound-details #'left #'text + = \markup { \bold Slower } +c2\startTextSpan b c\stopTextSpan a +@end lilypond + + +@item stencil-align-dir-y +@item stencil-offset +Without setting this, the stencil is simply put there at the +end-point, as defined by the @code{X} and @code{Y} sub properties. +Setting either @code{stencil-align-dir-y} or @code{stencil-offset} +will move the symbol at the edge relative to the end point of the line + +@lilypond[relative=1,fragment,verbatim] +\override TextSpanner #'bound-details #'left #'stencil-align-dir-y = #DOWN +\override TextSpanner #'bound-details #'right #'stencil-align-dir-y = #UP + +\override TextSpanner #'bound-details #'left #'text = #"gggg" +\override TextSpanner #'bound-details #'right #'text = #"hhhh" +c4^\startTextSpan c c c \stopTextSpan +@end lilypond + +@item arrow +Setting this sub property to @code{#t} produce an arrowhead at the end +of the line. + +@item 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. + +@end table + + @node Text spanners @subsection Text spanners -- 2.39.2