Guide, node Updating translation committishes..
@end ignore
-@c \version "2.14.0"
+@c \version "2.16.0"
@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
* Modifying context plug-ins::
* Changing context default settings::
* Defining new contexts::
-* Aligning contexts::
+* 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.
-Note that the @code{\set} command itself and the context must be
-omitted when the context default values are specified in this way:
+@example
+\layout @{
+ \context @{
+ \Voice
+ [context settings for all Voice contexts]
+ @}
+ \context @{
+ \Staff
+ [context settings for all Staff contexts]
+ @}
+@}
+@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 {
\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
- 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
+Directly setting a context property
-Modifications can be made to the @code{Score} context or all
-@code{Voice} contexts in a similar way.
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a\ff a
+ }
+ \layout {
+ \context {
+ \Staff
+ fontSize = #-4
+ }
+ }
+}
+@end lilypond
-@knownissues
+@item
+A predefined command such as @code{\dynamicUp} or a music
+expression like @code{\accidentalStyle "dodecaphonic"}
-It is not possible to collect context changes in a variable and apply
-them to a @code{\context} definition by referring to that variable.
+@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
-The @code{\Staff \RemoveEmptyStaves} will overwrite your current
-@code{\Staff} settings. If you wish to change the defaults for a
-staff which uses @code{\Staff \RemoveEmptyStaves}, you must do so
-after calling @code{\Staff \RemoveEmptyStaves}, ie
+@item
+A user-defined variable containing a @code{\with} block; for details
+of the @code{\with} block see
+@ref{Changing just one specific context}.
-@example
-\layout @{
- \context @{
- \Staff \RemoveEmptyStaves
+@lilypond[quote,verbatim]
+StaffDefaults = \with {
+ fontSize = #-4
+}
- \override Stem #'thickness = #4.0
- @}
+\score {
+ \new Staff {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a a
+ }
+ }
+ \layout {
+ \context {
+ \Staff
+ \StaffDefaults
+ }
+ }
+}
+@end lilypond
+
+@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
-@c TODO: add \with in here.
+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 {
+ \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
+ }
+ }
+ >>
+}
+@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
+
+@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
squashedPosition = #0
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
\alias Voice
}
\context { \Staff
@example
\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
squashedPosition = #0
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
\alias Voice
@}
@end example
@end example
-@node Aligning contexts
-@subsection Aligning contexts
+@node Context layout order
+@subsection Context layout order
-New contexts may be aligned above or below existing contexts. This
-could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
-in ossia,
+@cindex contexts, layout order
+@funindex \accepts
+@funindex \denies
-@c TODO Better example needed. Ref LM, and expand on it.
+Contexts are normally positioned in a system from top to bottom
+in the order in which they are encountered in the input file. When
+contexts are nested, the outer context will include inner nested
+contexts as specified in the input file, provided the inner contexts
+are included in the outer context's @qq{accepts} list. Nested
+contexts which are not included in the outer context's @qq{accepts}
+list will be repositioned below the outer context rather than nested
+within it.
-@cindex ossia
-@funindex alignAboveContext
-@funindex alignBelowContext
+The @qq{accepts} list of a context can be changed with the
+@code{\accepts} and @code{\denies} commands. @code{\accepts} adds a
+context to the @qq{accepts} list and @code{\denies} removes a context
+from the list. For example, it would not normally be desirable for
+chord names to be nested within a @code{Staff} context, so the
+@code{ChordNames} context is not included by default in the @qq{accepts}
+list of the @code{Staff} context, but if this were to be required it can
+be done:
-@lilypond[quote,ragged-right]
-ossia = { f4 f f f }
-\score{
- \relative c' \new Staff = "main" {
- c4 c c c
- <<
- \new Staff \with { alignAboveContext = #"main" } \ossia
- { d8 f d f d f d f }
- >>
+@lilypond[verbatim,quote]
+\score {
+ \new Staff {
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
}
}
@end lilypond
-@cindex nested contexts
-@cindex contexts, nested
-
-@funindex \accepts
-@funindex \denies
-
-Contexts like @code{PianoStaff} can contain other contexts
-nested within them. Contexts which are acceptable for nesting
-are defined by the @qq{accepts} list of a context. Contexts
-which are not in this list are placed below the outer context
-in the printed score.
-For example, the @code{PianoStaff} context is defined by default
-to accept @code{Staff} and @code{FiguredBass} contexts within
-it, but not (for example) a @code{Lyrics} context. So in the
-following structure the lyrics are placed below the piano staff
-rather than between the two staves:
-
-@lilypond[verbatim,quote,relative=1]
-\new PianoStaff
-<<
- \new Staff { e4 d c2 }
- \addlyrics { Three blind mice }
+@lilypond[verbatim,quote]
+\score {
\new Staff {
- \clef "bass"
- { c,1 }
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
}
->>
+ \layout {
+ \context {
+ \Staff
+ \accepts "ChordNames"
+ }
+ }
+}
@end lilypond
-The @qq{accepts} list of a context can be modified to include
-additional nested contexts, so if we wanted the lyrics to appear
-between the two staves we could use:
+@code{\denies} is mainly used when a new context is being based on
+another, but the required nesting differs. For example, the
+@code{VaticanaStaff} context is based on the @code{Staff} context, but
+with the @code{VaticanaVoice} context substituted for the @code{Voice}
+context in the @qq{accepts} list.
-@lilypond[verbatim,quote,relative=1]
-\new PianoStaff \with { \accepts Lyrics }
-<<
- \new Staff { e4 d c2 }
- \addlyrics { Three blind mice }
- \new Staff {
- \clef "bass"
- { c,1 }
- }
->>
-@end lilypond
+Note that a context will be silently created implicitly if a command
+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
+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}.
-The opposite of @code{\accepts} is @code{\denies}; this removes a
-context from the @qq{accepts} list.
@node Explaining the Internals Reference
@section Explaining the Internals Reference
-
@menu
* Navigating the program reference::
* Layout interfaces::
@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
@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
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 <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 explicit
+form of the @code{\tweak} command:
+
+@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.
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}
@menu
* Input modes::
* Direction and placement::
-* Context layout order::
* Distances and measurements::
* Staff symbol properties::
* Spanners::
@strong{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
TrillPitchGroup - not tried
@end ignore
-These indications affect all notes until they are cancelled.
+These indications affect all notes until they are canceled.
@lilypond[verbatim,quote,relative=2]
c2( c)
c2( c)
@end lilypond
-
-@node Context layout order
-@subsection Context layout order
-
-@cindex contexts, layout order
-
-Contexts are normally positioned in a system from top to bottom
-in the order in which they are encountered in the input file. When
-contexts are nested, the outer context will include inner nested
-contexts as specified in the input file, provided the inner contexts
-are included in the outer context's @qq{accepts} list. Nested
-contexts which are not included in the outer context's @qq{accepts}
-list will be repositioned below the outer context rather than nested
-within it.
-
-Note that a context will be silently created implicitly if a command
-is encountered when there is no suitable context available to
-contain it. This can give rise to unexpected new staves or scores.
-
-The default order in which contexts are laid out and the
-@qq{accepts} list can be changed, see @ref{Aligning contexts}.
+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
-Usage Manual:
-@rprogram{An extra staff appears}.
+Learning Manual:
+@rlearning{Within-staff objects}.
+
+Notation Reference:
+@ref{Multiple voices}.
@node 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}.
\startTextSpan with \stopTextSpan, nor is it necessary to close
hairpins with @code{\!}.
-
@seealso
Internals Reference:
@rinternals{TextSpanner},
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
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
* Vertical grouping of grobs::
* Modifying stencils::
* Modifying shapes::
+* 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
@c TODO Add inserting Postscript or ref to later
-
@seealso
Notation Reference:
@ref{Graphic notation inside markup},
Internals Reference:
@rinternals{TieColumn}.
+@cindex Scheme, pure containers
+@cindex Scheme, unpure containers
+@cindex pure containers, Scheme
+@cindex unpure containers, Scheme
+@cindex horizontal spacing, overriding
+
+
+@node Unpure-pure containers
+@subsection Unpure-pure containers
+
+Unpure-pure containers are useful for overriding @emph{Y-axis} spacing
+calculations - specifically @code{Y-offset} and @code{Y-extent} - with a
+Scheme function instead of a literal (i.e. a number or pair).
+
+For certain grobs, the @code{Y-extent} is based on the @code{stencil}
+property, overriding the stencil property of one of these will
+require an additional @code{Y-extent} override with an unpure-pure
+container. When a function overrides a @code{Y-offset} and/or
+@code{Y-extent} it is assumed that this will trigger line breaking
+calculations too early during compilation. So the function is not
+evaluated at all (usually returning a value of @samp{0} or
+@samp{'(0 . 0)}) which can result in collisions. A @q{pure} function
+will not affect properties, objects or grob suicides and therefore will
+always have its Y-axis-related evaluated correctly.
+
+Currently, there are about thirty functions that are already considered
+@q{pure} and Unpure-pure containers are a way to set functions not on
+this list as @q{pure}. The @q{pure} function is evaluated @emph{before}
+any line-breaking and so the horizontal spacing can be adjusted
+@q{in time}. The @q{unpure} function is then evaluated @emph{after}
+line breaking.
+
+@warning{As it is difficult to always know which functions are on this
+list we recommend that any @q{pure} functions you create do not use
+@code{Beam} or @code{VerticalAlignment} grobs.}
+
+An unpure-pure container is constructed as follows;
+
+@code{(ly:make-unpure-pure-container f0 f1)}
+
+where @code{f0} is a function taking @var{n} arguments (@var{n >= 1})
+and the first argument must always be the grob. This is the function
+that gives the actual result. @var{f1} is the function being labeled
+as @q{pure} that takes @var{n + 2} arguments. Again, the first argument
+must always still be the grob but the second and third are @q{start}
+and @q{end} arguments.
+
+@var{start} and @var{end} are, for all intents and purposes, dummy
+values that only matter for @code{Spanners} (i.e @code{Hairpin} or
+@code{Beam}), that can return different height estimations based on a
+starting and ending column.
+
+The rest are the other arguments to the first function (which
+may be none if @var{n = 1}).
+
+The results of the second function are used as an approximation of the
+value needed which is then used by the first function to get the real
+value which is then used for fine-tuning much later during the spacing
+process.
+
+@lilypond[verbatim,quote,ragged-right]
+#(define (square-line-circle-space grob)
+(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
+ (notename (ly:pitch-notename pitch)))
+ (if (= 0 (modulo notename 2))
+ (make-circle-stencil 0.5 0.0 #t)
+ (make-filled-box-stencil '(0 . 1.0)
+ '(-0.5 . 0.5)))))
+
+squareLineCircleSpace = {
+ \override NoteHead #'stencil = #square-line-circle-space
+}
+
+smartSquareLineCircleSpace = {
+ \squareLineCircleSpace
+ \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
+ \smartSquareLineCircleSpace
+ cis4 ces cisis c
+}
+@end lilypond
+
+In the first measure, without the unpure-pure container, the spacing
+engine does not know the width of the note head and lets it collide with
+the accidentals. In the second measure, with unpure-pure containers,
+the spacing engine knows the width of the note heads and avoids the
+collision by lengthening the line accordingly.
+
+Usually for simple calculations nearly-identical functions for both the
+@q{unpure} and @q{pure} parts can be used, by only changing the number
+of arguments passed to, and the scope of, the function.
+
+@warning{If a function is labeled as @q{pure} and it turns out not to
+be, the results can be unexpected.}
+
@node Using music functions
@section Using music functions
must return @code{#t}.
@item @code{@var{@dots{}music@dots{}}}
-@tab normal LilyPond input, using @code{$} to reference arguments
-(eg. @samp{$arg1}).
+@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 or music inside of music lists) to
+reference arguments
+(eg. @samp{#arg1}).
@end multitable
-
The @code{parser} and @code{location} arguments are mandatory, and
are used in some advanced situations as described in the
@q{Extending} manual (see @rextend{Music functions}). For
@example
boolean?
cheap-list? @emph{(use instead of }@q{list?}@emph{ for faster processing)}
+ly:duration?
ly:music?
+ly:pitch?
markup?
number?
pair?
@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
- \tempo \markup { \bold $tempotext }
+ \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