1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @node Changing defaults
14 @chapter Changing defaults
16 The purpose of LilyPond's design is to provide the finest quality
17 output by default. Nevertheless, it may happen that you need to
18 change this default layout. The layout is controlled through a large
19 number of @q{knobs and switches} collectively called @q{properties}.
20 A tutorial introduction to accessing and modifying these properties
21 can be found in the Learning Manual, see @rlearning{Tweaking output}.
22 This should be read first. This chapter covers similar ground, but
23 in a style more appropriate to a reference manual.
25 @cindex Internals Reference
27 The definitive description of the controls available for tuning can
28 be found in a separate document: @rinternalsnamed{Top,the Internals
29 Reference}. That manual lists all the variables, functions and
30 options available in LilyPond. It is written as a HTML document,
32 @c leave the @uref as one long line.
33 @uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/internals/,on@/-line},
34 and is also included with the LilyPond documentation package.
36 Internally, LilyPond uses Scheme (a LISP dialect) to provide
37 infrastructure. Overriding layout decisions in effect accesses the
38 program internals, which requires Scheme input. Scheme elements are
39 introduced in a @file{.ly} file with the hash
40 mark@tie{}@code{#}.@footnote{@rextend{Scheme tutorial}, contains a
41 short tutorial on entering numbers, lists, strings, and symbols in
46 * Interpretation contexts::
47 * Explaining the Internals Reference::
48 * Modifying properties::
49 * Useful concepts and properties::
51 * Using music functions::
55 @node Interpretation contexts
56 @section Interpretation contexts
58 This section describes what contexts are, and how to modify them.
61 * Contexts explained::
62 * Creating and referencing contexts::
63 * Keeping contexts alive::
64 * Modifying context plug-ins::
65 * Changing context default settings::
66 * Defining new contexts::
67 * Context layout order::
72 @rlearning{Contexts and engravers}.
75 @file{ly/engraver-init.ly},
76 @file{ly/performer-init.ly}.
79 @rlsr{Contexts and engravers}.
82 @rinternals{Contexts},
83 @rinternals{Engravers and Performers}.
86 @node Contexts explained
87 @subsection Contexts explained
90 @c TODO Rethink and rewrite
92 >> > > - list of contexts: my *danger unmaintainable*
93 >> > > alarm just went off. I'm
95 I knew it would... And leaving out some of them is perfectly fine
97 I do think that a list like this, with the main contexts and a
99 description of what they do (perhaps also with a note about what
101 behavior is associated with each of them, but this may be
103 should be there, and then we could simply list the remaining ones
105 further explanation and with links to the IR.
108 @c TODO Improve layout, order and consistency of wording -td
110 @c TODO Add introduction which explains contexts in generality -td
112 @c TODO Describe propagation of property values -td
114 Contexts are arranged hierarchically:
117 * Score - the master of all contexts::
118 * Top-level contexts - staff containers::
119 * Intermediate-level contexts - staves::
120 * Bottom-level contexts - voices::
123 @node Score - the master of all contexts
124 @unnumberedsubsubsec Score - the master of all contexts
126 This is the top level notation context. No other context can
127 contain a Score context. By default the Score context handles
128 the administration of time signatures and makes sure that items
129 such as clefs, time signatures, and key-signatures are aligned
132 A Score context is instantiated implicitly when a
133 @code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is
136 @node Top-level contexts - staff containers
137 @unnumberedsubsubsec Top-level contexts - staff containers
139 @strong{@emph{StaffGroup}}
141 Groups staves while adding a bracket on the left side, grouping
142 the staves together. The bar lines of the contained staves are
143 connected vertically. @code{StaffGroup} only consists of a collection
144 of staves, with a bracket in front and spanning bar lines.
146 @strong{@emph{ChoirStaff}}
148 Identical to @code{StaffGroup} except that the bar lines of the
149 contained staves are not connected vertically.
151 @strong{@emph{GrandStaff}}
153 A group of staves, with a brace on the left side, grouping the
154 staves together. The bar lines of the contained staves are
155 connected vertically.
157 @strong{@emph{PianoStaff}}
159 Just like @code{GrandStaff}, but with support for instrument names
160 to the left of each system.
162 @node Intermediate-level contexts - staves
163 @unnumberedsubsubsec Intermediate-level contexts - staves
165 @strong{@emph{Staff}}
167 Handles clefs, bar lines, keys, accidentals. It can contain
168 @code{Voice} contexts.
170 @strong{@emph{RhythmicStaff}}
172 Like @code{Staff} but for printing rhythms. Pitches are ignored;
173 the notes are printed on one line.
175 @strong{@emph{TabStaff}}
177 Context for generating tablature. By default lays the music
178 expression out as a guitar tablature, printed on six lines.
180 @strong{@emph{DrumStaff}}
182 Handles typesetting for percussion. Can contain @code{DrumVoice}
184 @strong{@emph{VaticanaStaff}}
186 Same as @code{Staff}, except that it is designed for typesetting
187 a piece in gregorian style.
189 @strong{@emph{MensuralStaff}}
191 Same as @code{Staff}, except that it is designed for typesetting
192 a piece in mensural style.
194 @node Bottom-level contexts - voices
195 @unnumberedsubsubsec Bottom-level contexts - voices
197 Voice-level contexts initialise certain properties and start
198 appropriate engravers. A bottom-level context is one without
199 @code{defaultchild}. While it is possible to let it
200 accept/@/contain subcontexts, they can only be created and entered
203 @strong{@emph{Voice}}
205 Corresponds to a voice on a staff. This context handles the
206 conversion of dynamic signs, stems, beams, super- and sub-scripts,
207 slurs, ties, and rests. You have to instantiate this explicitly
208 if you require multiple voices on the same staff.
210 @strong{@emph{VaticanaVoice}}
212 Same as @code{Voice}, except that it is designed for typesetting
213 a piece in gregorian style.
215 @strong{@emph{MensuralVoice}}
217 Same as @code{Voice}, with modifications for typesetting a piece in
220 @strong{@emph{Lyrics}}
222 Corresponds to a voice with lyrics. Handles the printing of a
223 single line of lyrics.
225 @strong{@emph{DrumVoice}}
227 The voice context used in a percussion staff.
229 @strong{@emph{FiguredBass}}
231 The context in which @code{BassFigure} objects are created from
232 input entered in @code{\figuremode} mode.
234 @strong{@emph{TabVoice}}
236 The voice context used within a @code{TabStaff} context. Usually
237 left to be created implicitly.
239 @strong{@emph{CueVoice}}
241 A voice context used to render notes of a reduced size, intended
242 primarily for adding cue notes to a staff, see @ref{Formatting
243 cue notes}. Usually left to be created implicitly.
245 @strong{@emph{ChordNames}}
247 Typesets chord names.
252 Then the following, which I don't know what to do with:
254 * GregorianTranscriptionVoice
255 * GregorianTranscriptionStaff
258 Engraves fretboards from chords. Not easy... Not
260 There is now some documentation on FretBoards in the NR, under
261 instrument-specific notation -- cds.
266 Hard coded entry point for LilyPond. Cannot be tuned.
268 Silently discards all musical information given to this
273 @node Creating and referencing contexts
274 @subsection Creating and referencing contexts
279 @cindex referencing contexts
280 @cindex Contexts, creating and referencing
282 LilyPond will create lower-level contexts automatically if a music
283 expression is encountered before a suitable context exists, but this
284 is usually successful only for simple scores or music fragments like
285 the ones in the documentation. For more complex scores it is
286 advisable to specify all contexts explicitly with either the
287 @code{\new} or @code{\context} command. The syntax of
288 these two commands is very similar:
291 [\new | \context] @var{Context} [ = @var{name}] [@var{music-expression}]
295 where either @code{\new} or @code{\context} may be specified.
296 @var{Context} is the type of context which is to be created,
297 @var{name} is an optional name to be given to the particular context
298 being created and @var{music-expression} is a single music expression
299 that is to be interpreted by the engravers and performers in this
302 The @code{\new} prefix without a name is commonly used to create
303 scores with many staves:
305 @lilypond[quote,verbatim,relative=2]
308 % leave the Voice context to be created implicitly
318 and to place several voices into one staff:
320 @lilypond[quote,verbatim,relative=2]
336 @code{\new} should always be used to specify unnamed contexts.
338 The difference between @code{\new} and @code{\context} is in the
343 @code{\new} with or without a name will always create a fresh,
344 distinct, context, even if one with the same name already exists:
346 @lilypond[quote,verbatim,relative=2]
362 @code{\context} with a name specified will create a distinct context
363 only if a context of the same type with the same name in the same
364 context hierarchy does not already exist. Otherwise it will be taken
365 as a reference to that previously created context, and its music
366 expression will be passed to that context for interpretation.
368 One application of named contexts is in separating the score layout
369 from the musical content. Either of these two forms is valid:
371 @lilypond[quote,verbatim]
385 \context Voice = "one" {
390 \context Voice = "two" {
399 @lilypond[quote,verbatim]
404 \context Voice = "one" {
407 \context Voice = "two" {
413 \context Voice = "one" {
418 \context Voice = "two" {
428 Alternatively, variables may be employed to similar effect. See
429 @rlearning{Organizing pieces with variables}.
433 @code{\context} with no name will match the first of any previously
434 created contexts of the same type in the same context heirarchy,
435 even one that has been given a name, and its music expression will be
436 passed to that context for interpretation. This form is rarely
437 useful. However, @code{\context} with no name and no music expression
438 is used to set the context in which a Scheme procedure specified with
439 @code{\applyContext} is executed:
442 \new Staff \relative c' @{
445 \applyContext #(lambda (ctx)
447 (display (ly:context-current-moment ctx)))
454 A context must be named if it is to be referenced later, for example
455 when lyrics are associated with music:
458 \new Voice = "tenor" @var{music}
460 \new Lyrics \lyricsto "tenor" @var{lyrics}
464 For details of associating lyrics with music see
465 @ref{Automatic syllable durations}.
467 The properties of all contexts of a particular type can be modified
468 in a @code{\layout} block (with a different syntax), see
469 @ref{Changing all contexts of the same type}. This construct also
470 provides a means of keeping layout instructions separate from the
471 musical content. If a single context is to be modified, a @code{\with}
472 block must be used, see @ref{Changing just one specific context}.
477 @rlearning{Organizing pieces with variables}.
480 @ref{Changing just one specific context},
481 @ref{Automatic syllable durations}.
484 @node Keeping contexts alive
485 @subsection Keeping contexts alive
487 @cindex contexts, keeping alive
488 @cindex contexts, lifetime
490 Contexts are usually terminated at the first musical moment in
491 which they have nothing to do. So @code{Voice} contexts die as
492 soon as they contain no events; @code{Staff} contexts die as soon
493 as all the @code{Voice} contexts within them contain no events; etc.
494 This can cause difficulties if earlier contexts which have died
495 have to be referenced, for example, when changing staves with
496 @code{\change} commands, associating lyrics with a voice with
497 @code{\lyricsto} commands, or when adding further musical events to
500 There is an exception to this general rule: just one of the
501 @code{Voice} contexts in a @code{Staff} context or in a
502 @code{<<...>>} construct will always persist to the end of the
503 enclosing @code{Staff} context or @code{<<...>>} construct, even
504 though there may be periods when it has nothing to do. The context
505 to persist in this way will be the first one encountered in the
506 first enclosed @code{@{...@}} construct, ignoring any in enclosed
507 @code{<<...>>} constructs.
509 Any context can be kept alive by ensuring it has something to do at
510 every musical moment. @code{Staff} contexts are kept alive by
511 ensuring one of their voices is kept alive. One way of doing this
512 is to add spacer rests to a voice in parallel with the real music.
513 These need to be added to every @code{Voice} context which needs to
514 be kept alive. If several voices are to be used sporadically it is
515 safest to keep them all alive rather than attempting to rely on the
516 exceptions mentioned above.
518 In the following example, both voice A and voice B are kept alive
519 in this way for the duration of the piece:
521 @lilypond[quote,verbatim]
522 musicA = \relative c'' { d4 d d d }
523 musicB = \relative c'' { g4 g g g }
526 \new Voice = "A" { s1*5 } % Keep Voice "A" alive for 5 bars
527 \new Voice = "B" { s1*5 } % Keep Voice "B" alive for 5 bars
532 \context Voice = "A" {
536 \context Voice = "B" {
540 \context Voice = "A" { \musicA }
541 \context Voice = "B" { \musicB }
542 \context Voice = "A" { \musicA }
553 @cindex lyrics, aligning with sporadic melody
555 The following example shows how a sporadic melody line with lyrics
556 might be written using this approach. In a real situation the
557 melody and accompaniment would consist of several different
560 @lilypond[quote,verbatim]
561 melody = \relative c'' { a4 a a a }
562 accompaniment = \relative c' { d4 d d d }
563 words = \lyricmode { These words fol -- low the mel -- o -- dy }
566 \new Staff = "music" {
568 \new Voice = "melody" {
570 s1*4 % Keep Voice "melody" alive for 4 bars
573 \new Voice = "accompaniment" {
578 \context Voice = "melody" { \melody }
579 \context Voice = "accompaniment" { \accompaniment }
581 \context Voice = "accompaniment" { \accompaniment }
583 \context Voice = "melody" { \melody }
584 \context Voice = "accompaniment" { \accompaniment }
589 \new Lyrics \with { alignAboveContext = #"music" }
590 \lyricsto "melody" { \words }
595 An alternative way, which may be better in many circumstances, is
596 to keep the melody line alive by simply including spacer notes to
597 line it up correctly with the accompaniment:
599 @lilypond[quote,verbatim]
600 melody = \relative c'' {
606 accompaniment = \relative c' {
612 words = \lyricmode { These words fol -- low the mel -- o -- dy }
616 \new Staff = "music" {
618 \new Voice = "melody" {
622 \new Voice = "accompaniment" {
628 \new Lyrics \with { alignAboveContext = #"music" }
629 \lyricsto "melody" { \words }
635 @node Modifying context plug-ins
636 @subsection Modifying context plug-ins
638 @c TODO Should this be Modifying engravers or Modifying contexts?
640 Notation contexts (like @code{Score} and @code{Staff}) not only store
641 properties, they also contain plug-ins called @q{engravers} that create
642 notation elements. For example, the @code{Voice} context contains a
643 @code{Note_heads_engraver} and the @code{Staff} context contains a
646 For a full a description of each plug-in, see
648 @rinternals{Engravers and Performers}.
651 Internals Reference @expansion{} Translation @expansion{} Engravers.
653 Every context described in
655 @rinternals{Contexts}
658 Internals Reference @expansion{} Translation @expansion{} Context.
660 lists the engravers used for that context.
663 It can be useful to shuffle around these plug-ins. This is done by
664 starting a new context with @code{\new} or @code{\context}, and
670 \new @var{context} \with @{
683 where the @dots{} should be the name of an engraver. Here is a simple
684 example which removes @code{Time_signature_engraver} and
685 @code{Clef_engraver} from a @code{Staff} context,
687 @lilypond[quote,relative=1,verbatim]
693 \remove "Time_signature_engraver"
694 \remove "Clef_engraver"
701 In the second staff there are no time signature or clef symbols. This
702 is a rather crude method of making objects disappear since it will affect
703 the entire staff. This method also influences the spacing, which may or
704 may not be desirable. More sophisticated methods of blanking objects
705 are shown in @rlearning{Visibility and color of objects}.
707 The next example shows a practical application. Bar lines and time
708 signatures are normally synchronized across the score. This is done
709 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
710 This plug-in keeps an administration of time signature, location
711 within the measure, etc. By moving these engraver from @code{Score} to
712 @code{Staff} context, we can have a score where each staff has its own
715 @cindex polymetric scores
716 @cindex Time signatures, multiple
718 @lilypond[quote,verbatim]
722 \consists "Timing_translator"
723 \consists "Default_bar_line_engraver"
729 \consists "Timing_translator"
730 \consists "Default_bar_line_engraver"
739 \remove "Timing_translator"
740 \remove "Default_bar_line_engraver"
748 The order in which the engravers are specified is the order in
749 which they are called to carry out their processing. Usually the
750 order in which the engravers are specified does not matter, but in
751 a few special cases the order is important, for example where one
752 engraver writes a property and another reads it, or where one
753 engraver creates a grob and another must process it.
755 The following orderings are important:
759 the @code{Bar_engraver} must normally be first,
762 the @code{New_fingering_engraver} must come before the
763 @code{Script_column_engraver},
766 the @code{Timing_translator} must come before the
767 @code{Bar_number_engraver}.
773 @file{ly/engraver-init.ly}.
776 @node Changing context default settings
777 @subsection Changing context default settings
779 @cindex default context properties, changing
780 @cindex context properties, changing defaults
782 Context and grob properties can be changed with @code{\set}
783 and @code{\override} commands, as described in
784 @ref{Modifying properties}. These commands create music events,
785 making the changes take effect at the point in time the music
788 In contrast, this section explains how to change the @emph{default}
789 values of context and grob properties at the time the context is
790 created. There are two ways of doing this. One modifies the default
791 values in all contexts of a particular type, the other modifies the
792 default values in just one particular instance of a context.
795 * Changing all contexts of the same type::
796 * Changing just one specific context::
797 * Order of precedence::
800 @node Changing all contexts of the same type
801 @unnumberedsubsubsec Changing all contexts of the same type
803 @cindex \context in \layout block
807 The context settings which are to be used by default in
808 @code{Score}, @code{Staff}, @code{Voice} and other contexts may be
809 specified in a @code{\context} block within any @code{\layout} block.
810 The @code{\layout} block should be placed within the @code{\score}
811 block to which it is to apply, after the music.
817 [context settings for all Voice contexts]
821 [context settings for all Staff contexts]
826 The following types of settings may be specified:
830 An @code{\override} command, but with the context name omitted
832 @lilypond[quote,verbatim]
835 a4^"Thicker stems" a a a
841 \override Stem.thickness = #4.0
848 Directly setting a context property
850 @lilypond[quote,verbatim]
853 a4^"Smaller font" a a a
866 A predefined command such as @code{\dynamicUp} or a music
867 expression like @code{\accidentalStyle dodecaphonic}
869 @lilypond[quote,verbatim]
872 a4^"Dynamics above" a a a
882 \accidentalStyle dodecaphonic
889 A user-defined variable containing a @code{\with} block; for details
890 of the @code{\with} block see
891 @ref{Changing just one specific context}.
893 @lilypond[quote,verbatim]
894 StaffDefaults = \with {
901 a4^"Smaller font" a a a
916 Property-setting commands can be placed in a @code{\layout} block
917 without being enclosed in a @code{\context} block. Such settings
918 are equivalent to including the same property-setting commands at
919 the start of every context of the type specified. If no context
920 is specified @emph{every} bottom-level context is affected, see
921 @ref{Bottom-level contexts - voices}. The syntax of a
922 property-setting command in a @code{\layout} block is the same as
923 the same command written in the music stream.
925 @lilypond[quote,verbatim]
929 a4^"Smaller font" a a a
934 \accidentalStyle dodecaphonic
936 \override Voice.Stem.thickness = #4.0
942 @node Changing just one specific context
943 @unnumberedsubsubsec Changing just one specific context
948 The context properties of just one specific context instance can be
949 changed in a @code{\with} block. All other context instances of the
950 same type retain the default settings built into LilyPond and modified
951 by any @code{\layout} block within scope. The @code{\with} block
952 must be placed immediately after the @code{\new} @var{context-type}
958 [context settings for this context instance only]
964 The following types of settings may be specified:
968 An @code{\override} command, but with the context name omitted
970 @lilypond[quote,verbatim]
975 \override Stem.thickness = #4.0
979 a4^"Thick stems" a a a
988 Directly setting a context property
990 @lilypond[quote,verbatim]
995 a4^"Default font" a a a
1004 a4^"Smaller font" a a a
1013 A predefined command such as @code{\dynamicUp}
1015 @lilypond[quote,verbatim]
1021 a4^"Dynamics below" a a a
1027 \with { \accidentalStyle dodecaphonic }
1030 \with { \dynamicUp }
1033 a4^"Dynamics above" a a a
1044 @node Order of precedence
1045 @unnumberedsubsubsec Order of precedence
1047 The value of a property which applies at a particular time is
1048 determined as follows:
1052 if an @code{\override} or @code{\set} command in the input stream is
1053 in effect that value is used,
1056 otherwise the default value taken from a @code{\with} statement
1057 on the context initiation statement is used,
1060 otherwise the default value taken from the most recent appropriate
1061 @code{\context} block in the @code{\layout} blocks is used,
1064 otherwise the LilyPond built-in default is used.
1069 @rlearning{Modifying context properties}.
1072 @ref{Contexts explained},
1073 @ref{Bottom-level contexts - voices},
1074 @ref{The set command},
1075 @ref{The override command},
1076 @ref{The \layout block}.
1079 @node Defining new contexts
1080 @subsection Defining new contexts
1082 @cindex contexts, defining new
1083 @cindex engravers, including in contexts
1098 Specific contexts, like @code{Staff} and @code{Voice}, are made from
1099 simple building blocks. It is possible to create new types of
1100 contexts with different combinations of engraver plug-ins.
1102 The next example shows how to build a different type of
1103 @code{Voice} context from scratch. It will be similar to
1104 @code{Voice}, but only prints centered slash note heads. It can be used
1105 to indicate improvisation in jazz pieces,
1107 @lilypond[quote,ragged-right]
1108 \layout { \context {
1110 \type "Engraver_group"
1111 \consists "Note_heads_engraver"
1112 \consists "Rhythmic_column_engraver"
1113 \consists "Text_engraver"
1114 \consists "Pitch_squash_engraver"
1115 squashedPosition = #0
1116 \override NoteHead.style = #'slash
1117 \override Stem.transparent = ##t
1118 \override Flag.transparent = ##t
1122 \accepts "ImproVoice"
1126 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
1127 c4 c^"undress" c_"while playing :)" c }
1133 These settings are defined within a @code{\context} block inside a
1134 @code{\layout} block,
1144 In the following discussion, the example input shown should go in place
1145 of the @dots{} in the previous fragment.
1147 First it is necessary to define a name for the new context:
1153 Since it is similar to the @code{Voice} context, we want commands that
1154 work in (existing) @code{Voice} contexts to continue working. This is
1155 achieved by giving the new context an alias of @code{Voice},
1161 The context will print notes and instructive texts, so we need to add
1162 the engravers which provide this functionality, plus the engraver which
1163 groups notes, stems and rests which occur at the same musical moment
1167 \consists "Note_heads_engraver"
1168 \consists "Text_engraver"
1169 \consists "Rhythmic_column_engraver"
1172 The note heads should all be placed on the center line,
1175 \consists "Pitch_squash_engraver"
1176 squashedPosition = #0
1179 The @code{Pitch_squash_engraver} modifies note heads (created
1180 by the @code{Note_heads_engraver}) and sets their vertical
1181 position to the value of @code{squashedPosition}, in this
1182 case@tie{}@code{0}, the center line.
1184 The notes look like a slash, and have no stem,
1187 \override NoteHead.style = #'slash
1188 \override Stem.transparent = ##t
1189 \override Flag.transparent = ##t
1192 All these plug-ins have to cooperate, and this is achieved with a
1193 special plug-in, which must be marked with the keyword @code{\type}.
1194 This should always be @code{Engraver_group}.
1197 \type "Engraver_group"
1200 Put together, we get
1205 \type "Engraver_group"
1206 \consists "Note_heads_engraver"
1207 \consists "Text_engraver"
1208 \consists "Rhythmic_column_engraver"
1209 \consists "Pitch_squash_engraver"
1210 squashedPosition = #0
1211 \override NoteHead.style = #'slash
1212 \override Stem.transparent = ##t
1213 \override Flag.transparent = ##t
1219 Contexts form hierarchies. We want to place the @code{ImproVoice}
1220 context within the @code{Staff} context, just like normal @code{Voice}
1221 contexts. Therefore, we modify the @code{Staff} definition with the
1222 @code{\accepts} command,
1232 The opposite of @code{\accepts} is @code{\denies},
1233 which is sometimes needed when reusing existing context definitions.
1235 Putting both into a @code{\layout} block, like
1245 \accepts "ImproVoice"
1250 Then the output at the start of this subsection can be entered as
1258 c c_"while playing :)"
1266 Internals Reference:
1267 @rinternals{Engraver_group},
1268 @rinternals{Note_heads_engraver},
1269 @rinternals{Text_engraver},
1270 @rinternals{Rhythmic_column_engraver},
1271 @rinternals{Pitch_squash_engraver}.
1274 @node Context layout order
1275 @subsection Context layout order
1277 @cindex contexts, layout order
1281 Contexts are normally positioned in a system from top to bottom
1282 in the order in which they are encountered in the input file. When
1283 contexts are nested, the outer context will include inner nested
1284 contexts as specified in the input file, provided the inner contexts
1285 are included in the outer context's @qq{accepts} list. Nested
1286 contexts which are not included in the outer context's @qq{accepts}
1287 list will be repositioned below the outer context rather than nested
1290 The @qq{accepts} list of a context can be changed with the
1291 @code{\accepts} and @code{\denies} commands. @code{\accepts} adds a
1292 context to the @qq{accepts} list and @code{\denies} removes a context
1293 from the list. For example, it would not normally be desirable for
1294 chord names to be nested within a @code{Staff} context, so the
1295 @code{ChordNames} context is not included by default in the @qq{accepts}
1296 list of the @code{Staff} context, but if this were to be required it can
1299 @lilypond[verbatim,quote]
1303 \chords { d1:m7 b1:min7.5- }
1308 @lilypond[verbatim,quote]
1312 \chords { d1:m7 b1:min7.5- }
1317 \accepts "ChordNames"
1323 @code{\denies} is mainly used when a new context is being based on
1324 another, but the required nesting differs. For example, the
1325 @code{VaticanaStaff} context is based on the @code{Staff} context, but
1326 with the @code{VaticanaVoice} context substituted for the @code{Voice}
1327 context in the @qq{accepts} list.
1329 @cindex contexts, implicit
1330 @cindex implicit contexts
1331 @funindex \defaultchild
1333 Note that a context will be silently created implicitly if a
1334 command is encountered when there is no suitable context available
1337 Within a context definition, the type of subcontext to be
1338 implicitly created is specified using @code{\defaultchild}. A
1339 number of music events require a @samp{Bottom} context: when such
1340 an event is encountered, subcontexts are created recursively until
1341 reaching a context with no @samp{defaultchild} setting.
1343 Implicit context creation can at times give rise to unexpected new
1344 staves or scores. Using @code{\new} to create contexts explicitly
1345 avoids those problems.
1347 @cindex alignAboveContext
1348 @cindex alignBelowContext
1349 @funindex alignAboveContext
1350 @funindex alignBelowContext
1352 Sometimes a context is required to exist for just a brief period, a
1353 good example being the staff context for an ossia. This is usually
1354 achieved by introducing the context definition at the appropriate
1355 place in parallel with corresponding section of the main music.
1356 By default, the temporary context will be placed below all the
1357 existing contexts. To reposition it above the context called
1358 @qq{main}, it should be defined like this:
1361 @code{\new Staff \with @{ alignAboveContext = #"main" @} }
1364 A similar situation arises when positioning a temporary lyrics
1365 context within a multi-staved layout such as a @code{ChoirStaff},
1366 for example, when adding a second verse to a repeated section.
1367 By default the temporary lyrics context will be placed beneath the
1368 lower staves. By defining the temporary lyrics context with
1369 @code{alignBelowContext} it can be positioned correctly beneath
1370 the (named) lyrics context containing the first verse.
1372 Examples showing this repositioning of temporary contexts can be
1373 found elsewhere --- see @rlearning{Nesting music expressions},
1374 @ref{Modifying single staves} and @ref{Techniques specific to lyrics}.
1378 @rlearning{Nesting music expressions}.
1381 @ref{Modifying single staves},
1382 @ref{Techniques specific to lyrics}.
1385 @rprogram{An extra staff appears}.
1388 @file{ly/engraver-init.ly}.
1391 @node Explaining the Internals Reference
1392 @section Explaining the Internals Reference
1395 * Navigating the program reference::
1396 * Layout interfaces::
1397 * Determining the grob property::
1398 * Naming conventions::
1401 @node Navigating the program reference
1402 @subsection Navigating the program reference
1404 @c TODO remove this (it's in the LM)
1405 @c Replace with more factual directions
1407 Suppose we want to move the fingering indication in the fragment
1410 @lilypond[quote,relative=2,verbatim]
1416 If you visit the documentation on fingering instructions (in
1417 @ref{Fingering instructions}), you will notice:
1422 Internals Reference: @rinternals{Fingering}.
1427 @c outdated info; probably will delete.
1429 This fragment points to two parts of the program reference: a page
1430 on @code{FingeringEvent} and one on @code{Fingering}.
1432 The page on @code{FingeringEvent} describes the properties of the music
1433 expression for the input @w{@code{-2}}. The page contains many links
1434 forward. For example, it says
1437 Accepted by: @rinternals{Fingering_engraver},
1441 That link brings us to the documentation for the Engraver, the
1445 This engraver creates the following layout objects: @rinternals{Fingering}.
1448 In other words, once the @code{FingeringEvent}s are interpreted, the
1449 @code{Fingering_engraver} plug-in will process them.
1453 @c I can't figure out what this is supposed to mean. -gp
1455 The @code{Fingering_engraver} is also listed to create
1456 @rinternals{Fingering} objects,
1458 @c old info? it doesn't make any sense to me with our current docs.
1460 second bit of information listed under @b{See also} in the Notation
1465 The programmer's reference is available as an HTML document. It is
1466 highly recommended that you read it in HTML form, either online or
1467 by downloading the HTML documentation. This section will be much more
1468 difficult to understand if you are using the
1472 Follow the link to @rinternals{Fingering}. At the top of the
1476 Fingering objects are created by: @rinternals{Fingering_engraver} and
1477 @rinternals{New_fingering_engraver}.
1480 By following related links inside the program reference, we can follow the
1481 flow of information within the program:
1485 @item @rinternals{Fingering}:
1486 @rinternals{Fingering} objects are created by:
1487 @rinternals{Fingering_engraver}
1489 @item @rinternals{Fingering_engraver}:
1490 Music types accepted: @rinternals{fingering-event}
1492 @item @rinternals{fingering-event}:
1493 Music event type @code{fingering-event} is in Music expressions named
1494 @rinternals{FingeringEvent}
1497 This path goes against the flow of information in the program: it
1498 starts from the output, and ends at the input event. You could
1499 also start at an input event, and read with the flow of
1500 information, eventually ending up at the output object(s).
1502 The program reference can also be browsed like a normal document. It
1503 contains chapters on
1505 @rinternals{Music definitions},
1508 @code{Music definitions}
1510 on @rinternals{Translation}, and the @rinternals{Backend}. Every
1511 chapter lists all the definitions used and all properties that may be
1515 @node Layout interfaces
1516 @subsection Layout interfaces
1518 @cindex interface, layout
1519 @cindex layout interface
1522 The HTML page that we found in the previous section describes the
1523 layout object called @rinternals{Fingering}. Such an object is a
1524 symbol within the score. It has properties that store numbers (like
1525 thicknesses and directions), but also pointers to related objects. A
1526 layout object is also called a @emph{Grob}, which is short for Graphical
1527 Object. For more details about Grobs, see @rinternals{grob-interface}.
1529 The page for @code{Fingering} lists the definitions for the
1530 @code{Fingering} object. For example, the page says
1533 @code{padding} (dimension, in staff space):
1539 which means that the number will be kept at a distance of at least 0.5
1543 Each layout object may have several functions as a notational or
1544 typographical element. For example, the Fingering object
1545 has the following aspects
1549 Its size is independent of the horizontal spacing, unlike slurs or beams.
1552 It is a piece of text. Granted, it is usually a very short text.
1555 That piece of text is typeset with a font, unlike slurs or beams.
1558 Horizontally, the center of the symbol should be aligned to the
1559 center of the note head.
1562 Vertically, the symbol is placed next to the note and the staff.
1565 The vertical position is also coordinated with other superscript
1566 and subscript symbols.
1569 Each of these aspects is captured in so-called @emph{interface}s,
1570 which are listed on the @rinternals{Fingering} page at the bottom
1573 This object supports the following interfaces:
1574 @rinternals{item-interface},
1575 @rinternals{self-alignment-interface},
1576 @rinternals{side-position-interface}, @rinternals{text-interface},
1577 @rinternals{text-script-interface}, @rinternals{font-interface},
1578 @rinternals{finger-interface}, and @rinternals{grob-interface}.
1581 Clicking any of the links will take you to the page of the respective
1582 object interface. Each interface has a number of properties. Some of
1583 them are not user-serviceable (@q{Internal properties}), but others
1586 We have been talking of @emph{the} @code{Fingering} object, but actually it
1587 does not amount to much. The initialization file (see
1588 @rlearning{Other sources of information})
1589 @file{scm/define-grobs.scm} shows the soul of the @q{object},
1594 (avoid-slur . around)
1595 (slur-padding . 0.2)
1596 (staff-padding . 0.5)
1597 (self-alignment-X . 0)
1598 (self-alignment-Y . 0)
1599 (script-priority . 100)
1600 (stencil . ,ly:text-interface::print)
1601 (direction . ,ly:script-interface::calc-direction)
1602 (font-encoding . fetaText)
1603 (font-size . -5) ; don't overlap when next to heads.
1604 (meta . ((class . Item)
1605 (interfaces . (finger-interface
1607 text-script-interface
1609 side-position-interface
1610 self-alignment-interface
1611 item-interface))))))
1615 As you can see, the @code{Fingering} object is nothing more than a
1616 bunch of variable settings, and the webpage in the Internals Reference
1617 is directly generated from this definition.
1620 @node Determining the grob property
1621 @subsection Determining the grob property
1623 @c TODO remove this (it's in the LM)
1624 @c Replace with more factual directions
1626 Recall that we wanted to change the position of the @b{2} in
1628 @lilypond[quote,relative=2,verbatim]
1634 Since the @b{2} is vertically positioned next to its note, we have to
1635 meddle with the interface associated with this positioning. This is
1636 done using @code{side-position-interface}. The page for this interface
1640 @code{side-position-interface}
1642 Position a victim object (this one) next to other objects (the
1643 support). The property @code{direction} signifies where to put the
1644 victim object relative to the support (left or right, up or down?)
1649 Below this description, the variable @code{padding} is described as
1654 (dimension, in staff space)
1656 Add this much extra space between objects that are next to each other.
1660 By increasing the value of @code{padding}, we can move the
1661 fingering away from the note head. The following command inserts
1662 3 staff spaces of white
1663 between the note and the fingering:
1665 \once \override Voice.Fingering.padding = #3
1668 Inserting this command before the Fingering object is created,
1669 i.e., before @code{c2}, yields the following result:
1671 @lilypond[quote,relative=2,verbatim]
1672 \once \override Voice.Fingering.padding = #3
1679 In this case, the context for this tweak is @code{Voice}. This
1680 fact can also be deduced from the program reference, for the page for
1681 the @rinternals{Fingering_engraver} plug-in says
1684 Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
1688 @node Naming conventions
1689 @subsection Naming conventions
1691 Another thing that is needed, is an overview of the various naming
1695 @item scheme functions: lowercase-with-hyphens (incl. one-word
1697 @item scheme functions: ly:plus-scheme-style
1698 @item music events, music classes and music properties:
1700 @item Grob interfaces: scheme-style
1701 @item backend properties: scheme-style (but X and Y!)
1702 @item contexts (and MusicExpressions and grobs): Capitalized or
1704 @item context properties: lowercaseFollowedByCamelCase
1706 Capitalized_followed_by_lowercase_and_with_underscores
1709 Questions to be answered:
1711 @item Which of these are conventions and which are rules?
1712 @item Which are rules of the underlying language, and which are
1716 @node Modifying properties
1717 @section Modifying properties
1719 @c TODO change the menu and subsection node names to use
1720 @c backslash once the new macro to handle the refs
1721 @c is available. Need to find and change all refs at
1722 @c the same time. -td
1725 * Overview of modifying properties::
1727 * The override command::
1728 * The tweak command::
1729 * set versus override::
1730 * Modifying alists::
1734 @node Overview of modifying properties
1735 @subsection Overview of modifying properties
1737 Each context is responsible for creating certain types of graphical
1738 objects. The settings used for printing these objects are also stored by
1739 context. By changing these settings, the appearance of objects can be
1742 There are two different kinds of properties stored in contexts:
1743 context properties and grob properties. Context properties are
1744 properties that apply to the context as a whole and control
1745 how the context itself is displayed. In contrast, grob properties
1746 apply to specific grob types that will be displayed in the context.
1748 The @code{\set} and @code{\unset} commands are used to change values
1749 for context properties. The @code{\override} and @code{\revert}
1750 commands are used to change values for grob properties.
1753 The syntax for this is
1756 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1759 Here @var{name} is the name of a graphical object, like
1760 @code{Stem} or @code{NoteHead}, and @var{property} is an internal
1761 variable of the formatting system (@q{grob property} or @q{layout
1762 property}). The latter is a symbol, so it must be quoted. The
1763 subsection @ref{Modifying properties}, explains what to fill in
1764 for @var{name}, @var{property}, and @var{value}. Here we only
1765 discuss the functionality of this command.
1770 \override Staff.Stem.thickness = #4.0
1774 makes stems thicker (the default is 1.3, with staff line thickness as a
1775 unit). Since the command specifies @code{Staff} as context, it only
1776 applies to the current staff. Other staves will keep their normal
1777 appearance. Here we see the command in action:
1779 @lilypond[quote,verbatim,relative=2]
1781 \override Staff.Stem.thickness = #4.0
1787 The @code{\override} command changes the definition of the @code{Stem}
1788 within the current @code{Staff}. After the command is interpreted
1789 all stems are thickened.
1791 Analogous to @code{\set}, the @var{context} argument may be left out,
1792 causing the default context @code{Voice} to be used. Adding
1793 @code{\once} applies the change during one timestep only.
1795 @lilypond[quote,verbatim,relative=2]
1797 \once \override Stem.thickness = #4.0
1802 The @code{\override} must be done before the object is
1803 started. Therefore, when altering @emph{Spanner} objects such as slurs
1804 or beams, the @code{\override} command must be executed at the moment
1805 when the object is created. In this example,
1807 @lilypond[quote,verbatim,relative=2]
1808 \override Slur.thickness = #3.0
1810 \override Beam.beam-thickness = #0.6
1815 the slur is fatter but the beam is not. This is because the command for
1816 @code{Beam} comes after the Beam is started, so it has no effect.
1818 Analogous to @code{\unset}, the @code{\revert} command for a context
1819 undoes an @code{\override} command; like with @code{\unset}, it only
1820 affects settings that were made in the same context. In other words, the
1821 @code{\revert} in the next example does not do anything.
1824 \override Voice.Stem.thickness = #4.0
1825 \revert Staff.Stem.thickness
1828 Some tweakable options are called @q{subproperties} and reside inside
1829 properties. To tweak those, use commands of the form
1831 @c leave this as a long long
1833 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1840 \override Stem.details.beamed-lengths = #'(4 4 3)
1846 Internals Reference:
1847 @rinternals{Backend},
1848 @rinternals{All layout objects},
1849 @rinternals{OverrideProperty},
1850 @rinternals{RevertProperty},
1851 @rinternals{PropertySet}.
1854 The back-end is not very strict in type-checking object properties.
1855 Cyclic references in Scheme values for properties can cause hangs
1856 or crashes, or both.
1859 @node The set command
1860 @subsection The @code{@bs{}set} command
1864 @cindex changing properties
1866 Each context has a set of @emph{properties}, variables contained
1867 in that context. Context properties are changed with the @code{\set}
1868 command, which has the following syntax:
1871 \set @var{context}.@var{property} = #@var{value}
1874 @var{value} is a Scheme object, which is why it must be preceded by
1875 the @code{#}@tie{}character.
1877 Contexts properties are usually named in
1878 @code{studlyCaps}. They mostly control the translation from
1879 music to notation, e.g. @code{localKeySignature} (for determining
1880 whether to print accidentals), or @code{measurePosition} (for
1881 determining when to print a bar line). Context properties can
1882 change value over time while interpreting a piece of music;
1883 @code{measurePosition} is an obvious example of
1884 this. Context properties are modified with @code{\set}.
1886 For example, multimeasure rests will be combined into a single bar
1887 if the context property @code{skipBars} is set to @code{#t}:
1889 @lilypond[quote,verbatim,relative=2]
1891 \set Score.skipBars = ##t
1895 If the @var{context} argument is left out, then the property will be
1896 set in the current bottom context (typically @code{ChordNames},
1897 @code{Voice}, @code{TabVoice}, or @code{Lyrics}).
1899 @lilypond[quote,verbatim,relative=2]
1900 \set Score.autoBeaming = ##f
1904 \set autoBeaming = ##t
1912 The change is applied @q{on-the-fly}, during the music, so that the
1913 setting only affects the second group of eighth notes.
1915 Note that the bottom-most context does not always contain the property
1916 that you wish to change -- for example, attempting to set the
1917 @code{skipBars} property of the default bottom context, in this case
1918 @code{Voice}, will have no effect, because skipBars is a property of
1919 the @code{Score} context.
1921 @lilypond[quote,verbatim,relative=2]
1927 Contexts are hierarchical, so if an enclosing context was specified, for
1928 example @code{Staff}, then the change would also apply to all
1929 @code{Voice}s in the current staff.
1933 The @code{\unset} command:
1936 \unset @var{context}.@var{property}
1940 is used to remove the definition of @var{property} from
1941 @var{context}. This command removes
1942 the definition only if it is set in @var{context}.
1943 Properties that have been set in enclosing contexts will
1944 not be altered by an unset in an enclosed context:
1946 @lilypond[quote,verbatim,relative=2]
1947 \set Score.autoBeaming = ##t
1952 \unset Score.autoBeaming
1960 Like @code{\set}, the @var{context} argument does not have to be
1961 specified for a bottom context, so the two statements
1964 \set Voice.autoBeaming = ##t
1965 \set autoBeaming = ##t
1969 are equivalent if the current bottom context is @code{Voice}.
1973 Preceding a @code{\set} command by @code{\once} makes the
1974 setting apply to only a single time-step:
1976 @lilypond[quote,verbatim,relative=2]
1978 \once \set fontSize = #4.7
1983 A full description of all available context properties is in the
1984 internals reference, see
1986 @rinternals{Tunable context properties}.
1989 Translation @expansion{} Tunable context properties.
1993 Internals Reference:
1994 @rinternals{Tunable context properties}.
1997 @node The override command
1998 @subsection The @code{\override} command
2000 @cindex grob properties
2001 @cindex properties, grob
2004 There is a special type of context property: the grob
2005 description. Grob descriptions are named in @code{StudlyCaps}
2006 (starting with capital letters). They contain the
2007 @q{default settings} for a particular kind of grob as an
2008 association list. See @file{scm/define-grobs.scm}
2009 to see the settings for each grob description. Grob descriptions
2010 are modified with @code{\override}.
2012 The syntax for the @code{\override} command is
2015 \override [@var{context}.]@var{GrobName}.@var{property} = #@var{value}
2018 For example, we can increase the thickness of a note stem by
2019 overriding the @code{thickness} property of the @code{Stem}
2022 @lilypond[quote,verbatim,relative=2]
2024 \override Voice.Stem.thickness = #3.0
2028 If no context is specified in an @code{\override}, the bottom
2031 @lilypond[quote,verbatim,relative=2]
2032 { \override Staff.Stem.thickness = #3.0
2036 \override Stem.thickness = #0.5
2045 Some tweakable options are called @q{subproperties} and reside inside
2046 properties. To tweak those, use commands in the form
2049 \override Stem.details.beamed-lengths = #'(4 4 3)
2052 or to modify the ends of spanners, use a form like these
2055 \override TextSpanner.bound-details.left.text = #"left text"
2056 \override TextSpanner.bound-details.right.text = #"right text"
2060 @cindex reverting overrides
2061 @cindex overrides, reverting
2063 The effects of @code{\override} can be undone by @code{\revert}.
2065 The syntax for the @code{\revert} command is
2068 \revert [@var{context}.]@var{GrobName}.@var{property}
2073 @lilypond[quote,verbatim,relative=2]
2075 \override Voice.Stem.thickness = #3.0
2077 \revert Voice.Stem.thickness
2081 The effects of @code{\override} and @code{\revert} apply to all
2082 grobs in the affected context from the current time forward:
2084 @lilypond[quote,verbatim,relative=2]
2089 \override Staff.Stem.thickness = #3.0
2093 \revert Staff.Stem.thickness
2101 @cindex overriding for only one moment
2103 @code{\once} can be used with @code{\override}
2104 to affect only the current time step:
2106 @lilypond[quote,verbatim,relative=2]
2110 \override Stem.thickness = #3.0
2114 \once \override Stem.thickness = #3.0
2123 Commands which change output generally look like
2126 \override Voice.Stem.thickness = #3.0
2130 To construct this tweak we must determine these bits of information:
2133 @item the context: here @code{Voice}.
2134 @item the layout object: here @code{Stem}.
2135 @item the layout property: here @code{thickness}.
2136 @item a sensible value: here @code{3.0}.
2139 @cindex internal documentation
2140 @cindex finding graphical objects
2141 @cindex graphical object descriptions
2144 @cindex internal documentation
2146 For many properties, regardless of the data type of the property, setting the
2147 property to false (@code{#f}) will result in turning it off, causing
2148 LilyPond to ignore that property entirely. This is particularly useful for
2149 turning off grob properties which may otherwise be causing problems.
2151 We demonstrate how to glean this information from the notation manual
2152 and the program reference.
2156 Internals Reference:
2157 @rinternals{Backend}
2160 @node The tweak command
2161 @subsection The @code{\tweak} command
2166 Changing grob properties
2167 with @code{\override} causes the changes to apply to all of the
2168 given grobs in the context at the moment the change applies.
2169 Sometimes, however, it is desirable to have changes apply to just
2170 one grob, rather than to all grobs in the affected context. This is
2171 accomplished with the @code{\tweak} command, which has the following
2175 \tweak [@var{layout-object}.]@var{grob-property} @var{value}
2178 Specifying @var{layout-object} is optional.
2179 The @code{\tweak} command applies to the music object that immediately
2180 follows @var{value} in the music stream.
2183 In some cases, it is possible to take a short-cut for tuning
2184 graphical objects. For objects that are created directly from
2185 an item in the input file, you can use the @code{\tweak} command.
2188 @lilypond[relative=2,verbatim,quote]
2193 \tweak duration-log #1
2202 The main use of the @code{\tweak} command is to modify just
2203 one of a number of notation elements which start at the same musical
2204 moment, like the notes of a chord, or tuplet brackets which start
2207 The @code{\tweak} command sets a property in the following object
2208 directly, without requiring the grob name or context to be
2209 specified. For this to work, it is necessary for the @code{\tweak}
2210 command to remain immediately adjacent to the object to which it is
2211 to apply after the input file has been converted to a music stream.
2212 This is often not the case, as many additional elements are inserted
2213 into the music stream implicitly. For example, when a note which is
2214 not part of a chord is processed, LilyPond implicitly inserts a
2215 @code{ChordEvent} event before the note, so separating the tweak
2216 from the note. However, if chord symbols are placed round the
2217 tweak and the note, the @code{\tweak} command comes after the
2218 @code{ChordEvent} in the music stream, so remaining adjacent to the
2219 note, and able to modify it.
2223 @lilypond[relative=2,verbatim,quote]
2224 <\tweak color #red c>4
2230 @lilypond[relative=2,verbatim,quote]
2231 \tweak color #red c4
2236 For an introduction to the syntax and uses of the tweak command
2237 see @rlearning{Tweaking methods}.
2239 When several similar items are placed at the same musical moment,
2240 the @code{\override} command cannot be used to modify just one of
2241 them -- this is where the @code{\tweak} command must be used.
2242 Items which may appear more than once at the same musical moment
2243 include the following:
2245 @c TODO expand to include any further uses of \tweak
2247 @item note heads of notes inside a chord
2248 @item articulation signs on a single note
2249 @item ties between notes in a chord
2250 @item tuplet brackets starting at the same time
2253 @c TODO add examples of these
2255 @cindex chord, modifying one note in
2257 In this example, the color of one note head and the type of another
2258 note head are modified within a single chord:
2260 @lilypond[relative=2,verbatim,quote]
2265 \tweak duration-log #1
2270 @code{\tweak} can be used to modify slurs:
2272 @lilypond[verbatim,quote,relative=1]
2273 c-\tweak thickness #5 ( d e f)
2277 For the @code{\tweak} command to work, it must
2278 remain immediately adjacent to the object to which it is
2279 to apply after the input file has been converted to a music stream.
2280 Tweaking a whole chord does not do anything since its music event
2281 only acts as a container, and all layout objects are created from events
2282 inside of the @code{EventChord}:
2284 @lilypond[relative=2,verbatim,quote]
2285 \tweak color #red c4
2286 \tweak color #red <c e>4
2287 <\tweak color #red c e>4
2290 The simple @code{\tweak} command cannot be used to modify any object
2291 that is not directly created from the input. In particular
2292 it will not affect stems, automatic
2293 beams or accidentals, since these are generated later by
2294 @code{NoteHead} layout objects rather than by music elements in the
2297 Such indirectly created layout objects can be tweaked using the form
2298 of the @code{\tweak} command in which the grob name is specified
2301 @lilypond[relative=2,verbatim,quote]
2302 \tweak Stem.color #red
2303 \tweak Beam.color #green c8 e
2304 <c e \tweak Accidental.font-size #-3 ges>4
2307 @code{\tweak} cannot be used to modify clefs or time
2308 signatures, since these become separated from any preceding
2309 @code{\tweak} command in the input stream by the automatic
2310 insertion of extra elements required to specify the context.
2312 Several @code{\tweak} commands may be placed before a
2313 notational element -- all affect it:
2315 @lilypond[verbatim,quote,relative=1]
2317 -\tweak style #'dashed-line
2318 -\tweak dash-fraction #0.2
2319 -\tweak thickness #3
2325 The music stream which is generated from a section of an input file,
2326 including any automatically inserted elements, may be examined,
2327 see @rextend{Displaying music expressions}. This may be helpful in
2328 determining what may be modified by a @code{\tweak} command, or
2329 in determining how to adjust the input to make a @code{\tweak}
2334 @rlearning{Tweaking methods}.
2337 @rextend{Displaying music expressions}.
2341 @cindex tweaking control points
2342 @cindex control points, tweaking
2344 The @code{\tweak} command cannot be used to modify the control
2345 points of just one of several ties in a chord, other than the first
2346 one encountered in the input file.
2348 @node set versus override
2349 @subsection @code{\set} vs. @code{\override}
2351 @c TODO -- This section is probably unnecessary now.
2354 We have seen two methods of changing properties: @code{\set} and
2355 @code{\override}. There are actually two different kinds of
2358 @code{fontSize} is a special property: it is equivalent to
2359 entering @code{\override ... #'font-size} for all pertinent
2360 objects. Since this is a common change, the special
2361 property (modified with @code{\set}) was created.
2366 @node Modifying alists
2367 @subsection Modifying alists
2369 Some user-configurable properties are internally represented as
2370 @emph{alists} (association lists), which store pairs of
2371 @emph{keys} and @emph{values}. The structure of an alist is:
2374 '((@var{key1} . @var{value1})
2375 (@var{key2} . @var{value2})
2376 (@var{key3} . @var{value3})
2380 If an alist is a grob property or @code{\paper} variable, its keys
2381 can be modified individually without affecting other keys.
2383 For example, to reduce the space between adjacent staves in a
2384 staff-group, use the @code{staff-staff-spacing} property of the
2385 @code{StaffGrouper} grob. The property is an alist with four
2386 keys: @code{basic-distance}, @code{minimum-distance},
2387 @code{padding}, and @code{stretchability}. The standard settings
2388 for this property are listed in the @qq{Backend} section of the
2389 Internals Reference (see @rinternals{StaffGrouper}):
2392 '((basic-distance . 9)
2393 (minimum-distance . 7)
2395 (stretchability . 5))
2398 One way to bring the staves closer together is by reducing the
2399 value of the @code{basic-distance} key (@code{9}) to match the
2400 value of @code{minimum-distance} (@code{7}). To modify a single
2401 key individually, use a @emph{nested declaration}:
2403 @lilypond[quote,verbatim]
2404 % default space between staves
2406 \new Staff { \clef treble c''1 }
2407 \new Staff { \clef bass c1 }
2410 % reduced space between staves
2411 \new PianoStaff \with {
2412 % this is the nested declaration
2413 \override StaffGrouper.staff-staff-spacing.basic-distance = #7
2415 \new Staff { \clef treble c''1 }
2416 \new Staff { \clef bass c1 }
2420 Using a nested declaration will update the specified key (such as
2421 @code{basic-distance} in the above example) without altering any
2422 other keys already set for the same property.
2424 Now suppose we want the staves to be as close as possible without
2425 overlapping. The simplest way to do this is to set all four alist
2426 keys to zero. However, it is not necessary to enter four nested
2427 declarations, one for each key. Instead, the property can be
2428 completely re-defined with one declaration, as an alist:
2430 @lilypond[quote,verbatim]
2431 \new PianoStaff \with {
2432 \override StaffGrouper.staff-staff-spacing =
2433 #'((basic-distance . 0)
2434 (minimum-distance . 0)
2436 (stretchability . 0))
2438 \new Staff { \clef treble c''1 }
2439 \new Staff { \clef bass c1 }
2443 Note that any keys not explicitly listed in the alist definition
2444 will be reset to their @emph{default-when-unset} values. In the
2445 case of @code{staff-staff-spacing}, any unset key-values would be
2446 reset to zero (except @code{stretchability}, which takes the value
2447 of @code{basic-distance} when unset). Thus the following two
2448 declarations are equivalent:
2451 \override StaffGrouper.staff-staff-spacing =
2452 #'((basic-distance . 7))
2454 \override StaffGrouper.staff-staff-spacing =
2455 #'((basic-distance . 7)
2456 (minimum-distance . 0)
2458 (stretchability . 7))
2461 One (possibly unintended) consequence of this is the removal of
2462 any standard settings that are set in an initialization file and
2463 loaded each time an input file is compiled. In the above example,
2464 the standard settings for @code{padding} and
2465 @code{minimum-distance} (defined in @file{scm/define-grobs.scm})
2466 are reset to their default-when-unset values (zero for both keys).
2467 Defining a property or variable as an alist (of any size) will
2468 always reset all unset key-values to their default-when-unset
2469 values. Unless this is the intended result, it is safer to update
2470 key-values individually with a nested declaration.
2472 @warning{Nested declarations will not work for context property
2473 alists (such as @code{beamExceptions}, @code{keySignature},
2474 @code{timeSignatureSettings}, etc.). These properties can only be
2475 modified by completely re-defining them as alists.}
2478 @node Useful concepts and properties
2479 @section Useful concepts and properties
2484 * Direction and placement::
2485 * Distances and measurements::
2486 * Staff symbol properties::
2488 * Visibility of objects::
2490 * Rotating objects::
2494 @subsection Input modes
2496 The way in which the notation contained within an input file is
2497 interpreted is determined by the current input mode.
2501 This is activated with the @code{\chordmode} command, and causes
2502 input to be interpreted with the syntax of chord notation, see
2503 @ref{Chord notation}. Chords are rendered as notes on a staff.
2505 Chord mode is also activated with the @code{\chords} command.
2506 This also creates a new @code{ChordNames} context and
2507 causes the following input to be interpreted with the syntax of
2508 chord notation and rendered as chord names in the @code{ChordNames}
2509 context, see @ref{Printing chord names}.
2513 This is activated with the @code{\drummode} command, and causes
2514 input to be interpreted with the syntax of drum notation, see
2515 @ref{Basic percussion notation}.
2517 Drum mode is also activated with the @code{\drums} command.
2518 This also creates a new @code{DrumStaff} context and causes the
2519 following input to be interpreted with the syntax of drum notation
2520 and rendered as drum symbols on a drum staff, see @ref{Basic
2521 percussion notation}.
2523 @strong{Figure mode}
2525 This is activated with the @code{\figuremode} command, and causes
2526 input to be interpreted with the syntax of figured bass, see
2527 @ref{Entering figured bass}.
2529 Figure mode is also activated with the @code{\figures} command.
2530 This also creates a new @code{FiguredBass} context and causes the
2531 following input to be interpreted with the figured bass syntax
2532 and rendered as figured bass symbols in the @code{FiguredBass}
2533 context, see @ref{Introduction to figured bass}.
2535 @strong{Fret and tab modes}
2537 There are no special input modes for entering fret and tab symbols.
2539 To create tab diagrams, enter notes or chords in note mode and
2540 render them in a @code{TabStaff} context, see
2541 @ref{Default tablatures}.
2543 To create fret diagrams above a staff, you have two choices.
2544 You can either use the @code{FretBoards} context (see
2545 @ref{Automatic fret diagrams} or you can enter them as a markup
2546 above the notes using the @code{\fret-diagram} command (see
2547 @ref{Fret diagram markups}).
2549 @strong{Lyrics mode}
2551 This is activated with the @code{\lyricmode} command, and causes
2552 input to be interpreted as lyric syllables with optional durations
2553 and associated lyric modifiers, see @ref{Vocal music}.
2555 Lyric mode is also activated with the @code{\addlyrics} command.
2556 This also creates a new @code{Lyrics} context and an implicit
2557 @code{\lyricsto} command which associates the following lyrics
2558 with the preceding music.
2560 @strong{Markup mode}
2562 This is activated with the @code{\markup} command, and causes
2563 input to be interpreted with the syntax of markup, see
2564 @ref{Text markup commands}.
2566 @c silly work-around for texinfo broken-ness
2567 @c (@strong{Note...} causes a spurious cross-reference in Info)
2570 This is the default mode or it may be activated with the
2571 @code{\notemode} command. Input is interpreted as pitches,
2572 durations, markup, etc and typeset as musical notation on a staff.
2574 It is not normally necessary to specify note mode explicitly, but
2575 it may be useful to do so in certain situations, for example if you
2576 are in lyric mode, chord mode or any other mode and want to insert
2577 something that only can be done with note mode syntax.
2579 For example, to indicate dynamic markings for the verses of a
2580 choral pieces it is necessary to enter note mode to interpret
2583 @lilypond[verbatim,relative=2,quote]
2586 \notemode{\set stanza = \markup{ \dynamic f 1. } }
2590 \notemode{\set stanza = \markup{ \dynamic p 2. } }
2597 @node Direction and placement
2598 @subsection Direction and placement
2600 In typesetting music the direction and placement of many items is
2601 a matter of choice. For example, the stems of notes can
2602 be directed up or down; lyrics, dynamics, and other expressive
2603 marks may be placed above or below the staff; text may be aligned
2604 left, right or center; etc. Most of these choices may be left to
2605 be determined automatically by LilyPond, but in some cases it may
2606 be desirable to force a particular direction or placement.
2609 * Articulation direction indicators::
2610 * The direction property::
2613 @node Articulation direction indicators
2614 @unnumberedsubsubsec Articulation direction indicators
2616 By default some directions are always up or always down (e.g.
2617 dynamics or fermata), while other things can alternate between
2618 up or down based on the stem direction (like slurs or accents).
2620 @c TODO Add table showing these
2622 The default action may be overridden by prefixing the articulation
2623 by a @emph{direction indicator}. Three direction indicators are
2624 available: @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down})
2625 and @code{-} (meaning @qq{use default direction}). The direction
2626 indicator can usually be omitted, in which case @code{-} is assumed,
2627 but a direction indicator is @strong{always} required before
2630 @item @code{\tweak} commands
2631 @item @code{\markup} commands
2632 @item @code{\tag} commands
2633 @item string markups, e.g. -"string"
2634 @item fingering instructions, e.g. @w{@code{-1}}
2635 @item articulation shortcuts, e.g. @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
2638 Direction indicators affect only the next note:
2640 @lilypond[verbatim,quote,relative=2]
2647 @node The direction property
2648 @unnumberedsubsubsec The direction property
2650 The position or direction of many layout objects is controlled by the
2651 @code{direction} property.
2653 The value of the @code{direction} property may be set to @code{1},
2654 meaning @qq{up} or @qq{above}, or to @w{@code{-1}}, meaning @qq{down} or
2655 @qq{below}. The symbols @code{UP} and @code{DOWN} may be used instead
2656 of @code{1} and @w{@code{-1}} respectively. The default direction may
2657 be specified by setting @code{direction} to @code{0} or @code{CENTER}.
2658 Alternatively, in many cases predefined commands exist to specify the
2659 direction. These are of the form
2662 @code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
2666 where @code{\xxxNeutral} means @qq{use the default} direction.
2667 See @rlearning{Within-staff objects}.
2669 In a few cases, arpeggio for example, the value of the @code{direction}
2670 property can specify whether the object is to be placed to the right or
2671 left of the parent. In this case @w{@code{-1}} or @code{LEFT} means
2672 @qq{to the left} and @code{1} or @code{RIGHT} means @qq{to the right}.
2673 @code{0} or @code{CENTER} means @qq{use the default} direction.
2676 These all have side-axis set to #X
2677 AmbitusAccidental - direction has no effect
2679 StanzaNumber - not tried
2680 TrillPitchAccidental - not tried
2681 TrillPitchGroup - not tried
2684 These indications affect all notes until they are canceled.
2686 @lilypond[verbatim,quote,relative=2]
2695 In polyphonic music, it is generally better to specify an explicit
2696 @code{voice} than change an object's direction. For more information.
2697 See @ref{Multiple voices}.
2701 @rlearning{Within-staff objects}.
2704 @ref{Multiple voices}.
2707 @node Distances and measurements
2708 @subsection Distances and measurements
2710 @cindex distances, absolute
2711 @cindex distances, scaled
2718 Distances in LilyPond are of two types: absolute and scaled.
2720 Absolute distances are used for specifying margins, indents, and
2721 other page layout details, and are by default specified in
2722 millimeters. Distances may be specified in other units by
2723 following the quantity by @code{\mm}, @code{\cm},
2724 @code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27 of
2725 an inch). Page layout distances can also be specified in scalable
2726 units (see the following paragraph) by appending
2727 @code{\staff-space} to the quantity. Page layout is described in
2728 detail in @ref{Page layout}.
2730 Scaled distances are always specified in units of the staff-space
2731 or, rarely, the half staff-space. The staff-space is the distance
2732 between two adjacent staff lines. The default value can be changed
2733 globally by setting the global staff size, or it can be overridden
2734 locally by changing the @code{staff-space} property of
2735 @code{StaffSymbol}. Scaled distances automatically scale with any
2736 change to the either the global staff size or the
2737 @code{staff-space} property of @code{StaffSymbol}, but fonts scale
2738 automatically only with changes to the global staff size.
2739 The global staff size thus enables the overall size of a rendered
2740 score to be easily varied. For the methods of setting the global
2741 staff size see @ref{Setting the staff size}.
2745 If just a section of a score needs to be rendered to a different
2746 scale, for example an ossia section or a footnote, the global staff
2747 size cannot simply be changed as this would affect the entire score.
2748 In such cases the change in size is made by overriding both the
2749 @code{staff-space} property of @code{StaffSymbol} and the size of
2750 the fonts. A Scheme function, @code{magstep}, is available to
2751 convert from a font size change to the equivalent change in
2752 @code{staff-space}. For an explanation and an example of its use,
2753 see @rlearning{Length and thickness of objects}.
2757 @rlearning{Length and thickness of objects}.
2761 @ref{Setting the staff size}.
2764 @node Staff symbol properties
2765 @subsection Staff symbol properties
2767 @cindex adjusting staff symbol
2768 @cindex drawing staff symbol
2769 @cindex staff symbol, setting of
2771 @c TODO Extend or remove this section. See also NR 1.6.2 Staff symbol
2772 @c Need to think of uses for these properties. Eg 'line-positions
2773 @c is used in a snippet to thicken centre line.
2774 @c If retained, add @ref to here in 1.6.2 -td
2776 The vertical position of staff lines and the number of staff lines
2777 can be defined at the same time. As the following example shows,
2778 note positions are not influenced by the staff line positions.
2780 @warning{The @code{'line-positions} property overrides the
2781 @code{'line-count} property. The number of staff lines is
2782 implicitly defined by the number of elements in the list of values
2783 for @code{'line-positions}.}
2785 @lilypond[verbatim,quote,relative=1]
2787 \override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7)
2792 The width of a staff can be modified. The units are staff
2793 spaces. The spacing of objects inside the staff is not affected by
2796 @lilypond[verbatim,quote,relative=1]
2798 \override StaffSymbol.width = #23
2805 @subsection Spanners
2807 Many objects of musical notation extend over several notes or even
2808 several bars. Examples are slurs, beams, tuplet brackets, volta
2809 repeat brackets, crescendi, trills, and glissandi. Such objects
2810 are collectively called @qq{spanners}, and have special properties to control
2811 their appearance and behaviour. Some of these properties are common
2812 to all spanners; others are restricted to a sub-set of the spanners.
2814 All spanners support the @code{spanner-interface}. A few, essentially
2815 those that draw a straight line between the two objects, support in
2816 addition the @code{line-spanner-interface}.
2819 * Using the spanner-interface::
2820 * Using the line-spanner-interface::
2823 @node Using the spanner-interface
2824 @unnumberedsubsubsec Using the @code{spanner-interface}
2826 This interface provides two properties that apply to several spanners.
2828 @subsubsubheading The @code{minimum-length} property
2830 The minimum length of the spanner is specified by the
2831 @code{minimum-length} property. Increasing this usually has the
2832 necessary effect of increasing the spacing of the notes between the
2833 two end points. However, this override has no effect on
2834 many spanners, as their length is determined by other considerations.
2835 A few examples where it is effective are shown below.
2845 Works as long as callback is made:
2849 Works not at all for:
2858 @lilypond[verbatim,quote,relative=2]
2861 % increase the length of the tie
2862 -\tweak minimum-length #5
2866 @lilypond[verbatim,quote,relative=2]
2868 \compressFullBarRests
2870 % increase the length of the rest bar
2871 \once \override MultiMeasureRest.minimum-length = #20
2876 @lilypond[verbatim,quote,relative=2]
2878 % increase the length of the hairpin
2879 \override Hairpin.minimum-length = #20
2883 This override can also be used to increase the length of slurs and
2886 @lilypond[verbatim,quote,relative=2]
2889 -\tweak minimum-length #5
2894 -\tweak minimum-length #5
2898 For some layout objects, the @code{minimum-length} property becomes
2899 effective only if the @code{set-spacing-rods} procedure is called
2900 explicitly. To do this, the @code{springs-and-rods} property should
2901 be set to @code{ly:spanner::set-spacing-rods}. For example,
2902 the minimum length of a glissando has no effect unless the
2903 @code{springs-and-rods} property is set:
2905 @lilypond[verbatim,quote,relative=1]
2909 % not effective alone
2910 \once \override Glissando.minimum-length = #20
2913 % effective only when both overrides are present
2914 \once \override Glissando.minimum-length = #20
2915 \once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods
2919 The same is true of the @code{Beam} object:
2921 @lilypond[verbatim,quote,relative=1]
2922 % not effective alone
2923 \once \override Beam.minimum-length = #20
2926 % effective only when both overrides are present
2927 \once \override Beam.minimum-length = #20
2928 \once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods
2932 @subsubsubheading The @code{to-barline} property
2934 The second useful property of the @code{spanner-interface} is
2935 @code{to-barline}. By default this is true, causing hairpins and
2936 other spanners which are terminated on the first note of a measure to
2937 end instead on the immediately preceding bar line. If set to false,
2938 the spanner will extend beyond the bar line and end on the note
2941 @lilypond[verbatim,quote,relative=2]
2942 a \< a a a a \! a a a \break
2943 \override Hairpin.to-barline = ##f
2944 a \< a a a a \! a a a
2947 This property is not effective for all spanners. For example,
2948 setting it to @code{#t} has no effect on slurs or phrasing slurs
2949 or on other spanners for which terminating on the bar line would
2952 @node Using the line-spanner-interface
2953 @unnumberedsubsubsec Using the @code{line-spanner-interface}
2955 Objects which support the @code{line-spanner-interface} include
2958 @item @code{DynamicTextSpanner}
2959 @item @code{Glissando}
2960 @item @code{TextSpanner}
2961 @item @code{TrillSpanner}
2962 @item @code{VoiceFollower}
2965 The routine responsible for drawing the stencils for these spanners is
2966 @code{ly:line-interface::print}. This routine determines the
2967 exact location of the two end points and draws a line
2968 between them, in the style requested. The locations of the two
2969 end points of the spanner are computed on-the-fly, but it is
2970 possible to override their Y-coordinates. The
2971 properties which need to be specified are nested
2972 two levels down within the property hierarchy, but the syntax of
2973 the @code{\override} command is quite simple:
2975 @lilypond[relative=2,quote,verbatim]
2977 \once \override Glissando.bound-details.left.Y = #3
2978 \once \override Glissando.bound-details.right.Y = #-2
2982 The units for the @code{Y} property are @code{staff-space}s,
2983 with the center line of the staff being the zero point.
2984 For the glissando, this is the value for @code{Y} at the
2985 X-coordinate corresponding to the center point of each note head,
2986 if the line is imagined to be extended to there.
2988 If @code{Y} is not set, the value is computed from the vertical
2989 position of the corresponding attachment point of the spanner.
2991 In case of a line break, the values for the end points are
2992 specified by the @code{left-broken} and @code{right-broken}
2993 sub-lists of @code{bound-details}. For example:
2995 @lilypond[relative=2,ragged-right,verbatim,quote]
2996 \override Glissando.breakable = ##t
2997 \override Glissando.bound-details.right-broken.Y = #-3
2998 c1 \glissando \break
3003 A number of further properties of the @code{left} and
3004 @code{right} sub-lists of the @code{bound-details} property
3005 may be modified in the same way as @code{Y}:
3009 This sets the Y-coordinate of the end point, in @code{staff-space}s
3010 offset from the staff center line. By default, it is the center of
3011 the bound object, so a glissando points to the vertical center of
3014 For horizontal spanners, such as text spanners and trill spanners,
3015 it is hardcoded to 0.
3018 This determines where the line starts and ends in the X-direction,
3019 relative to the bound object. So, a value of @w{@code{-1}} (or
3020 @code{LEFT}) makes the line start/end at the left side of the note
3021 head it is attached to.
3024 This is the absolute X-coordinate of the end point. It is usually
3025 computed on the fly, and overriding it has little useful effect.
3028 Line spanners may have symbols at the beginning or end, which is
3029 contained in this sub-property. This is for internal use; it is
3030 recommended that @code{text} be used instead.
3033 This is a markup that is evaluated to yield the stencil. It is used
3034 to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
3036 @lilypond[quote,ragged-right,relative=2,verbatim]
3037 \override TextSpanner.bound-details.left.text
3038 = \markup { \small \bold Slower }
3039 c2\startTextSpan b c a\stopTextSpan
3042 @item stencil-align-dir-y
3043 @item stencil-offset
3044 Without setting one of these, the stencil is simply put at the
3045 end-point, centered on the line, as defined by the @code{X} and
3046 @code{Y} sub-properties. Setting either @code{stencil-align-dir-y}
3047 or @code{stencil-offset} will move the symbol at the edge vertically
3048 relative to the end point of the line:
3050 @lilypond[relative=1,quote,verbatim]
3051 \override TextSpanner.bound-details.left.stencil-align-dir-y = #-2
3052 \override TextSpanner.bound-details.right.stencil-align-dir-y = #UP
3054 \override TextSpanner.bound-details.left.text = #"ggg"
3055 \override TextSpanner.bound-details.right.text = #"hhh"
3056 c4^\startTextSpan c c c \stopTextSpan
3059 Note that negative values move the text @emph{up}, contrary to the
3060 effect that might be expected, as a value of @w{@code{-1}} or
3061 @code{DOWN} means align the @emph{bottom} edge of the text with
3062 the spanner line. A value of @code{1} or @code{UP} aligns
3063 the top edge of the text with the spanner line.
3066 Setting this sub-property to @code{#t} produces an arrowhead at the
3070 This sub-property controls the space between the specified
3071 end point of the line and the actual end. Without padding, a
3072 glissando would start and end in the center of each note head.
3076 The music function @code{\endSpanners} terminates the spanner
3077 which starts on the immediately following note prematurely. It
3078 is terminated after exactly one note, or at the following bar line
3079 if @code{to-barline} is true and a bar line occurs before the next
3082 @lilypond[verbatim,quote,ragged-right,relative=2]
3084 c2 \startTextSpan c2 c2
3089 When using @code{\endSpanners} it is not necessary to close
3090 \startTextSpan with \stopTextSpan, nor is it necessary to close
3091 hairpins with @code{\!}.
3094 Internals Reference:
3095 @rinternals{TextSpanner},
3096 @rinternals{Glissando},
3097 @rinternals{VoiceFollower},
3098 @rinternals{TrillSpanner},
3099 @rinternals{line-spanner-interface}.
3102 @node Visibility of objects
3103 @subsection Visibility of objects
3105 @cindex objects, visibility of
3106 @cindex grobs, visibility of
3107 @cindex visibility of objects
3109 There are four main ways in which the visibility of layout objects
3110 can be controlled: their stencil can be removed, they can be made
3111 transparent, they can be colored white, or their
3112 @code{break-visibility} property can be overridden. The first
3113 three apply to all layout objects; the last to just a few -- the
3114 @emph{breakable} objects. The Learning Manual introduces these
3115 four techniques, see @rlearning{Visibility and color of objects}.
3117 There are also a few other techniques which are specific to
3118 certain layout objects. These are covered under Special
3122 * Removing the stencil::
3123 * Making objects transparent::
3124 * Painting objects white::
3125 * Using break-visibility::
3126 * Special considerations::
3130 @node Removing the stencil
3131 @unnumberedsubsubsec Removing the stencil
3133 @cindex stencil, removing
3135 Every layout object has a stencil property. By default this is set
3136 to the specific function which draws that object. If this property
3137 is overridden to @code{#f} no function will be called and the object
3138 will not be drawn. The default action can be recovered with
3141 @lilypond[quote,verbatim,relative=1]
3143 \override Score.BarLine.stencil = ##f
3145 \revert Score.BarLine.stencil
3149 @node Making objects transparent
3150 @unnumberedsubsubsec Making objects transparent
3152 @cindex transparent, making objects
3154 Every layout object has a transparent property which by default is
3155 set to @code{#f}. If set to @code{#t} the object still occupies
3156 space but is made invisible.
3158 @lilypond[quote,verbatim,relative=2]
3160 \once \override NoteHead.transparent = ##t
3164 @node Painting objects white
3165 @unnumberedsubsubsec Painting objects white
3167 @cindex objects, coloring
3168 @cindex coloring objects
3170 @cindex printing order
3171 @cindex overwriting objects
3172 @cindex objects, overwriting
3173 @cindex grobs, overwriting
3175 Every layout object has a color property which by default is set
3176 to @code{black}. If this is overridden to @code{white} the object
3177 will be indistinguishable from the white background. However,
3178 if the object crosses other objects the color of the crossing
3179 points will be determined by the order in which they are drawn,
3180 and this may leave a ghostly image of the white object, as shown
3183 @lilypond[quote,verbatim,relative=2]
3184 \override Staff.Clef.color = #white
3188 This may be avoided by changing the order of printing the objects.
3189 All layout objects have a @code{layer} property which should be set
3190 to an integer. Objects with the lowest value of @code{layer} are
3191 drawn first, then objects with progressively higher values are drawn,
3192 so objects with higher values overwrite objects with lower values.
3193 By default most objects are assigned a @code{layer} value of
3194 @code{1}, although a few objects, including @code{StaffSymbol} and
3195 @code{BarLine}, are assigned a value of @code{0}. The order of
3196 printing objects with the same value of @code{layer} is indeterminate.
3198 In the example above the white clef, with a default @code{layer}
3199 value of @code{1}, is drawn after the staff lines (default
3200 @code{layer} value @code{0}), so overwriting them. To change this,
3201 the @code{Clef} object must be given in a lower value of
3202 @code{layer}, say @w{@code{-1}}, so that it is drawn earlier:
3204 @lilypond[quote,verbatim,relative=2]
3205 \override Staff.Clef.color = #white
3206 \override Staff.Clef.layer = #-1
3210 @node Using break-visibility
3211 @unnumberedsubsubsec Using break-visibility
3213 @c TODO Add making other objects breakable
3215 @cindex break-visibility
3217 Most layout objects are printed only once, but some like
3218 bar lines, clefs, time signatures and key signatures, may need
3219 to be printed twice when a line break occurs -- once at the end
3220 of the line and again at the start of the next line. Such
3221 objects are called @emph{breakable}, and have a property, the
3222 @code{break-visibility} property to control their visibility
3223 at the three positions in which they may appear -- at the
3224 start of a line, within a line if they are changed, and at the
3225 end of a line if a change takes place there.
3227 For example, the time signature
3228 by default will be printed at the start of the first line, but
3229 nowhere else unless it changes, when it will be printed at the
3230 point at which the change occurs. If this change occurs at the
3231 end of a line the new time signature will be printed at the start
3232 of the next line and a cautionary time signature will be printed
3233 at the end of the previous line as well.
3235 This behaviour is controlled by the @code{break-visibility}
3236 property, which is explained in
3237 @c Leave this ref on a newline - formats incorrectly otherwise -td
3238 @rlearning{Visibility and color of objects}. This property takes
3239 a vector of three booleans which, in order, determine whether the
3240 object is printed at the end of, within the body of, or at the
3241 beginning of a line. Or to be more precise, before a line break,
3242 where there is no line break, or after a line break.
3244 Alternatively, these eight combinations may be specified
3245 by pre-defined functions, defined in @file{scm/output-lib.scm},
3246 where the last three columns indicate whether the layout objects
3247 will be visible in the positions shown at the head of the columns:
3249 @multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}
3250 @headitem Function @tab Vector @tab Before @tab At no @tab After
3251 @headitem form @tab form @tab break @tab break @tab break
3253 @item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes
3254 @item @code{begin-of-line-visible} @tab @code{'#(#f #f #t)} @tab no @tab no @tab yes
3255 @item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no
3256 @item @code{end-of-line-visible} @tab @code{'#(#t #f #f)} @tab yes @tab no @tab no
3257 @item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no
3258 @item @code{center-invisible} @tab @code{'#(#t #f #t)} @tab yes @tab no @tab yes
3259 @item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes
3260 @item @code{all-invisible} @tab @code{'#(#f #f #f)} @tab no @tab no @tab no
3263 The default settings of @code{break-visibility} depend on the
3264 layout object. The following table shows all the layout objects
3265 of interest which are affected by @code{break-visibility} and the
3266 default setting of this property:
3268 @multitable @columnfractions .3 .3 .4
3270 @headitem Layout object @tab Usual context @tab Default setting
3272 @c omit Ambitus as it appears not to be affected by break-visibility -td
3273 @c @item @code{Ambitus} @tab as specified @tab @code{begin-of-line-visible}
3274 @item @code{BarLine} @tab @code{Score} @tab calculated
3275 @item @code{BarNumber} @tab @code{Score} @tab @code{begin-of-line-visible}
3276 @c omit the following item until it can be explained -td
3277 @c @item @code{BreakAlignGroup} @tab @code{Score} @tab calculated
3278 @item @code{BreathingSign} @tab @code{Voice} @tab @code{begin-of-line-invisible}
3279 @item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible}
3280 @item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible}
3281 @item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible}
3282 @item @code{KeyCancellation} @tab @code{Staff} @tab @code{begin-of-line-invisible}
3283 @item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible}
3284 @c omit LeftEdge until it can be explained -td
3285 @c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible}
3286 @item @code{ClefModifier} @tab @code{Staff} @tab @code{begin-of-line-visible}
3287 @item @code{RehearsalMark} @tab @code{Score} @tab @code{end-of-line-invisible}
3288 @item @code{TimeSignature} @tab @code{Staff} @tab @code{all-visible}
3292 The example below shows the use of the vector form to control the
3293 visibility of bar lines:
3295 @lilypond[quote,verbatim,relative=1,ragged-right]
3298 % Remove bar line at the end of the current line
3299 \once \override Score.BarLine.break-visibility = ##(#f #t #t)
3305 Although all three components of the vector used to override
3306 @code{break-visibility} must be present, not all of them are
3307 effective with every layout object, and some combinations may
3308 even give errors. The following limitations apply:
3311 @item Bar lines cannot be printed at start of line.
3312 @item A bar number cannot be printed at the start of the first
3313 line unless it is set to be different from 1.
3314 @item Clef -- see below
3315 @item Double percent repeats are either all printed or all
3316 suppressed. Use begin-of line-invisible to print and
3317 all-invisible to suppress.
3318 @item Key signature -- see below
3319 @item ClefModifier -- see below
3322 @node Special considerations
3323 @unnumberedsubsubsec Special considerations
3325 @subsubsubheading Visibility following explicit changes
3327 @cindex key signature, visibility following explicit change
3328 @cindex explicitKeySignatureVisibility
3329 @cindex clef, visibility following explicit change
3330 @cindex explicitClefVisibility
3332 The @code{break-visibility} property controls the visibility of
3333 key signatures and changes of clef only at the start of lines,
3334 i.e. after a break. It has no effect on the visibility of the
3335 key signature or clef following an explicit key change or an
3336 explicit clef change within or at the end of a line. In the
3337 following example the key signature following the explicit change
3338 to B-flat major is still visible, even though @code{all-invisible}
3341 @lilypond[quote,verbatim,relative=1,ragged-right]
3344 % Try to remove all key signatures
3345 \override Staff.KeySignature.break-visibility = #all-invisible
3353 The visibility of such explicit key signature and clef changes is
3354 controlled by the @code{explicitKeySignatureVisibility} and
3355 @code{explicitClefVisibility} properties. These are the equivalent
3356 of the @code{break-visibility} property and both take a vector of
3357 three booleans or the predefined functions listed above, exactly like
3358 @code{break-visibility}. Both are properties of the Staff context,
3359 not the layout objects themselves, and so they are set using the
3360 @code{\set} command. Both are set by default to @code{all-visible}.
3361 These properties control only the visibility of key signatures and
3362 clefs resulting from explicit changes and do not affect key
3363 signatures and clefs at the beginning of lines;
3364 @code{break-visibility} must still be overridden in the appropriate
3365 object to remove these.
3367 @lilypond[quote,verbatim,relative=1,ragged-right]
3370 \set Staff.explicitKeySignatureVisibility = #all-invisible
3371 \override Staff.KeySignature.break-visibility = #all-invisible
3378 @subsubsubheading Visibility of cancelling accidentals
3380 To remove the cancelling accidentals printed at an explicit key
3381 change, set the Staff context property @code{printKeyCancellation}
3384 @lilypond[quote,verbatim,relative=1,ragged-right]
3387 \set Staff.explicitKeySignatureVisibility = #all-invisible
3388 \set Staff.printKeyCancellation = ##f
3389 \override Staff.KeySignature.break-visibility = #all-invisible
3396 With these overrides only the accidentals before the notes remain
3397 to indicate the change of key.
3399 Note that when changing the key to C@tie{}major or A@tie{}minor
3400 the cancelling accidentals would be the @emph{only} indication of
3401 the key change. In this case setting @code{printKeyCancellation} to
3402 @code{#f} has no effect:
3404 @lilypond[quote,verbatim,relative=1,ragged-right]
3407 \set Staff.explicitKeySignatureVisibility = #all-invisible
3408 \set Staff.printKeyCancellation = ##f
3415 To suppress the cancelling accidentals even when the key is
3416 changed to C@tie{}major or A@tie{}minor, override
3417 the visibility of the @code{KeyCancellation} grob instead:
3419 @lilypond[quote,verbatim,relative=1,ragged-right]
3422 \set Staff.explicitKeySignatureVisibility = #all-invisible
3423 \override Staff.KeyCancellation.break-visibility = #all-invisible
3430 @c TODO Add visibility of cautionary accidentals before notes
3432 @subsubsubheading Automatic bars
3434 @cindex automaticBars
3435 @cindex bar lines, suppressing
3437 As a special case, the printing of bar lines can also be turned off
3438 by setting the @code{automaticBars} property in the Score context.
3439 If set to @code{#f}, bar lines will not be printed automatically;
3440 they must be explicitly created with a @code{\bar} command. Unlike
3441 the @code{\cadenzaOn} predefined command, measures are still counted.
3442 Bar generation will resume according to that count if this property
3443 is later set to @code{#t}. When set to @code{#f}, line breaks can
3444 occur only at explicit @code{\bar} commands.
3448 @subsubsubheading Transposed clefs
3450 @cindex transposed clefs, visibility of
3451 @cindex visibility of transposed clefs
3452 @cindex clefs, visibility of transposition
3454 The small transposition symbol on transposed clefs is produced by the
3455 @code{ClefModifier} layout object. Its visibility is automatically
3456 inherited from the @code{Clef} object, so it is not necessary to apply
3457 any required @code{break-visibility} overrides to the @code{ClefModifier}
3458 layout objects to suppress transposition symbols for invisible clefs.
3460 For explicit clef changes, the @code{explicitClefVisibility}
3461 property controls both the clef symbol and any transposition symbol
3466 @rlearning{Visibility and color of objects}.
3470 @subsection Line styles
3472 Some performance indications, e.g., @i{rallentando} and
3473 @i{accelerando} and @i{trills} are written as text and are
3474 extended over many measures with lines, sometimes dotted or wavy.
3476 These all use the same routines as the glissando for drawing the
3477 texts and the lines, and tuning their behavior is therefore also
3478 done in the same way. It is done with a spanner, and the routine
3479 responsible for drawing the spanners is
3480 @code{ly:line-interface::print}. This routine determines the
3481 exact location of the two @i{span points} and draws a line
3482 between them, in the style requested.
3484 Here is an example showing the different line styles available,
3485 and how to tune them.
3487 @lilypond[relative=2,ragged-right,verbatim,quote]
3489 \once \override Glissando.style = #'dashed-line
3491 \override Glissando.style = #'dotted-line
3493 \override Glissando.style = #'zigzag
3495 \override Glissando.style = #'trill
3499 The locations of the end-points of the spanner are computed
3500 on-the-fly for every graphic object, but it is possible to
3504 @lilypond[relative=2,ragged-right,verbatim,quote]
3506 \once \override Glissando.bound-details.right.Y = #-2
3510 The value for @code{Y} is set to @w{@code{-2}} for the right end
3511 point. The left side may be similarly adjusted by specifying
3512 @code{left} instead of @code{right}.
3514 If @code{Y} is not set, the value is computed from the vertical
3515 position of the left and right attachment points of the spanner.
3517 Other adjustments of spanners are possible, for details, see
3520 @node Rotating objects
3521 @subsection Rotating objects
3523 Both layout objects and elements of markup text can be rotated by
3524 any angle about any point, but the method of doing so differs.
3527 * Rotating layout objects::
3531 @node Rotating layout objects
3532 @unnumberedsubsubsec Rotating layout objects
3534 @cindex rotating objects
3535 @cindex objects, rotating
3537 All layout objects which support the @code{grob-interface} can be
3538 rotated by setting their @code{rotation} property. This takes a
3539 list of three items: the angle of rotation counter-clockwise,
3540 and the x and y coordinates of the point relative to the object's
3541 reference point about which the rotation is to be performed. The
3542 angle of rotation is specified in degrees and the coordinates in
3545 The angle of rotation and the coordinates of the rotation point must
3546 be determined by trial and error.
3548 @cindex hairpins, angled
3549 @cindex angled hairpins
3551 There are only a few situations where the rotation of layout
3552 objects is useful; the following example shows one situation where
3555 @lilypond[quote,verbatim,relative=1]
3557 \override Hairpin.rotation = #'(20 -1 0)
3561 @node Rotating markup
3562 @unnumberedsubsubsec Rotating markup
3564 All markup text can be rotated to lie at any angle by prefixing it
3565 with the @code{\rotate} command. The command takes two arguments:
3566 the angle of rotation in degrees counter-clockwise and the text to
3567 be rotated. The extents of the text are not rotated: they take
3568 their values from the extremes of the x and y coordinates of the
3569 rotated text. In the following example the
3570 @code{outside-staff-priority} property for text is set to @code{#f}
3571 to disable the automatic collision avoidance, which would push some
3572 of the text too high.
3574 @lilypond[quote,verbatim,relative=1]
3575 \override TextScript.outside-staff-priority = ##f
3576 g4^\markup { \rotate #30 "a G" }
3577 b^\markup { \rotate #30 "a B" }
3578 des^\markup { \rotate #30 "a D-Flat" }
3579 fis^\markup { \rotate #30 "an F-Sharp" }
3582 @node Advanced tweaks
3583 @section Advanced tweaks
3585 This section discusses various approaches to fine tuning the
3586 appearance of the printed score.
3589 * Aligning objects::
3590 * Vertical grouping of grobs::
3591 * Modifying stencils::
3592 * Modifying shapes::
3593 * Unpure-pure containers::
3598 @rlearning{Tweaking output},
3599 @rlearning{Other sources of information}.
3602 @ref{Explaining the Internals Reference},
3603 @ref{Modifying properties}.
3606 @rextend{Interfaces for programmers}.
3609 @file{scm/define-grobs.scm}.
3612 @rlsr{Tweaks and overrides}.
3614 Internals Reference:
3615 @rinternals{All layout objects}.
3618 @node Aligning objects
3619 @subsection Aligning objects
3621 Graphical objects which support the @code{self-alignment-interface}
3622 and/or the @code{side-position-interface} can be aligned to a previously
3623 placed object in a variety of ways. For a list of these objects, see
3624 @rinternals{self-alignment-interface} and @rinternals{side-position-interface}.
3626 All graphical objects have a reference point, a horizontal extent and a
3627 vertical extent. The horizontal extent is a pair of numbers
3628 giving the displacements from the reference point of the left and
3629 right edges, displacements to the left being negative. The vertical
3630 extent is a pair of numbers giving the displacement from the reference
3631 point to the bottom and top edges, displacements down being negative.
3633 An object's position on a staff is given by the values of the
3634 @code{X-offset} and @code{Y-offset} properties. The value of
3635 @code{X-offset} gives the displacement from the X coordinate of
3636 the reference point of the parent object, and the value of
3637 @code{Y-offset} gives the displacement from the center line of the
3638 staff. The values of @code{X-offset} and @code{Y-offset} may
3639 be set directly or may be set to be calculated by procedures in order
3640 to achieve alignment with the parent object.
3642 @warning{Many objects have special positioning considerations which
3643 cause any setting of @code{X-offset} or @code{Y-offset} to be
3644 ignored or modified, even though the object supports the
3645 @code{self-alignment-interface}. Overriding the @code{X-offset}
3646 or @code{Y-offset} properties to a fixed value causes the respective
3647 @code{self-alignment} property to be disregarded.}
3649 For example, an accidental can be repositioned vertically by setting
3650 @code{Y-offset} but any changes to @code{X-offset} have no effect.
3652 Rehearsal marks may be aligned with breakable objects such as bar
3653 lines, clef symbols, time signature symbols and key signatures. There
3654 are special properties to be found in the @code{break-aligned-interface}
3655 for positioning rehearsal marks on such objects.
3659 @ref{Using the break-alignable-interface}.
3662 @rextend{Callback functions}.
3665 * Setting X-offset and Y-offset directly::
3666 * Using the side-position-interface::
3667 * Using the self-alignment-interface::
3668 * Using the break-alignable-interface::
3671 @node Setting X-offset and Y-offset directly
3672 @unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly
3674 Numerical values may be given to the @code{X-offset} and @code{Y-offset}
3675 properties of many objects. The following example shows three
3676 notes with the default fingering position and the positions with @code{X-offset}
3677 and @code{Y-offset} modified.
3679 @lilypond[verbatim,quote,relative=2]
3686 -\tweak X-offset #-1
3693 @node Using the side-position-interface
3694 @unnumberedsubsubsec Using the @code{side-position-interface}
3696 An object which supports the @code{side-position-interface} can be
3697 placed next to its parent object so that
3698 the specified edges of the two objects touch. The object may be
3699 placed above, below, to the right or to the left of the parent.
3700 The parent cannot be specified; it is determined by the order of
3701 elements in the input stream. Most objects have the associated
3702 note head as their parent.
3704 The values of the @code{side-axis} and @code{direction} properties
3705 determine where the object is to be placed, as follows:
3707 @c TODO add an example of each to the table
3709 @multitable @columnfractions .3 .3 .3
3710 @headitem @code{side-axis} @tab @code{direction} @tab
3711 @headitem property @tab property @tab Placement
3713 @item @code{0} @tab @code{-1} @tab left
3714 @item @code{0} @tab @code{1} @tab right
3715 @item @code{1} @tab @code{-1} @tab below
3716 @item @code{1} @tab @code{1} @tab above
3720 When @code{side-axis} is @code{0}, @code{X-offset} should be set to
3721 the procedure @code{ly:side-position-interface::x-aligned-side}.
3722 This procedure will return the correct value of @code{X-offset} to
3723 place the object to the left or right side of the parent according
3724 to value of @code{direction}.
3726 When @code{side-axis} is @code{1}, @code{Y-offset} should be set to
3727 the procedure @code{ly:side-position-interface::y-aligned-side}.
3728 This procedure will return the correct value of @code{Y-offset} to
3729 place the object to the top or bottom of the parent according
3730 to value of @code{direction}.
3732 @c TODO Add examples
3734 @node Using the self-alignment-interface
3735 @unnumberedsubsubsec Using the @code{self-alignment-interface}
3737 @subsubsubheading Self-aligning objects horizontally
3739 The horizontal alignment of an object which supports the
3740 @code{self-alignment-interface} is controlled by the value of
3741 the @code{self-alignment-X} property, provided the object's
3742 @code{X-offset} property is set to
3743 @code{ly:self-alignment-interface::x-aligned-on-self}.
3744 @code{self-alignment-X} may be given any
3745 real value, in units of half the total X extent of the
3746 object. Negative values move the object to the right, positive
3747 to the left. A value of @code{0} centers the object on the
3748 reference point of its parent, a value of @w{@code{-1}} aligns the
3749 left edge of the object on the reference point of its parent,
3750 and a value of @code{1} aligns the right edge of the object on the
3751 reference point of its parent. The symbols @code{LEFT},
3752 @code{CENTER}, and @code{RIGHT} may be used instead of the values
3753 @w{@code{-1}}, @code{0}, and @code{1}, respectively.
3755 Normally the @code{\override} command would be used to modify the
3756 value of @code{self-alignment-X}, but the @code{\tweak} command
3757 can be used to separately align several annotations on a single
3760 @lilypond[quote,verbatim,relative=1]
3762 -\tweak self-alignment-X #-1
3764 -\tweak self-alignment-X #0
3766 -\tweak self-alignment-X #RIGHT
3768 -\tweak self-alignment-X #-2.5
3769 ^"aligned further to the right"
3772 @subsubsubheading Self-aligning objects vertically
3774 Objects may be aligned vertically in an analogous way to aligning
3775 them horizontally if the @code{Y-offset} property is set to
3776 @code{ly:self-alignment-interface::y-aligned-on-self}. However,
3777 other mechanisms are often involved in vertical alignment: the
3778 value of @code{Y-offset} is just one variable taken into account.
3779 This may make adjusting the value of some objects tricky.
3780 The units are just half the vertical extent of the object, which
3781 is usually quite small, so quite large numbers may be required.
3782 A value of @w{@code{-1}} aligns the lower edge of the object with
3783 the reference point of the parent object, a value of @code{0}
3784 aligns the center of the object with the reference point of the
3785 parent, and a value of @code{1} aligns the top edge of the object
3786 with the reference point of the parent. The symbols @code{DOWN},
3787 @code{CENTER}, and @code{UP} may be substituted for @w{@code{-1}},
3788 @code{0}, and @code{1}, respectively.
3790 @subsubsubheading Self-aligning objects in both directions
3792 By setting both @code{X-offset} and @code{Y-offset}, an object may
3793 be aligned in both directions simultaneously.
3795 The following example shows how to adjust a fingering mark so
3796 that it nestles close to the note head.
3798 @lilypond[quote,verbatim,relative=2]
3800 -\tweak self-alignment-X #0.5 % move horizontally left
3801 -\tweak Y-offset #ly:self-alignment-interface::y-aligned-on-self
3802 -\tweak self-alignment-Y #-1 % move vertically up
3807 @unnumberedsubsubsec Using the @code{aligned-on-parent} procedures
3809 @c Cannot document as they do not seem to operate consistently on all objects -td
3810 @c TODO investigate further
3812 The @code{aligned-on-parent} procedures are used in the same way
3813 as the @code{aligned-on-self} procedures, they difference being
3814 that they permit an object to be aligned with the @emph{edges} of
3815 the parent rather than the parent's reference point. The following
3816 example shows the difference:
3820 @lilypond[verbatim,quote]
3826 @unnumberedsubsubsec Using the @code{centered-on-parent} procedures
3828 @c Cannot document as they do not seem to operate consistently on all objects -td
3829 @c TODO investigate further
3833 @c TODO The align-interface, BassFigureAlignment and VerticalAlignment
3835 @node Using the break-alignable-interface
3836 @unnumberedsubsubsec Using the @code{break-alignable-interface}
3838 @cindex align to objects
3839 @cindex break-align-symbols
3841 Rehearsal marks and bar numbers may be aligned with notation
3842 objects other than bar lines. These objects include @code{ambitus},
3843 @code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
3844 @code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
3845 @code{time-signature}.
3847 Each type of object has its own default reference point, to which
3848 rehearsal marks are aligned:
3850 @lilypond[verbatim,quote,relative=1]
3851 % The rehearsal mark will be aligned to right edge of the Clef
3852 \override Score.RehearsalMark.break-align-symbols = #'(clef)
3857 % The rehearsal mark will be centered above the Time Signature
3858 \override Score.RehearsalMark.break-align-symbols = #'(time-signature)
3864 % The rehearsal mark will be centered above the Breath Mark
3865 \override Score.RehearsalMark.break-align-symbols = #'(breathing-sign)
3874 A list of possible target alignment objects may be specified. If
3875 some of the objects are invisible at that point due to the setting
3876 of @code{break-visibility} or the explicit visibility settings for
3877 keys and clefs, the rehearsal mark or bar number is aligned to the
3878 first object in the list which is visible. If no objects in the
3879 list are visible the object is aligned to the bar line. If the bar
3880 line is invisible the object is aligned to the place where the bar
3883 @lilypond[verbatim,quote,relative=1]
3884 % The rehearsal mark will be aligned to the right edge of the Key Signature
3885 \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
3890 % The rehearsal mark will be aligned to the right edge of the Clef
3891 \set Staff.explicitKeySignatureVisibility = #all-invisible
3892 \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
3897 % The rehearsal mark will be centered above the Bar Line
3898 \set Staff.explicitKeySignatureVisibility = #all-invisible
3899 \set Staff.explicitClefVisibility = #all-invisible
3900 \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
3907 The alignment of the rehearsal mark relative to the notation object
3908 can be changed, as shown in the following example. In a score with
3909 multiple staves, this setting should be done for all the staves.
3911 @lilypond[verbatim,quote,relative=1]
3912 % The RehearsalMark will be aligned with the right edge of the Key Signature
3913 \override Score.RehearsalMark.break-align-symbols = #'(key-signature)
3919 % The RehearsalMark will be centered above the Key Signature
3920 \once \override Score.KeySignature.break-align-anchor-alignment = #CENTER
3924 % The RehearsalMark will be aligned with the left edge of the Key Signature
3925 \once \override Score.KeySignature.break-align-anchor-alignment = #LEFT
3931 The rehearsal mark can also be offset to the right or left of the left
3932 edge by an arbitrary amount. The units are staff-spaces:
3934 @lilypond[verbatim,quote,relative=1]
3935 % The RehearsalMark will be aligned with the left edge of the Key Signature
3936 % and then shifted right by 3.5 staff-spaces
3937 \override Score.RehearsalMark.break-align-symbols = #'(key-signature)
3938 \once \override Score.KeySignature.break-align-anchor = #3.5
3942 % The RehearsalMark will be aligned with the left edge of the Key Signature
3943 % and then shifted left by 2 staff-spaces
3944 \once \override Score.KeySignature.break-align-anchor = #-2
3951 @node Vertical grouping of grobs
3952 @subsection Vertical grouping of grobs
3954 @c TODO Expand this section
3956 The VerticalAlignment and VerticalAxisGroup grobs work together.
3957 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
3958 etc. VerticalAlignment then vertically aligns the different grobs
3959 grouped together by VerticalAxisGroup. There is usually only one
3960 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
3964 @node Modifying stencils
3965 @subsection Modifying stencils
3967 All layout objects have a @code{stencil} property which is part of
3968 the @code{grob-interface}. By default, this property is usually
3969 set to a function specific to the object that is tailor-made to
3970 render the symbol which represents it in the output. For example,
3971 the standard setting for the @code{stencil} property of the
3972 @code{MultiMeasureRest} object is @code{ly:multi-measure-rest::print}.
3974 The standard symbol for any object can be replaced by modifying the
3975 @code{stencil} property to reference a different, specially-written,
3976 procedure. This requires a high level of knowledge of the internal
3977 workings of LilyPond, but there is an easier way which can often
3978 produce adequate results.
3980 This is to set the @code{stencil} property to the procedure which
3981 prints text -- @code{ly:text-interface::print} -- and to add a
3982 @code{text} property to the object which is set to contain the
3983 markup text which produces the required symbol. Due to the
3984 flexibility of markup, much can be achieved -- see in particular
3985 @ref{Graphic notation inside markup}.
3987 The following example demonstrates this by changing the note head
3988 symbol to a cross within a circle.
3990 @lilypond[verbatim,quote]
3992 \once \override NoteHead.stencil = #ly:text-interface::print
3993 \once \override NoteHead.text = \markup {
3995 \halign #-0.7 \draw-circle #0.85 #0.2 ##f
3996 \musicglyph #"noteheads.s2cross"
4004 Any of the glyphs in the feta Font can be supplied to the
4005 @code{\musicglyph} markup command -- see @ref{The Feta font}.
4007 @c TODO Add inserting eps files or ref to later
4009 @c TODO Add inserting Postscript or ref to later
4013 @ref{Graphic notation inside markup},
4014 @ref{Formatting text},
4015 @ref{Text markup commands},
4016 @ref{The Feta font}.
4019 @node Modifying shapes
4020 @subsection Modifying shapes
4023 * Modifying ties and slurs::
4026 @node Modifying ties and slurs
4027 @unnumberedsubsubsec Modifying ties and slurs
4029 @cindex slurs, modifying
4030 @cindex ties, modifying
4031 @cindex Bézier curves, control points
4032 @cindex control points, Bézier curves
4034 @code{Tie}s, @code{Slur}s, @code{PhrasingSlur}s,
4035 @code{LaissezVibrerTie}s and @code{RepeatTie}s are all drawn as
4036 third-order Bézier curves. If the shape of the tie or slur which
4037 is calculated automatically is not optimum, the shape may be
4038 modified manually in two ways:
4042 by specifying the displacements to be made to the control points
4043 of the automatically calculated Bézier curve, or
4046 by explicitly specifying the positions of the four control points
4047 required to define the wanted curve.
4050 Both methods are explained below. The first method is more suitable
4051 if only slight adjustments to the curve are required; the second may
4052 be better for creating curves which are related to just a single
4055 @subsubsubheading Cubic Bézier curves
4057 Third-order or cubic Bézier curves are defined by four control
4058 points. The first and fourth control points are precisely the
4059 starting and ending points of the curve. The intermediate two
4060 control points define the shape. Animations showing how the curve
4061 is drawn can be found on the web, but the following description
4062 may be helpful. The curve starts from the first control point
4063 heading directly towards the second, gradually bending over to
4064 head towards the third and continuing to bend over to head towards
4065 the fourth, arriving there travelling directly from the third
4066 control point. The curve is entirely contained in the
4067 quadrilateral defined by the four control points. Translations,
4068 rotations and scaling of the control points all result in exactly
4069 the same operations on the curve.
4071 @subsubsubheading Specifying displacements from current control points
4073 @cindex shaping slurs and ties
4076 In this example the automatic placement of the tie is not optimum,
4077 and @code{\tieDown} would not help.
4079 @lilypond[verbatim,quote,relative=1]
4083 { r4 <g c,> <g c,> <g c,> }
4087 Adjusting the control points of the tie with @code{\shape} allows
4088 the collisions to be avoided.
4090 The syntax of @code{\shape} is
4093 [-]@code{\shape} @var{displacements} @var{item}
4096 This will reposition the control-points of @var{item} by the amounts
4097 given by @var{displacements}. The @var{displacements} argument is a
4098 list of number pairs or a list of such lists. Each element of a pair
4099 represents the displacement of one of the coordinates of a
4100 control-point. If @var{item} is a string, the result is
4101 @code{\once\override} for the specified grob type. If @var{item} is
4102 a music expression, the result is the same music expression with an
4103 appropriate tweak applied.
4105 In other words, the @code{\shape} function can act as either a
4106 @code{\once\override} command or a @code{\tweak} command depending
4107 on whether the @var{item} argument is a grob name, like @qq{Slur},
4108 or a music expression, like @qq{(}. The @var{displacements} argument
4109 specifies the displacements of the four control points as a list of
4110 four pairs of (dx . dy) values in units of staff-spaces (or a list
4111 of such lists if the curve has more than one segment).
4113 The leading hyphen is required if and only if the @code{\tweak} form
4116 So, using the same example as above and the @code{\once\override}
4117 form of @code{\shape}, this will raise the tie by half a staff-space:
4119 @lilypond[verbatim,quote,relative=1]
4122 \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
4126 { r4 <g c,> <g c,> <g c,> }
4130 This positioning of the tie is better, but maybe it should be raised
4131 more in the center. The following example does this, this time using
4132 the alternative @code{\tweak} form:
4134 @lilypond[verbatim,quote,relative=1]
4137 e1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e
4140 { r4 <g c,> <g c,> <g c,> }
4144 Changes to the horizontal positions of the control points may be made
4145 in the same way, and two different curves starting at the same
4146 musical moment may also be shaped:
4148 @lilypond[verbatim,quote,ragged-right,relative=2]
4150 \shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
4151 \shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
4155 The @code{\shape} function can also displace the control points of
4156 curves which stretch across line breaks. Each piece of the broken
4157 curve can be given its own list of offsets. If changes to a
4158 particular segment are not needed, the empty list can serve as a
4159 placeholder. In this example the line break makes the single slur
4162 @lilypond[verbatim,quote,ragged-right,relative=1]
4168 Changing the shapes of the two halves of the slur makes it clearer
4169 that the slur continues over the line break:
4171 @lilypond[verbatim,quote,ragged-right,relative=1]
4172 % () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
4173 % if any of the segments does not need to be changed
4175 (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
4176 ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
4183 If an S-shaped curve is required the control points must always be
4184 adjusted manually --- LilyPond will never select such shapes
4187 @lilypond[verbatim,quote,relative=2]
4188 c8( e b-> f d' a e-> g)
4189 \shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
4190 c8\( e b-> f d' a e-> g\)
4193 @subsubsubheading Specifying control points explicitly
4195 The coordinates of the Bézier control points are specified in units
4196 of staff-spaces. The X@tie{}coordinate is relative to the reference
4197 point of the note to which the tie or slur is attached, and the
4198 Y@tie{}coordinate is relative to the staff center line. The
4199 coordinates are specified as a list of four pairs of decimal numbers
4200 (reals). One approach is to estimate the coordinates of the two
4201 end points, and then guess the two intermediate points. The optimum
4202 values are then found by trial and error. Be aware that these values
4203 may need to be manually adjusted if any further changes are made to
4204 the music or the layout.
4206 One situation where specifying the control points explicitly is
4207 preferable to specifying displacements is when they need to be
4208 specified relative to a single note. Here is an example of this.
4209 It shows one way of indicating a slur extending into alternative
4210 sections of a volta repeat.
4212 @lilypond[verbatim,quote,relative=2]
4214 \repeat volta 3 { c4 d( e f }
4219 % create a slur and move it to a new position
4220 % the <> is just an empty chord to carry the slur termination
4221 -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
4226 % create a slur and move it to a new position
4227 -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
4234 It is not possible to modify shapes of ties or slurs by changing
4235 the @code{control-points} property if there are multiple ties or slurs
4236 at the same musical moment -- the @code{\tweak} command will also not
4237 work in this case. However, the @code{tie-configuration} property of
4238 @code{TieColumn} can be overridden to set start line and direction as
4242 Internals Reference:
4243 @rinternals{TieColumn}.
4246 @node Unpure-pure containers
4247 @subsection Unpure-pure containers
4249 @cindex Scheme, pure containers
4250 @cindex Scheme, unpure containers
4251 @cindex pure containers, Scheme
4252 @cindex unpure containers, Scheme
4253 @cindex horizontal spacing, overriding
4255 Unpure-pure containers are useful for overriding @emph{Y-axis} spacing
4256 calculations - specifically @code{Y-offset} and @code{Y-extent} - with a
4257 Scheme function instead of a literal (i.e. a number or pair).
4259 For certain grobs, the @code{Y-extent} is based on the @code{stencil}
4260 property, overriding the stencil property of one of these will
4261 require an additional @code{Y-extent} override with an unpure-pure
4262 container. When a function overrides a @code{Y-offset} and/or
4263 @code{Y-extent} it is assumed that this will trigger line breaking
4264 calculations too early during compilation. So the function is not
4265 evaluated at all (usually returning a value of @samp{0} or
4266 @samp{'(0 . 0)}) which can result in collisions. A @q{pure} function
4267 will not affect properties, objects or grob suicides and therefore will
4268 always have its Y-axis-related evaluated correctly.
4270 Currently, there are about thirty functions that are already considered
4271 @q{pure} and Unpure-pure containers are a way to set functions not on
4272 this list as @q{pure}. The @q{pure} function is evaluated @emph{before}
4273 any line-breaking and so the horizontal spacing can be adjusted
4274 @q{in time}. The @q{unpure} function is then evaluated @emph{after}
4277 @warning{As it is difficult to always know which functions are on this
4278 list we recommend that any @q{pure} functions you create do not use
4279 @code{Beam} or @code{VerticalAlignment} grobs.}
4281 An unpure-pure container is constructed as follows;
4283 @code{(ly:make-unpure-pure-container f0 f1)}
4285 where @code{f0} is a function taking @var{n} arguments (@var{n >= 1})
4286 and the first argument must always be the grob. This is the function
4287 that gives the actual result. @var{f1} is the function being labeled
4288 as @q{pure} that takes @var{n + 2} arguments. Again, the first argument
4289 must always still be the grob but the second and third are @q{start}
4290 and @q{end} arguments.
4292 @var{start} and @var{end} are, for all intents and purposes, dummy
4293 values that only matter for @code{Spanners} (i.e @code{Hairpin} or
4294 @code{Beam}), that can return different height estimations based on a
4295 starting and ending column.
4297 The rest are the other arguments to the first function (which
4298 may be none if @var{n = 1}).
4300 The results of the second function are used as an approximation of the
4301 value needed which is then used by the first function to get the real
4302 value which is then used for fine-tuning much later during the spacing
4305 @lilypond[verbatim,quote,ragged-right]
4306 #(define (square-line-circle-space grob)
4307 (let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
4308 (notename (ly:pitch-notename pitch)))
4309 (if (= 0 (modulo notename 2))
4310 (make-circle-stencil 0.5 0.0 #t)
4311 (make-filled-box-stencil '(0 . 1.0)
4314 squareLineCircleSpace = {
4315 \override NoteHead.stencil = #square-line-circle-space
4318 smartSquareLineCircleSpace = {
4319 \squareLineCircleSpace
4320 \override NoteHead.Y-extent =
4321 #(ly:make-unpure-pure-container
4322 ly:grob::stencil-height
4323 (lambda (grob start end) (ly:grob::stencil-height grob)))
4326 \new Voice \with { \remove "Stem_engraver" }
4328 \squareLineCircleSpace
4330 \smartSquareLineCircleSpace
4335 In the first measure, without the unpure-pure container, the spacing
4336 engine does not know the width of the note head and lets it collide with
4337 the accidentals. In the second measure, with unpure-pure containers,
4338 the spacing engine knows the width of the note heads and avoids the
4339 collision by lengthening the line accordingly.
4341 Usually for simple calculations nearly-identical functions for both the
4342 @q{unpure} and @q{pure} parts can be used, by only changing the number
4343 of arguments passed to, and the scope of, the function.
4345 @warning{If a function is labeled as @q{pure} and it turns out not to
4346 be, the results can be unexpected.}
4349 @node Using music functions
4350 @section Using music functions
4352 @c TODO -- add @seealso, etc. to these subsections
4354 Where tweaks need to be reused with different music expressions,
4355 it is often convenient to make the tweak part of a @emph{music
4356 function}. In this section, we discuss only @emph{substitution}
4357 functions, where the object is to substitute a variable into a
4358 piece of LilyPond input code. Other more complex functions are
4359 described in @rextend{Music functions}.
4362 * Substitution function syntax::
4363 * Substitution function examples::
4366 @node Substitution function syntax
4367 @subsection Substitution function syntax
4369 Making a function that substitutes a variable into LilyPond
4370 code is easy. The general form of these functions is
4374 #(define-music-function
4375 (parser location @var{arg1} @var{arg2} @dots{})
4376 (@var{type1?} @var{type2?} @dots{})
4378 @var{@dots{}music@dots{}}
4385 @multitable @columnfractions .33 .66
4386 @item @code{@var{argN}}
4387 @tab @var{n}th argument
4389 @item @code{@var{typeN?}}
4390 @tab a scheme @emph{type predicate} for which @code{@var{argN}}
4391 must return @code{#t}.
4393 @item @code{@var{@dots{}music@dots{}}}
4394 @tab normal LilyPond input, using @code{$} (in places where only
4395 Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
4396 value or music function argument or music inside of music lists) to
4401 The @code{parser} and @code{location} arguments are mandatory, and
4402 are used in some advanced situations as described in the
4403 @q{Extending} manual (see @rextend{Music functions}). For
4404 substitution functions, just be sure to include them.
4406 The list of type predicates is also required. Some of the most
4407 common type predicates used in music functions are:
4411 cheap-list? @emph{(use instead of }@q{list?}@emph{ for faster processing)}
4423 For a list of available type predicates, see
4424 @ref{Predefined type predicates}. User-defined type predicates
4429 @ref{Predefined type predicates}.
4432 @rextend{Music functions}.
4435 @file{lily/music-scheme.cc},
4437 @file{scm/lily.scm}.
4440 @node Substitution function examples
4441 @subsection Substitution function examples
4443 This section introduces some substitution function examples.
4444 These are not intended to be exhaustive, but rather to demonstrate
4445 some of the possibilities of simple substitution functions.
4447 In the first example, a function is defined that simplifies
4448 setting the padding of a TextScript:
4450 @lilypond[quote,verbatim,ragged-right]
4452 #(define-music-function
4453 (parser location padding)
4456 \once \override TextScript.padding = #padding
4460 c4^"piu mosso" b a b
4462 c4^"piu mosso" d e f
4464 c4^"piu mosso" fis a g
4468 In addition to numbers, we can use music expressions such
4469 as notes for arguments to music functions:
4471 @lilypond[quote,verbatim,ragged-right]
4473 #(define-music-function
4474 (parser location note)
4477 \tweak NoteHead.stencil #ly:text-interface::print
4478 \tweak NoteHead.text
4479 \markup \musicglyph #"custodes.mensural.u0"
4480 \tweak Stem.stencil ##f
4484 \relative c' { c4 d e f \custosNote g }
4487 Substitution functions with multiple arguments can be defined:
4489 @lilypond[quote,verbatim,ragged-right]
4491 #(define-music-function
4492 (parser location padding tempotext)
4495 \once \override Score.MetronomeMark.padding = #padding
4496 \tempo \markup { \bold #tempotext }
4500 \tempo \markup { "Low tempo" }
4502 \tempoPadded #4.0 "High tempo"
4507 @c TODO: add appropriate @@ref's here.