Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.20"
+@c \version "2.17.6"
@node Changing defaults
@chapter Changing defaults
options available in LilyPond. It is written as a HTML document,
which is available
@c leave the @uref as one long line.
-@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/internals/,on@/-line},
and is also included with the LilyPond documentation package.
Internally, LilyPond uses Scheme (a LISP dialect) to provide
* Context layout order::
@end menu
-
@seealso
Learning Manual:
@rlearning{Contexts and engravers}.
@c TODO Should this be Modifying engravers or Modifying contexts?
-Notation contexts (like @code{Score} and @code{Staff}) not only
-store properties,
-they also contain plug-ins called @q{engravers} that create notation
-elements. For example, the @code{Voice} context contains a
+Notation contexts (like @code{Score} and @code{Staff}) not only store
+properties, they also contain plug-ins called @q{engravers} that create
+notation elements. For example, the @code{Voice} context contains a
@code{Note_heads_engraver} and the @code{Staff} context contains a
-@code{Key_signature_engraver}.
+@code{Key_engraver}.
For a full a description of each plug-in, see
@ifhtml
@knownissues
-Usually the order in which the engravers are specified
-does not matter, but in a few special cases the order
-is important, for example where one engraver writes
-a property and another reads it, or where one engraver
-creates a grob and another must process it. The order in
-which the engravers are specified is the order in which
-they are called to carry out their processing.
+The order in which the engravers are specified is the order in
+which they are called to carry out their processing. Usually the
+order in which the engravers are specified does not matter, but in
+a few special cases the order is important, for example where one
+engraver writes a property and another reads it, or where one
+engraver creates a grob and another must process it.
+
+The following orderings are important:
+
+@itemize
+@item
+the @code{Bar_engraver} must normally be first,
+
+@item
+the @code{New_fingering_engraver} must come before the
+@code{Script_column_engraver},
+
+@item
+the @code{Timing_translator} must come before the
+@code{Bar_number_engraver}.
+
+@end itemize
+
+@seealso
+Installed Files:
+@file{ly/engraver-init.ly}.
-The following orderings are important: the
-@code{Bar_engraver} must normally be first, and
-the @code{New_fingering_engraver} must come before
-the @code{Script_column_engraver}. There may be others
-with ordering dependencies.
@node Changing context default settings
@subsection Changing context default settings
+@cindex default context properties, changing
+@cindex context properties, changing defaults
+
+Context and grob properties can be changed with @code{\set}
+and @code{\override} commands, as described in
+@ref{Modifying properties}. These commands create music events,
+making the changes take effect at the point in time the music
+is being processed.
+
+In contrast, this section explains how to change the @emph{default}
+values of context and grob properties at the time the context is
+created. There are two ways of doing this. One modifies the default
+values in all contexts of a particular type, the other modifies the
+default values in just one particular instance of a context.
+
+@menu
+* Changing all contexts of the same type::
+* Changing just one specific context::
+* Order of precedence::
+@end menu
+
+@node Changing all contexts of the same type
+@unnumberedsubsubsec Changing all contexts of the same type
+
+@cindex \context in \layout block
+@funindex \context
+@funindex \layout
+
The context settings which are to be used by default in
-@code{Score}, @code{Staff} and @code{Voice} contexts may be specified
-in a @code{\layout} block, as illustrated in the following example.
+@code{Score}, @code{Staff}, @code{Voice} and other contexts may be
+specified in a @code{\context} block within any @code{\layout} block.
The @code{\layout} block should be placed within the @code{\score}
-block to which it is to apply, but outside any music.
+block to which it is to apply, after the music.
+
+@example
+\layout @{
+ \context @{
+ \Voice
+ [context settings for all Voice contexts]
+ @}
+ \context @{
+ \Staff
+ [context settings for all Staff contexts]
+ @}
+@}
+@end example
-Note that the @code{\set} command itself and the context must be
-omitted when the context default values are specified in this way:
+The following types of settings may be specified:
+
+@itemize
+@item
+An @code{\override} command, but with the context name omitted
@lilypond[quote,verbatim]
\score {
\relative c'' {
- a4^"Really small, thicker stems, no time signature" a a a
- a a a a
+ a4^"Thicker stems" a a a
+ a4 a a\ff a
+ }
+ \layout {
+ \context {
+ \Staff
+ \override Stem.thickness = #4.0
+ }
+ }
+}
+@end lilypond
+
+@item
+Directly setting a context property
+
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a\ff a
}
\layout {
\context {
\Staff
fontSize = #-4
- \override Stem #'thickness = #4.0
- \remove "Time_signature_engraver"
}
}
}
@end lilypond
-In this example, the @code{\Staff} command specifies that the
-subsequent specifications are to be applied to all staves within
-this score block.
+@item
+A predefined command such as @code{\dynamicUp} or a music
+expression like @code{\accidentalStyle dodecaphonic}
+
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ a4^"Dynamics above" a a a
+ a4 a a\ff a
+ }
+ \layout {
+ \context {
+ \Voice
+ \dynamicUp
+ }
+ \context {
+ \Staff
+ \accidentalStyle dodecaphonic
+ }
+ }
+}
+@end lilypond
-Modifications can be made to the @code{Score} context or all
-@code{Voice} contexts in a similar way.
+@item
+A user-defined variable containing a @code{\with} block; for details
+of the @code{\with} block see
+@ref{Changing just one specific context}.
-Context changes can be placed in a variable and applied to a
-@code{\context} definition by prepending the modification with
-@code{\with}:
@lilypond[quote,verbatim]
-blubb = \with {
+StaffDefaults = \with {
fontSize = #-4
- \override Stem #'thickness = #4.0
- \remove "Time_signature_engraver"
}
-bla = \with {
- fontSize = #3
- \override Stem #'thickness = #-2.0
+\score {
+ \new Staff {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a a
+ }
+ }
+ \layout {
+ \context {
+ \Staff
+ \StaffDefaults
+ }
+ }
}
+@end lilypond
-melody = \relative c'' {
- a4 a a a |
- a4 a a a |
+@end itemize
+
+Property-setting commands can be placed in a @code{\layout} block
+without being enclosed in a @code{\context} block. Such settings
+are equivalent to including the same property-setting commands at
+the start of every context of the type specified. If no context
+is specified @emph{every} bottom-level context is affected, see
+@ref{Bottom-level contexts - voices}. The syntax of a
+property-setting command in a @code{\layout} block is the same as
+the same command written in the music stream.
+
+@lilypond[quote,verbatim]
+\score {
+ \new Staff {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a a
+ }
+ }
+ \layout {
+ \accidentalStyle dodecaphonic
+ \set fontSize = #-4
+ \override Voice.Stem.thickness = #4.0
+ }
+}
+@end lilypond
+
+
+@node Changing just one specific context
+@unnumberedsubsubsec Changing just one specific context
+
+@cindex \with
+@funindex \with
+
+The context properties of just one specific context instance can be
+changed in a @code{\with} block. All other context instances of the
+same type retain the default settings built into LilyPond and modified
+by any @code{\layout} block within scope. The @code{\with} block
+must be placed immediately after the @code{\new} @var{context-type}
+command:
+
+@example
+\new Staff
+\with @{
+ [context settings for this context instance only]
+@} @{
+...
+@}
+@end example
+
+The following types of settings may be specified:
+
+@itemize
+@item
+An @code{\override} command, but with the context name omitted
+
+@lilypond[quote,verbatim]
+\score {
+ \new Staff {
+ \new Voice
+ \with {
+ \override Stem.thickness = #4.0
+ }
+ {
+ \relative c'' {
+ a4^"Thick stems" a a a
+ a4 a a a
+ }
+ }
+ }
}
+@end lilypond
+
+@item
+Directly setting a context property
+@lilypond[quote,verbatim]
\score {
<<
- \new Staff <<
- \melody
- s1*0^"Small, thicker stems, no time signature"
- >>
- \new Staff \bla <<
- \melody
- s1*0^"Different"
- >>
+ \new Staff {
+ \relative c'' {
+ a4^"Default font" a a a
+ a4 a a a
+ }
+ }
+ \new Staff
+ \with {
+ fontSize = #-4
+ } {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a a
+ }
+ }
>>
- \layout {
- \context {
- \Staff
- \blubb
+}
+@end lilypond
+
+@item
+A predefined command such as @code{\dynamicUp}
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff {
+ \new Voice {
+ \relative c'' {
+ a4^"Dynamics below" a a a
+ a4 a a\ff a
+ }
+ }
}
- }
+ \new Staff
+ \with { \accidentalStyle dodecaphonic }
+ {
+ \new Voice
+ \with { \dynamicUp }
+ {
+ \relative c'' {
+ a4^"Dynamics above" a a a
+ a4 a a\ff a
+ }
+ }
+ }
+ >>
}
@end lilypond
-@c TODO: add \with in here.
+@end itemize
+
+@node Order of precedence
+@unnumberedsubsubsec Order of precedence
+
+The value of a property which applies at a particular time is
+determined as follows:
+
+@itemize
+@item
+if an @code{\override} or @code{\set} command in the input stream is
+in effect that value is used,
+
+@item
+otherwise the default value taken from a @code{\with} statement
+on the context initiation statement is used,
+
+@item
+otherwise the default value taken from the most recent appropriate
+@code{\context} block in the @code{\layout} blocks is used,
+
+@item
+otherwise the LilyPond built-in default is used.
+@end itemize
+
+@seealso
+Learning Manual:
+@rlearning{Modifying context properties}.
+Notation Reference:
+@ref{Contexts explained},
+@ref{Bottom-level contexts - voices},
+@ref{The set command},
+@ref{The override command},
+@ref{The \layout block}.
@node Defining new contexts
\consists "Note_heads_engraver"
\consists "Rhythmic_column_engraver"
\consists "Text_engraver"
- \consists Pitch_squash_engraver
+ \consists "Pitch_squash_engraver"
squashedPosition = #0
- \override NoteHead #'style = #'slash
- \override Stem #'transparent = ##t
- \override Flag #'transparent = ##t
+ \override NoteHead.style = #'slash
+ \override Stem.transparent = ##t
+ \override Flag.transparent = ##t
\alias Voice
}
\context { \Staff
the engravers which provide this functionality,
@example
-\consists Note_heads_engraver
-\consists Text_engraver
+\consists "Note_heads_engraver"
+\consists "Text_engraver"
@end example
but we only need this on the center line,
@example
-\consists Pitch_squash_engraver
+\consists "Pitch_squash_engraver"
squashedPosition = #0
@end example
The notes look like a slash, and have no stem,
@example
-\override NoteHead #'style = #'slash
-\override Stem #'transparent = ##t
-\override Flag #'transparent = ##t
+\override NoteHead.style = #'slash
+\override Stem.transparent = ##t
+\override Flag.transparent = ##t
@end example
All these plug-ins have to cooperate, and this is achieved with a
\type "Engraver_group"
\consists "Note_heads_engraver"
\consists "Text_engraver"
- \consists Pitch_squash_engraver
+ \consists "Pitch_squash_engraver"
squashedPosition = #0
- \override NoteHead #'style = #'slash
- \override Stem #'transparent = ##t
- \override Flag #'transparent = ##t
+ \override NoteHead.style = #'slash
+ \override Stem.transparent = ##t
+ \override Flag.transparent = ##t
\alias Voice
@}
@end example
is encountered when there is no suitable context available to
contain it. This can give rise to unexpected new staves or scores.
+@cindex alignAboveContext
+@cindex alignBelowContext
+@funindex alignAboveContext
+@funindex alignBelowContext
+
+Sometimes a context is required to exist for just a brief period, a
+good example being the staff context for an ossia. This is usually
+achieved by introducing the context definition at the appropriate
+place in parallel with corresponding section of the main music.
+By default, the temporary context will be placed below all the
+existing contexts. To reposition it above the context called
+@qq{main}, it should be defined like this:
+
+@example
+@code{\new Staff \with @{ alignAboveContext = #"main" @} }
+@end example
+
+A similar situation arises when positioning a temporary lyrics
+context within a multi-staved layout such as a @code{ChoirStaff},
+for example, when adding a second verse to a repeated section.
+By default the temporary lyrics context will be placed beneath the
+lower staves. By defining the temporary lyrics context with
+@code{alignBelowContext} it can be positioned correctly beneath
+the (named) lyrics context containing the first verse.
+
+Examples showing this repositioning of temporary contexts can be
+found elsewhere --- see @rlearning{Nesting music expressions},
+@ref{Modifying single staves} and @ref{Techniques specific to lyrics}.
+
@seealso
-Usage Manual:
+Learning Manual:
+@rlearning{Nesting music expressions}.
+
+Notation Reference:
+@ref{Modifying single staves},
+@ref{Techniques specific to lyrics}.
+
+Application Usage:
@rprogram{An extra staff appears}.
Installed Files:
@file{ly/engraver-init.ly}.
-
@node Explaining the Internals Reference
@section Explaining the Internals Reference
-
@menu
* Navigating the program reference::
* Layout interfaces::
3 staff spaces of white
between the note and the fingering:
@example
-\once \override Voice.Fingering #'padding = #3
+\once \override Voice.Fingering.padding = #3
@end example
Inserting this command before the Fingering object is created,
i.e., before @code{c2}, yields the following result:
@lilypond[quote,relative=2,verbatim]
-\once \override Voice.Fingering #'padding = #3
+\once \override Voice.Fingering.padding = #3
c-2
\stemUp
f
The command
@verbatim
-\override Staff.Stem #'thickness = #4.0
+\override Staff.Stem.thickness = #4.0
@end verbatim
@noindent
@lilypond[quote,verbatim,relative=2]
c4
-\override Staff.Stem #'thickness = #4.0
+\override Staff.Stem.thickness = #4.0
c4
c4
c4
@lilypond[quote,verbatim,relative=2]
c4
-\once \override Stem #'thickness = #4.0
+\once \override Stem.thickness = #4.0
c4
c4
@end lilypond
when the object is created. In this example,
@lilypond[quote,verbatim,relative=2]
-\override Slur #'thickness = #3.0
+\override Slur.thickness = #3.0
c8[( c
-\override Beam #'beam-thickness = #0.6
+\override Beam.beam-thickness = #0.6
c8 c])
@end lilypond
@code{\revert} in the next example does not do anything.
@example
-\override Voice.Stem #'thickness = #4.0
-\revert Staff.Stem #'thickness
+\override Voice.Stem.thickness = #4.0
+\revert Staff.Stem.thickness
@end example
Some tweakable options are called @q{subproperties} and reside inside
such as
@example
-\override Stem #'(details beamed-lengths) = #'(4 4 3)
+\override Stem.details.beamed-lengths = #'(4 4 3)
@end example
@end ignore
@seealso
-Internals:
+Internals Reference:
@rinternals{Backend},
@rinternals{All layout objects},
@rinternals{OverrideProperty},
@rinternals{RevertProperty},
@rinternals{PropertySet}.
-
@knownissues
-
The back-end is not very strict in type-checking object properties.
Cyclic references in Scheme values for properties can cause hangs
or crashes, or both.
-
@node The set command
@subsection The @code{@bs{}set} command
@end ifnothtml
@seealso
-
Internals Reference:
-
@rinternals{Tunable context properties}.
-
@cindex grob properties
@cindex properties, grob
@funindex \override
to see the settings for each grob description. Grob descriptions
are modified with @code{\override}.
-@code{\override} is actually a shorthand;
-
-@example
-\override @var{context}.@var{GrobName} #'@var{property} = #@var{value}
-@end example
-
-@noindent
-is more or less equivalent to
+The syntax for the @code{\override} command is
-@c leave this long line -gp
@example
-\set @var{context}.@var{GrobName} =
- #(cons (cons '@var{property} @var{value})
- <previous value of @var{context}.@var{GrobName}>)
+\override [@var{context}.]@var{GrobName}.@var{property} = #@var{value}
@end example
-The value of @code{context}.@code{GrobName} (the alist) is used to initialize
-the properties of individual grobs. Grobs have
-properties, named in Scheme style, with
-@code{dashed-words}. The values of grob properties change
-during the formatting process: formatting basically amounts
-to computing properties using callback functions.
-
For example, we can increase the thickness of a note stem by
overriding the @code{thickness} property of the @code{Stem}
object:
@lilypond[quote,verbatim,relative=2]
c4 c
-\override Voice.Stem #'thickness = #3.0
+\override Voice.Stem.thickness = #3.0
c4 c
@end lilypond
context is used:
@lilypond[quote,verbatim,relative=2]
-{ \override Staff.Stem #'thickness = #3.0
+{ \override Staff.Stem.thickness = #3.0
<<
{
e4 e
- \override Stem #'thickness = #0.5
+ \override Stem.thickness = #0.5
e4 e
} \\ {
c4 c c c
}
@end lilypond
+Some tweakable options are called @q{subproperties} and reside inside
+properties. To tweak those, use commands in the form
+
+@example
+\override Stem.details.beamed-lengths = #'(4 4 3)
+@end example
+
+or to modify the ends of spanners, use a form like these
+
+@example
+\override TextSpanner.bound-details.left.text = #"left text"
+\override TextSpanner.bound-details.right.text = #"right text"
+@end example
+
@funindex \revert
@cindex reverting overrides
@cindex overrides, reverting
-The effects of @code{\override} can be undone by @code{\revert}:
+The effects of @code{\override} can be undone by @code{\revert}.
+
+The syntax for the @code{\revert} command is
+
+@example
+\revert [@var{context}.]@var{GrobName}.@var{property}
+@end example
+
+For example,
@lilypond[quote,verbatim,relative=2]
c4
-\override Voice.Stem #'thickness = #3.0
+\override Voice.Stem.thickness = #3.0
c4 c
-\revert Voice.Stem #'thickness
+\revert Voice.Stem.thickness
c4
@end lilypond
<<
{
e4
- \override Staff.Stem #'thickness = #3.0
+ \override Staff.Stem.thickness = #3.0
e4 e e
} \\ {
c4 c c
- \revert Staff.Stem #'thickness
+ \revert Staff.Stem.thickness
c4
}
>>
{
<<
{
- \override Stem #'thickness = #3.0
+ \override Stem.thickness = #3.0
e4 e e e
} \\ {
c4
- \once \override Stem #'thickness = #3.0
+ \once \override Stem.thickness = #3.0
c4 c c
}
>>
Commands which change output generally look like
@example
-\override Voice.Stem #'thickness = #3.0
+\override Voice.Stem.thickness = #3.0
@end example
@noindent
@item a sensible value: here @code{3.0}.
@end itemize
-Some tweakable options are called @q{subproperties} and reside inside
-properties. To tweak those, use commands in the form
-
-@example
-\override Stem #'(details beamed-lengths) = #'(4 4 3)
-@end example
-
@cindex internal documentation
@cindex finding graphical objects
@cindex graphical object descriptions
@end ignore
@seealso
-
Internals Reference:
@rinternals{Backend}
+
@node The tweak command
@subsection The @code{\tweak} command
syntax:
@example
-\tweak #'@code{grob-property} #@code{value}
+\tweak [@var{layout-object}.]@var{grob-property} @var{value}
@end example
-The @code{\tweak} command applies to the object that immediately
-follows @code{value} in the music stream.
+Specifying @var{layout-object} is optional.
+The @code{\tweak} command applies to the music object that immediately
+follows @var{value} in the music stream.
@ignore
In some cases, it is possible to take a short-cut for tuning
@lilypond[relative=2,verbatim,quote]
< c
- \tweak #'color #red
+ \tweak color #red
d
g
- \tweak #'duration-log #1
+ \tweak duration-log #1
a
> 4
--\tweak #'padding #8
+-\tweak padding #8
-^
@end lilypond
-But the main use of the @code{\tweak} command is to modify just
+The main use of the @code{\tweak} command is to modify just
one of a number of notation elements which start at the same musical
moment, like the notes of a chord, or tuplet brackets which start
at the same time.
So, this works:
@lilypond[relative=2,verbatim,quote]
-<\tweak #'color #red c>4
+<\tweak color #red c>4
@end lilypond
@noindent
but this does not:
@lilypond[relative=2,verbatim,quote]
-\tweak #'color #red c4
+\tweak color #red c4
@end lilypond
@end ignore
@lilypond[relative=2,verbatim,quote]
< c
- \tweak #'color #red
+ \tweak color #red
d
g
- \tweak #'duration-log #1
+ \tweak duration-log #1
a
> 4
@end lilypond
@code{\tweak} can be used to modify slurs:
@lilypond[verbatim,quote,relative=1]
-c-\tweak #'thickness #5 ( d e f)
+c-\tweak thickness #5 ( d e f)
@end lilypond
For the @code{\tweak} command to work, it must
remain immediately adjacent to the object to which it is
to apply after the input file has been converted to a music stream.
-At times, LilyPond may insert additional items into the music stream
-during the parsing process. For example, when a note that is not
-explicitly part of a chord will be placed in a chord by LilyPond,
-so notes to be modified with @code{\tweak} must be placed inside
-a chord construct:
+Tweaking a whole chord does not do anything since its music event
+only acts as a container, and all layout objects are created from events
+inside of the @code{EventChord}:
@lilypond[relative=2,verbatim,quote]
-\tweak #'color #red c4
-<\tweak #'color #red c>4
+\tweak color #red c4
+\tweak color #red <c e>4
+<\tweak color #red c e>4
@end lilypond
-The @code{\tweak} command cannot be used to modify any item
-that does not appear explicitly in the input file. In particular
-it cannot be used to modify stems,
-beams or accidentals directly, since these are generated later by
-note heads, rather than by music elements in the input stream.
-Nor can @code{\tweak} be used to modify clefs or time
+The simple @code{\tweak} command cannot be used to modify any object
+that is not directly created from the input. In particular
+it will not affect stems, automatic
+beams or accidentals, since these are generated later by
+@code{NoteHead} layout objects rather than by music elements in the
+input stream.
+
+Such indirectly created layout objects can be tweaked using the form
+of the @code{\tweak} command in which the grob name is specified
+explicitly:
+
+@lilypond[relative=2,verbatim,quote]
+\tweak Stem.color #red
+\tweak Beam.color #green c8 e
+<c e \tweak Accidental.font-size #-3 ges>4
+@end lilypond
+
+@code{\tweak} cannot be used to modify clefs or time
signatures, since these become separated from any preceding
@code{\tweak} command in the input stream by the automatic
insertion of extra elements required to specify the context.
@lilypond[verbatim,quote,relative=1]
c
--\tweak #'style #'dashed-line
--\tweak #'dash-fraction #0.2
--\tweak #'thickness #3
--\tweak #'color #red
+-\tweak style #'dashed-line
+-\tweak dash-fraction #0.2
+-\tweak thickness #3
+-\tweak color #red
\glissando
f'
@end lilypond
in determining how to adjust the input to make a @code{\tweak}
apply.
-
@seealso
Learning Manual:
@rlearning{Tweaking methods}.
-Extending:
+Extending LilyPond:
@rextend{Displaying music expressions}.
-
@knownissues
-@cindex tweaks in a variable
-The @code{\tweak} command cannot be used inside a variable.
-
-@cindex tweaks in lyrics
-The @code{\tweak} commands cannot be used in @code{\lyricmode}.
-
@cindex tweaking control points
@cindex control points, tweaking
-The @code{\tweak} command will apply to only the first of several
-generated ties in a chord.
+The @code{\tweak} command cannot be used to modify the control
+points of just one of several ties in a chord, other than the first
+one encountered in the input file.
@node set versus override
@subsection @code{\set} vs. @code{\override}
% reduced space between staves
\new PianoStaff \with {
% this is the nested declaration
- \override StaffGrouper #'staff-staff-spacing #'basic-distance = #7
+ \override StaffGrouper.staff-staff-spacing.basic-distance = #7
} <<
\new Staff { \clef treble c''1 }
\new Staff { \clef bass c1 }
@lilypond[quote,verbatim]
\new PianoStaff \with {
- \override StaffGrouper #'staff-staff-spacing =
+ \override StaffGrouper.staff-staff-spacing =
#'((basic-distance . 0)
(minimum-distance . 0)
(padding . 0)
declarations are equivalent:
@example
-\override StaffGrouper #'staff-staff-spacing =
+\override StaffGrouper.staff-staff-spacing =
#'((basic-distance . 7))
-\override StaffGrouper #'staff-staff-spacing =
+\override StaffGrouper.staff-staff-spacing =
#'((basic-distance . 7)
(minimum-distance . 0)
(padding . 0)
be determined automatically by LilyPond, but in some cases it may
be desirable to force a particular direction or placement.
-@strong{Articulation direction indicators}
+@menu
+* Articulation direction indicators::
+* The direction property::
+@end menu
+
+@node Articulation direction indicators
+@unnumberedsubsubsec Articulation direction indicators
By default some directions are always up or always down (e.g.
dynamics or fermata), while other things can alternate between
c2^( c)
@end lilypond
-@strong{The direction property}
+@node The direction property
+@unnumberedsubsubsec The direction property
-The position or direction of many layout objects is controlled
-by the @code{direction} property.
+The position or direction of many layout objects is controlled by the
+@code{direction} property.
-The value of the @code{direction} property may be
-set to @code{1}, meaning @qq{up} or @qq{above}, or to @w{@code{-1}},
-meaning @qq{down} or @qq{below}. The symbols @code{UP} and
-@code{DOWN} may be used instead of @code{1} and @w{@code{-1}}
-respectively. The default direction may be specified by setting
-@code{direction} to @code{0} or @code{CENTER}. Alternatively,
-in many cases predefined commands
-exist to specify the direction. These are all of the form
+The value of the @code{direction} property may be set to @code{1},
+meaning @qq{up} or @qq{above}, or to @w{@code{-1}}, meaning @qq{down} or
+@qq{below}. The symbols @code{UP} and @code{DOWN} may be used instead
+of @code{1} and @w{@code{-1}} respectively. The default direction may
+be specified by setting @code{direction} to @code{0} or @code{CENTER}.
+Alternatively, in many cases predefined commands exist to specify the
+direction. These are of the form
-@noindent
-@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
+@example
+@code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
+@end example
@noindent
-where @code{xxxNeutral} means @qq{use the default direction}.
+where @code{\xxxNeutral} means @qq{use the default} direction.
See @rlearning{Within-staff objects}.
-In a few cases, arpeggio being the only common example, the value
-of the @code{direction} property specifies whether the object
-is to be placed to the right or left of the parent object. In
-this case @w{@code{-1}} or @code{LEFT} means @qq{to the left} and
-@code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
-or @code{CENTER} means @qq{use the default} direction, as before.
+In a few cases, arpeggio for example, the value of the @code{direction}
+property can specify whether the object is to be placed to the right or
+left of the parent. In this case @w{@code{-1}} or @code{LEFT} means
+@qq{to the left} and @code{1} or @code{RIGHT} means @qq{to the right}.
+@code{0} or @code{CENTER} means @qq{use the default} direction.
@ignore
These all have side-axis set to #X
c2( c)
@end lilypond
+In polyphonic music, it is generally better to specify an explicit
+@code{voice} than change an object's direction. For more information.
+See @ref{Multiple voices}.
+
+@seealso
+Learning Manual:
+@rlearning{Within-staff objects}.
+
+Notation Reference:
+@ref{Multiple voices}.
+
@node Distances and measurements
@subsection Distances and measurements
@code{staff-space}. For an explanation and an example of its use,
see @rlearning{Length and thickness of objects}.
-
@seealso
Learning Manual:
@rlearning{Length and thickness of objects}.
@lilypond[verbatim,quote,relative=1]
\new Staff \with {
- \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+ \override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7)
}
{ a4 e' f b | d1 }
@end lilypond
@lilypond[verbatim,quote,relative=1]
\new Staff \with {
- \override StaffSymbol #'width = #23
+ \override StaffSymbol.width = #23
}
{ a4 e' f b | d1 }
@end lilypond
those that draw a straight line between the two objects, support in
addition the @code{line-spanner-interface}.
+@menu
+* Using the spanner-interface::
+* Using the line-spanner-interface::
+@end menu
+
+@node Using the spanner-interface
@unnumberedsubsubsec Using the @code{spanner-interface}
This interface provides two properties that apply to several spanners.
-@strong{@i{The @code{minimum-length} property}}
+@subsubsubheading The @code{minimum-length} property
The minimum length of the spanner is specified by the
@code{minimum-length} property. Increasing this usually has the
a~a
a
% increase the length of the tie
--\tweak #'minimum-length #5
+-\tweak minimum-length #5
~a
@end lilypond
\compressFullBarRests
R1*23
% increase the length of the rest bar
-\once \override MultiMeasureRest #'minimum-length = #20
+\once \override MultiMeasureRest.minimum-length = #20
R1*23
a1
@end lilypond
@lilypond[verbatim,quote,relative=2]
a \< a a a \!
% increase the length of the hairpin
-\override Hairpin #'minimum-length = #20
+\override Hairpin.minimum-length = #20
a \< a a a \!
@end lilypond
@lilypond[verbatim,quote,relative=2]
a( a)
a
--\tweak #'minimum-length #5
+-\tweak minimum-length #5
( a)
a\( a\)
a
--\tweak #'minimum-length #5
+-\tweak minimum-length #5
\( a\)
@end lilypond
e \glissando c'
% not effective alone
-\once \override Glissando #'minimum-length = #20
+\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
+\once \override Glissando.minimum-length = #20
+\once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods
e, \glissando c'
@end lilypond
@lilypond[verbatim,quote,relative=1]
% not effective alone
-\once \override Beam #'minimum-length = #20
+\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
+\once \override Beam.minimum-length = #20
+\once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods
e8 e e e
@end lilypond
-@strong{@i{The @code{to-barline} property}}
+@subsubsubheading The @code{to-barline} property
The second useful property of the @code{spanner-interface} is
@code{to-barline}. By default this is true, causing hairpins and
@lilypond[verbatim,quote,relative=2]
a \< a a a a \! a a a \break
-\override Hairpin #'to-barline = ##f
+\override Hairpin.to-barline = ##f
a \< a a a a \! a a a
@end lilypond
or on other spanners for which terminating on the bar line would
not be meaningful.
+@node Using the line-spanner-interface
@unnumberedsubsubsec Using the @code{line-spanner-interface}
Objects which support the @code{line-spanner-interface} include
@lilypond[relative=2,quote,verbatim]
e2 \glissando b
-\once \override Glissando #'(bound-details left Y) = #3
-\once \override Glissando #'(bound-details right Y) = #-2
+\once \override Glissando.bound-details.left.Y = #3
+\once \override Glissando.bound-details.right.Y = #-2
e2 \glissando b
@end lilypond
sub-lists of @code{bound-details}. For example:
@lilypond[relative=2,ragged-right,verbatim,quote]
-\override Glissando #'breakable = ##t
-\override Glissando #'(bound-details right-broken Y) = #-3
+\override Glissando.breakable = ##t
+\override Glissando.bound-details.right-broken.Y = #-3
c1 \glissando \break
f1
@end lilypond
to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
@lilypond[quote,ragged-right,relative=2,verbatim]
-\override TextSpanner #'(bound-details left text)
+\override TextSpanner.bound-details.left.text
= \markup { \small \bold Slower }
c2\startTextSpan b c a\stopTextSpan
@end lilypond
relative to the end point of the line:
@lilypond[relative=1,quote,verbatim]
-\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"
+\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
@end lilypond
\startTextSpan with \stopTextSpan, nor is it necessary to close
hairpins with @code{\!}.
-
@seealso
Internals Reference:
@rinternals{TextSpanner},
@lilypond[quote,verbatim,relative=1]
a1 a
-\override Score.BarLine #'stencil = ##f
+\override Score.BarLine.stencil = ##f
a a
-\revert Score.BarLine #'stencil
+\revert Score.BarLine.stencil
a a a
@end lilypond
@lilypond[quote,verbatim,relative=2]
a4 a
-\once \override NoteHead #'transparent = ##t
+\once \override NoteHead.transparent = ##t
a a
@end lilypond
here:
@lilypond[quote,verbatim,relative=2]
-\override Staff.Clef #'color = #white
+\override Staff.Clef.color = #white
a1
@end lilypond
@code{layer}, say @w{@code{-1}}, so that it is drawn earlier:
@lilypond[quote,verbatim,relative=2]
-\override Staff.Clef #'color = #white
-\override Staff.Clef #'layer = #-1
+\override Staff.Clef.color = #white
+\override Staff.Clef.layer = #-1
a1
@end lilypond
where the last three columns indicate whether the layout objects
will be visible in the positions shown at the head of the columns:
-@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}
@headitem Function @tab Vector @tab Before @tab At no @tab After
@headitem form @tab form @tab break @tab break @tab break
@item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible}
@item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible}
@item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible}
-@c omit KeyCancellation until it can be explained -td
-@c @item @code{KeyCancellation} @tab ?? @tab @code{begin-of-line-invisible}
+@item @code{KeyCancellation} @tab @code{Staff} @tab @code{begin-of-line-invisible}
@item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible}
@c omit LeftEdge until it can be explained -td
@c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible}
f4 g a b
f4 g a b
% Remove bar line at the end of the current line
-\once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
+\once \override Score.BarLine.break-visibility = ##(#f #t #t)
\break
f4 g a b
f4 g a b
@node Special considerations
@unnumberedsubsubsec Special considerations
-@strong{@emph{Visibility following explicit changes}}
+@subsubsubheading Visibility following explicit changes
@cindex key signature, visibility following explicit change
@cindex explicitKeySignatureVisibility
\key g \major
f4 g a b
% Try to remove all key signatures
-\override Staff.KeySignature #'break-visibility = #all-invisible
+\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b
\break
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
-\override Staff.KeySignature #'break-visibility = #all-invisible
+\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b
@end lilypond
-@strong{@emph{Visibility of cautionary accidentals}}
+@subsubsubheading Visibility of cancelling accidentals
-To remove the cautionary accidentals printed at an explicit key
+To remove the cancelling accidentals printed at an explicit key
change, set the Staff context property @code{printKeyCancellation}
to @code{#f}:
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.printKeyCancellation = ##f
-\override Staff.KeySignature #'break-visibility = #all-invisible
+\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
With these overrides only the accidentals before the notes remain
to indicate the change of key.
+Note that when changing the key to C@tie{}major or A@tie{}minor
+the cancelling accidentals would be the @emph{only} indication of
+the key change. In this case setting @code{printKeyCancellation} to
+@code{#f} has no effect:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.printKeyCancellation = ##f
+\key c \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+To suppress the cancelling accidentals even when the key is
+changed to C@tie{}major or A@tie{}minor, override
+the visibility of the @code{KeyCancellation} grob instead:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Staff.KeyCancellation.break-visibility = #all-invisible
+\key c \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
@c TODO Add visibility of cautionary accidentals before notes
-@strong{@emph{Automatic bars}}
+@subsubsubheading Automatic bars
@cindex automaticBars
@cindex bar lines, suppressing
@c TODO Add example
-@strong{@emph{Octavated clefs}}
+@subsubsubheading Octavated clefs
@cindex octavated clefs, visibility of
@cindex visibility of octavated clefs
property controls both the clef symbol and any octavation symbol
associated with it.
-
@seealso
Learning Manual:
-@rlearning{Visibility and color of objects}
+@rlearning{Visibility and color of objects}.
@node Line styles
@lilypond[relative=2,ragged-right,verbatim,quote]
d2 \glissando d'2
-\once \override Glissando #'style = #'dashed-line
+\once \override Glissando.style = #'dashed-line
d,2 \glissando d'2
-\override Glissando #'style = #'dotted-line
+\override Glissando.style = #'dotted-line
d,2 \glissando d'2
-\override Glissando #'style = #'zigzag
+\override Glissando.style = #'zigzag
d,2 \glissando d'2
-\override Glissando #'style = #'trill
+\override Glissando.style = #'trill
d,2 \glissando d'2
@end lilypond
@c TODO Complete
@lilypond[relative=2,ragged-right,verbatim,quote]
e2 \glissando f
-\once \override Glissando #'(bound-details right Y) = #-2
+\once \override Glissando.bound-details.right.Y = #-2
e2 \glissando f
@end lilypond
@lilypond[quote,verbatim,relative=1]
g4\< e' d' f\!
-\override Hairpin #'rotation = #'(20 -1 0)
+\override Hairpin.rotation = #'(20 -1 0)
g,,4\< e' d' f\!
@end lilypond
of the text too high.
@lilypond[quote,verbatim,relative=1]
-\override TextScript #'outside-staff-priority = ##f
+\override TextScript.outside-staff-priority = ##f
g4^\markup { \rotate #30 "a G" }
b^\markup { \rotate #30 "a B" }
des^\markup { \rotate #30 "a D-Flat" }
* Unpure-pure containers::
@end menu
-
@seealso
Learning Manual:
@rlearning{Tweaking output},
@ref{Explaining the Internals Reference},
@ref{Modifying properties}.
+Extending LilyPond:
+@rextend{Interfaces for programmers}.
+
Installed Files:
@file{scm/define-grobs.scm}.
Snippets:
@rlsr{Tweaks and overrides}.
-Extending:
-@rextend{Interfaces for programmers}.
-
Internals Reference:
@rinternals{All layout objects}.
for positioning rehearsal marks on such objects.
@seealso
-@ref{Using the break-alignable-interface},
+Notation Reference:
+@ref{Using the break-alignable-interface}.
+
+Extending LilyPond:
@rextend{Callback functions}.
@menu
@lilypond[verbatim,quote,relative=2]
a-3
a
--\tweak #'X-offset #0
--\tweak #'Y-offset #0
+-\tweak X-offset #0
+-\tweak Y-offset #0
-3
a
--\tweak #'X-offset #-1
--\tweak #'Y-offset #1
+-\tweak X-offset #-1
+-\tweak Y-offset #1
-3
@end lilypond
@node Using the self-alignment-interface
@unnumberedsubsubsec Using the @code{self-alignment-interface}
-@emph{Self-aligning objects horizontally}
+@subsubsubheading Self-aligning objects horizontally
The horizontal alignment of an object which supports the
@code{self-alignment-interface} is controlled by the value of
@lilypond[quote,verbatim,relative=1]
a'
--\tweak #'self-alignment-X #-1
+-\tweak self-alignment-X #-1
^"left-aligned"
--\tweak #'self-alignment-X #0
+-\tweak self-alignment-X #0
^"center-aligned"
--\tweak #'self-alignment-X #RIGHT
+-\tweak self-alignment-X #RIGHT
^"right-aligned"
--\tweak #'self-alignment-X #-2.5
+-\tweak self-alignment-X #-2.5
^"aligned further to the right"
@end lilypond
-@emph{Self-aligning objects vertically}
+@subsubsubheading Self-aligning objects vertically
Objects may be aligned vertically in an analogous way to aligning
them horizontally if the @code{Y-offset} property is set to
@code{CENTER}, and @code{UP} may be substituted for @w{@code{-1}},
@code{0}, and @code{1}, respectively.
-@emph{Self-aligning objects in both directions}
+@subsubsubheading Self-aligning objects in both directions
By setting both @code{X-offset} and @code{Y-offset}, an object may
be aligned in both directions simultaneously.
@lilypond[quote,verbatim,relative=2]
a
--\tweak #'self-alignment-X #0.5 % move horizontally left
--\tweak #'Y-offset #ly:self-alignment-interface::y-aligned-on-self
--\tweak #'self-alignment-Y #-1 % move vertically up
+-\tweak self-alignment-X #0.5 % move horizontally left
+-\tweak Y-offset #ly:self-alignment-interface::y-aligned-on-self
+-\tweak self-alignment-Y #-1 % move vertically up
-3 % third finger
@end lilypond
@lilypond[verbatim,quote,relative=1]
% The rehearsal mark will be centered above the Clef
-\override Score.RehearsalMark #'break-align-symbols = #'(clef)
+\override Score.RehearsalMark.break-align-symbols = #'(clef)
\key a \major
\clef treble
\mark "↓"
e1
% The rehearsal mark will be centered above the Time Signature
-\override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
+\override Score.RehearsalMark.break-align-symbols = #'(time-signature)
\key a \major
\clef treble
\time 3/4
\mark "↓"
e2.
% The rehearsal mark will be centered above the Breath Mark
-\override Score.RehearsalMark #'break-align-symbols = #'(breathing-sign)
+\override Score.RehearsalMark.break-align-symbols = #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
@lilypond[verbatim,quote,relative=1]
% The rehearsal mark will be centered above the Key Signature
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
e1
% The rehearsal mark will be centered above the Clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef bass
\mark "↓"
% The rehearsal mark will be centered above the Bar Line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be centered above the Key Signature
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
\key a \major
\clef treble
\time 4/4
\mark "↓"
e1
% The RehearsalMark will be aligned with the left edge of the Key Signature
-\once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
+\once \override Score.KeySignature.break-align-anchor-alignment = #LEFT
\mark "↓"
\key a \major
e1
% The RehearsalMark will be aligned with the right edge of the Key Signature
-\once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
+\once \override Score.KeySignature.break-align-anchor-alignment = #RIGHT
\key a \major
\mark "↓"
e1
@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted right by 3.5 staff-spaces
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
-\once \override Score.KeySignature #'break-align-anchor = #3.5
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
+\once \override Score.KeySignature.break-align-anchor = #3.5
\key a \major
\mark "↓"
e1
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted left by 2 staff-spaces
-\once \override Score.KeySignature #'break-align-anchor = #-2
+\once \override Score.KeySignature.break-align-anchor = #-2
\key a \major
\mark "↓"
e1
@lilypond[verbatim,quote]
XinO = {
- \once \override NoteHead #'stencil = #ly:text-interface::print
- \once \override NoteHead #'text = \markup {
+ \once \override NoteHead.stencil = #ly:text-interface::print
+ \once \override NoteHead.text = \markup {
\combine
\halign #-0.7 \draw-circle #0.85 #0.2 ##f
\musicglyph #"noteheads.s2cross"
@c TODO Add inserting Postscript or ref to later
-
@seealso
Notation Reference:
@ref{Graphic notation inside markup},
@cindex Bézier curves, control points
@cindex control points, Bézier curves
-Ties, slurs and phrasing slurs are drawn as third-order Bézier
-curves. If the shape of the tie or slur which is calculated
-automatically is not optimum, the shape may be modified manually by
-explicitly specifying the four control points required to define
-a third-order Bézier curve.
+@code{Tie}s, @code{Slur}s, @code{PhrasingSlur}s,
+@code{LaissezVibrerTie}s and @code{RepeatTie}s are all drawn as
+third-order Bézier curves. If the shape of the tie or slur which
+is calculated automatically is not optimum, the shape may be
+modified manually in two ways:
+
+@enumerate a
+@item
+by specifying the displacements to be made to the control points
+of the automatically calculated Bézier curve, or
+
+@item
+by explicitly specifying the positions of the four control points
+required to define the wanted curve.
+@end enumerate
+
+Both methods are explained below. The first method is more suitable
+if only slight adjustments to the curve are required; the second may
+be better for creating curves which are related to just a single
+note.
+
+@subsubsubheading Cubic Bézier curves
Third-order or cubic Bézier curves are defined by four control
points. The first and fourth control points are precisely the
head towards the third and continuing to bend over to head towards
the fourth, arriving there travelling directly from the third
control point. The curve is entirely contained in the
-quadrilateral defined by the four control points.
+quadrilateral defined by the four control points. Translations,
+rotations and scaling of the control points all result in exactly
+the same operations on the curve.
+
+@subsubsubheading Specifying displacements from current control points
-Here is an example of a case where the tie is not optimum, and
-where @code{\tieDown} would not help.
+@cindex shaping slurs and ties
+@funindex \shape
+
+In this example the automatic placement of the tie is not optimum,
+and @code{\tieDown} would not help.
@lilypond[verbatim,quote,relative=1]
<<
>>
@end lilypond
-One way of improving this tie is to manually modify its control
-points, as follows.
+Adjusting the control points of the tie with @code{\shape} allows
+the collisions to be avoided.
-The coordinates of the Bézier control points are specified in units
-of staff-spaces. The X@tie{}coordinate is relative to the reference
-point of the note to which the tie or slur is attached, and the
-Y@tie{}coordinate is relative to the staff center line. The
-coordinates are entered as a list of four pairs of decimal numbers
-(reals). One approach is to estimate the coordinates of the two
-end points, and then guess the two intermediate points. The optimum
-values are then found by trial and error.
+The syntax of @code{\shape} is
+
+@example
+[-]@code{\shape} @var{displacements} @var{item}
+@end example
-It is useful to remember that a symmetric curve requires symmetric
-control points, and that Bézier curves have the useful property that
-transformations of the curve such as translation, rotation and
-scaling can be achieved by applying the same transformation to the
-curve's control points.
+This will reposition the control-points of @var{item} by the amounts
+given by @var{displacements}. The @var{displacements} argument is a
+list of number pairs or a list of such lists. Each element of a pair
+represents the displacement of one of the coordinates of a
+control-point. If @var{item} is a string, the result is
+@code{\once\override} for the specified grob type. If @var{item} is
+a music expression, the result is the same music expression with an
+appropriate tweak applied.
+
+In other words, the @code{\shape} function can act as either a
+@code{\once\override} command or a @code{\tweak} command depending
+on whether the @var{item} argument is a grob name, like @qq{Slur},
+or a music expression, like @qq{(}. The @var{displacements} argument
+specifies the displacements of the four control points as a list of
+four pairs of (dx . dy) values in units of staff-spaces (or a list
+of such lists if the curve has more than one segment).
+
+The leading hyphen is required if and only if the @code{\tweak} form
+is being used.
+
+So, using the same example as above and the @code{\once\override}
+form of @code{\shape}, this will raise the tie by half a staff-space:
+
+@lilypond[verbatim,quote,relative=1]
+<<
+ {
+ \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
+ e1~ e
+ }
+\\
+ { r4 <g c,> <g c,> <g c,> }
+>>
+@end lilypond
-For the example above the following override gives a satisfactory
-tie. Note the placement -- it has to be immediately before the note
-to which the start of the tie (or slur) is attached.
+This positioning of the tie is better, but maybe it should be raised
+more in the center. The following example does this, this time using
+the alternative @code{\tweak} form:
@lilypond[verbatim,quote,relative=1]
<<
{
- \once \override Tie
- #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
- e1 ~ e
+ e1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e
}
\\
{ r4 <g c,> <g c,> <g c,> }
>>
@end lilypond
+Changes to the horizontal positions of the control points may be made
+in the same way, and two different curves starting at the same
+musical moment may also be shaped:
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+c8(\( a) a'4 e c\)
+\shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
+\shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
+c8(\( a) a'4 e c\)
+@end lilypond
+
+The @code{\shape} function can also displace the control points of
+curves which stretch across line breaks. Each piece of the broken
+curve can be given its own list of offsets. If changes to a
+particular segment are not needed, the empty list can serve as a
+placeholder. In this example the line break makes the single slur
+look like two:
+
+@lilypond[verbatim,quote,ragged-right,relative=1]
+c4( f g c
+\break
+d,4 c' f, c)
+@end lilypond
+
+Changing the shapes of the two halves of the slur makes it clearer
+that the slur continues over the line break:
+
+@lilypond[verbatim,quote,ragged-right,relative=1]
+% () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
+% if any of the segments does not need to be changed
+\shape #'(
+ (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
+ ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
+ ) Slur
+c4( f g c
+\break
+d,4 c' f, c)
+@end lilypond
+
+If an S-shaped curve is required the control points must always be
+adjusted manually --- LilyPond will never select such shapes
+automatically.
+
+@lilypond[verbatim,quote,relative=2]
+c8( e b-> f d' a e-> g)
+\shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
+c8\( e b-> f d' a e-> g\)
+@end lilypond
+
+@subsubsubheading Specifying control points explicitly
+
+The coordinates of the Bézier control points are specified in units
+of staff-spaces. The X@tie{}coordinate is relative to the reference
+point of the note to which the tie or slur is attached, and the
+Y@tie{}coordinate is relative to the staff center line. The
+coordinates are specified as a list of four pairs of decimal numbers
+(reals). One approach is to estimate the coordinates of the two
+end points, and then guess the two intermediate points. The optimum
+values are then found by trial and error. Be aware that these values
+may need to be manually adjusted if any further changes are made to
+the music or the layout.
+
+One situation where specifying the control points explicitly is
+preferable to specifying displacements is when they need to be
+specified relative to a single note. Here is an example of this.
+It shows one way of indicating a slur extending into alternative
+sections of a volta repeat.
+
+@lilypond[verbatim,quote,relative=2]
+c1
+\repeat volta 3 { c4 d( e f }
+\alternative {
+ { g2) d }
+ {
+ g2
+ % create a slur and move it to a new position
+ % the <> is just an empty chord to carry the slur termination
+ -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
+ f,
+ }
+ {
+ e'2
+ % create a slur and move it to a new position
+ -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
+ f,
+ }
+}
+@end lilypond
+
@knownissues
It is not possible to modify shapes of ties or slurs by changing
the @code{control-points} property if there are multiple ties or slurs
@cindex unpure containers, Scheme
@cindex horizontal spacing, overriding
+
@node Unpure-pure containers
@subsection Unpure-pure containers
'(-0.5 . 0.5)))))
squareLineCircleSpace = {
- \override NoteHead #'stencil = #square-line-circle-space
+ \override NoteHead.stencil = #square-line-circle-space
}
smartSquareLineCircleSpace = {
\squareLineCircleSpace
- \override NoteHead #'Y-extent =
+ \override NoteHead.Y-extent =
#(ly:make-unpure-pure-container
ly:grob::stencil-height
(lambda (grob start end) (ly:grob::stencil-height grob)))
\new Voice \with { \remove "Stem_engraver" }
\relative c'' {
\squareLineCircleSpace
- cis4 ces cisis c
+ cis4 ces disis d
\smartSquareLineCircleSpace
- cis4 ces cisis c
+ cis4 ces disis d
}
@end lilypond
@item @code{@var{@dots{}music@dots{}}}
@tab normal LilyPond input, using @code{$} (in places where only
Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
-value or music function argument) to reference arguments
+value or music function argument or music inside of music lists) to
+reference arguments
(eg. @samp{#arg1}).
@end multitable
@ref{Predefined type predicates}. User-defined type predicates
are also allowed.
-
@seealso
-
Notation Reference:
@ref{Predefined type predicates}.
-Extending:
+Extending Lilypond:
@rextend{Music functions}.
Installed Files:
(parser location padding)
(number?)
#{
- \once \override TextScript #'padding = #padding
+ \once \override TextScript.padding = #padding
#})
\relative c''' {
In addition to numbers, we can use music expressions such
as notes for arguments to music functions:
-@c TODO: use a better example (the music argument is redundant).
-
@lilypond[quote,verbatim,ragged-right]
custosNote =
#(define-music-function
(parser location note)
(ly:music?)
#{
- \once \override Voice.NoteHead #'stencil =
- #ly:text-interface::print
- \once \override Voice.NoteHead #'text =
- \markup \musicglyph #"custodes.mensural.u0"
- \once \override Voice.Stem #'stencil = ##f
- $note
+ \tweak NoteHead.stencil #ly:text-interface::print
+ \tweak NoteHead.text
+ \markup \musicglyph #"custodes.mensural.u0"
+ \tweak Stem.stencil ##f
+ #note
#})
\relative c' { c4 d e f \custosNote g }
tempoPadded =
#(define-music-function
(parser location padding tempotext)
- (number? string?)
+ (number? markup?)
#{
- \once \override Score.MetronomeMark #'padding = #padding
+ \once \override Score.MetronomeMark.padding = #padding
\tempo \markup { \bold #tempotext }
#})
\relative c'' {
\tempo \markup { "Low tempo" }
c4 d e f g1
- \tempoPadded #4.0 #"High tempo"
+ \tempoPadded #4.0 "High tempo"
g4 f e d c1
}
@end lilypond
projects / lilypond.git / blobdiff