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 of
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}, we want commands that work
1154 on (existing) @code{Voice}s to remain working. This is achieved by
1155 giving the new context an alias @code{Voice},
1161 The context will print notes and instructive texts, so we need to add
1162 the engravers which provide this functionality,
1165 \consists "Note_heads_engraver"
1166 \consists "Text_engraver"
1169 but we only need this on the center line,
1172 \consists "Pitch_squash_engraver"
1173 squashedPosition = #0
1176 The @rinternals{Pitch_squash_engraver} modifies note heads (created
1177 by @rinternals{Note_heads_engraver}) and sets their vertical
1178 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
1181 The notes look like a slash, and have no stem,
1184 \override NoteHead.style = #'slash
1185 \override Stem.transparent = ##t
1186 \override Flag.transparent = ##t
1189 All these plug-ins have to cooperate, and this is achieved with a
1190 special plug-in, which must be marked with the keyword @code{\type}.
1191 This should always be @code{Engraver_group}.
1194 \type "Engraver_group"
1197 Put together, we get
1202 \type "Engraver_group"
1203 \consists "Note_heads_engraver"
1204 \consists "Text_engraver"
1205 \consists "Pitch_squash_engraver"
1206 squashedPosition = #0
1207 \override NoteHead.style = #'slash
1208 \override Stem.transparent = ##t
1209 \override Flag.transparent = ##t
1215 Contexts form hierarchies. We want to hang the @code{ImproVoice}
1216 under @code{Staff}, just like normal @code{Voice}s. Therefore, we
1217 modify the @code{Staff} definition with the @code{\accepts}
1228 The opposite of @code{\accepts} is @code{\denies},
1229 which is sometimes needed when reusing existing context definitions.
1231 Putting both into a @code{\layout} block, like
1241 \accepts "ImproVoice"
1246 Then the output at the start of this subsection can be entered as
1254 c c_"while playing :)"
1261 @node Context layout order
1262 @subsection Context layout order
1264 @cindex contexts, layout order
1268 Contexts are normally positioned in a system from top to bottom
1269 in the order in which they are encountered in the input file. When
1270 contexts are nested, the outer context will include inner nested
1271 contexts as specified in the input file, provided the inner contexts
1272 are included in the outer context's @qq{accepts} list. Nested
1273 contexts which are not included in the outer context's @qq{accepts}
1274 list will be repositioned below the outer context rather than nested
1277 The @qq{accepts} list of a context can be changed with the
1278 @code{\accepts} and @code{\denies} commands. @code{\accepts} adds a
1279 context to the @qq{accepts} list and @code{\denies} removes a context
1280 from the list. For example, it would not normally be desirable for
1281 chord names to be nested within a @code{Staff} context, so the
1282 @code{ChordNames} context is not included by default in the @qq{accepts}
1283 list of the @code{Staff} context, but if this were to be required it can
1286 @lilypond[verbatim,quote]
1290 \chords { d1:m7 b1:min7.5- }
1295 @lilypond[verbatim,quote]
1299 \chords { d1:m7 b1:min7.5- }
1304 \accepts "ChordNames"
1310 @code{\denies} is mainly used when a new context is being based on
1311 another, but the required nesting differs. For example, the
1312 @code{VaticanaStaff} context is based on the @code{Staff} context, but
1313 with the @code{VaticanaVoice} context substituted for the @code{Voice}
1314 context in the @qq{accepts} list.
1316 @cindex contexts, implicit
1317 @cindex implicit contexts
1318 @funindex \defaultchild
1320 Note that a context will be silently created implicitly if a
1321 command is encountered when there is no suitable context available
1324 Within a context definition, the type of subcontext to be
1325 implicitly created is specified using @code{\defaultchild}. A
1326 number of music events require a @samp{Bottom} context: when such
1327 an event is encountered, subcontexts are created recursively until
1328 reaching a context with no @samp{defaultchild} setting.
1330 Implicit context creation can at times give rise to unexpected new
1331 staves or scores. Using @code{\new} to create contexts explicitly
1332 avoids those problems.
1334 @cindex alignAboveContext
1335 @cindex alignBelowContext
1336 @funindex alignAboveContext
1337 @funindex alignBelowContext
1339 Sometimes a context is required to exist for just a brief period, a
1340 good example being the staff context for an ossia. This is usually
1341 achieved by introducing the context definition at the appropriate
1342 place in parallel with corresponding section of the main music.
1343 By default, the temporary context will be placed below all the
1344 existing contexts. To reposition it above the context called
1345 @qq{main}, it should be defined like this:
1348 @code{\new Staff \with @{ alignAboveContext = #"main" @} }
1351 A similar situation arises when positioning a temporary lyrics
1352 context within a multi-staved layout such as a @code{ChoirStaff},
1353 for example, when adding a second verse to a repeated section.
1354 By default the temporary lyrics context will be placed beneath the
1355 lower staves. By defining the temporary lyrics context with
1356 @code{alignBelowContext} it can be positioned correctly beneath
1357 the (named) lyrics context containing the first verse.
1359 Examples showing this repositioning of temporary contexts can be
1360 found elsewhere --- see @rlearning{Nesting music expressions},
1361 @ref{Modifying single staves} and @ref{Techniques specific to lyrics}.
1365 @rlearning{Nesting music expressions}.
1368 @ref{Modifying single staves},
1369 @ref{Techniques specific to lyrics}.
1372 @rprogram{An extra staff appears}.
1375 @file{ly/engraver-init.ly}.
1378 @node Explaining the Internals Reference
1379 @section Explaining the Internals Reference
1382 * Navigating the program reference::
1383 * Layout interfaces::
1384 * Determining the grob property::
1385 * Naming conventions::
1388 @node Navigating the program reference
1389 @subsection Navigating the program reference
1391 @c TODO remove this (it's in the LM)
1392 @c Replace with more factual directions
1394 Suppose we want to move the fingering indication in the fragment
1397 @lilypond[quote,relative=2,verbatim]
1403 If you visit the documentation on fingering instructions (in
1404 @ref{Fingering instructions}), you will notice:
1409 Internals Reference: @rinternals{Fingering}.
1414 @c outdated info; probably will delete.
1416 This fragment points to two parts of the program reference: a page
1417 on @code{FingeringEvent} and one on @code{Fingering}.
1419 The page on @code{FingeringEvent} describes the properties of the music
1420 expression for the input @w{@code{-2}}. The page contains many links
1421 forward. For example, it says
1424 Accepted by: @rinternals{Fingering_engraver},
1428 That link brings us to the documentation for the Engraver, the
1432 This engraver creates the following layout objects: @rinternals{Fingering}.
1435 In other words, once the @code{FingeringEvent}s are interpreted, the
1436 @code{Fingering_engraver} plug-in will process them.
1440 @c I can't figure out what this is supposed to mean. -gp
1442 The @code{Fingering_engraver} is also listed to create
1443 @rinternals{Fingering} objects,
1445 @c old info? it doesn't make any sense to me with our current docs.
1447 second bit of information listed under @b{See also} in the Notation
1452 The programmer's reference is available as an HTML document. It is
1453 highly recommended that you read it in HTML form, either online or
1454 by downloading the HTML documentation. This section will be much more
1455 difficult to understand if you are using the
1459 Follow the link to @rinternals{Fingering}. At the top of the
1463 Fingering objects are created by: @rinternals{Fingering_engraver} and
1464 @rinternals{New_fingering_engraver}.
1467 By following related links inside the program reference, we can follow the
1468 flow of information within the program:
1472 @item @rinternals{Fingering}:
1473 @rinternals{Fingering} objects are created by:
1474 @rinternals{Fingering_engraver}
1476 @item @rinternals{Fingering_engraver}:
1477 Music types accepted: @rinternals{fingering-event}
1479 @item @rinternals{fingering-event}:
1480 Music event type @code{fingering-event} is in Music expressions named
1481 @rinternals{FingeringEvent}
1484 This path goes against the flow of information in the program: it
1485 starts from the output, and ends at the input event. You could
1486 also start at an input event, and read with the flow of
1487 information, eventually ending up at the output object(s).
1489 The program reference can also be browsed like a normal document. It
1490 contains chapters on
1492 @rinternals{Music definitions},
1495 @code{Music definitions}
1497 on @rinternals{Translation}, and the @rinternals{Backend}. Every
1498 chapter lists all the definitions used and all properties that may be
1502 @node Layout interfaces
1503 @subsection Layout interfaces
1505 @cindex interface, layout
1506 @cindex layout interface
1509 The HTML page that we found in the previous section describes the
1510 layout object called @rinternals{Fingering}. Such an object is a
1511 symbol within the score. It has properties that store numbers (like
1512 thicknesses and directions), but also pointers to related objects. A
1513 layout object is also called a @emph{Grob}, which is short for Graphical
1514 Object. For more details about Grobs, see @rinternals{grob-interface}.
1516 The page for @code{Fingering} lists the definitions for the
1517 @code{Fingering} object. For example, the page says
1520 @code{padding} (dimension, in staff space):
1526 which means that the number will be kept at a distance of at least 0.5
1530 Each layout object may have several functions as a notational or
1531 typographical element. For example, the Fingering object
1532 has the following aspects
1536 Its size is independent of the horizontal spacing, unlike slurs or beams.
1539 It is a piece of text. Granted, it is usually a very short text.
1542 That piece of text is typeset with a font, unlike slurs or beams.
1545 Horizontally, the center of the symbol should be aligned to the
1546 center of the note head.
1549 Vertically, the symbol is placed next to the note and the staff.
1552 The vertical position is also coordinated with other superscript
1553 and subscript symbols.
1556 Each of these aspects is captured in so-called @emph{interface}s,
1557 which are listed on the @rinternals{Fingering} page at the bottom
1560 This object supports the following interfaces:
1561 @rinternals{item-interface},
1562 @rinternals{self-alignment-interface},
1563 @rinternals{side-position-interface}, @rinternals{text-interface},
1564 @rinternals{text-script-interface}, @rinternals{font-interface},
1565 @rinternals{finger-interface}, and @rinternals{grob-interface}.
1568 Clicking any of the links will take you to the page of the respective
1569 object interface. Each interface has a number of properties. Some of
1570 them are not user-serviceable (@q{Internal properties}), but others
1573 We have been talking of @emph{the} @code{Fingering} object, but actually it
1574 does not amount to much. The initialization file (see
1575 @rlearning{Other sources of information})
1576 @file{scm/define-grobs.scm} shows the soul of the @q{object},
1581 (avoid-slur . around)
1582 (slur-padding . 0.2)
1583 (staff-padding . 0.5)
1584 (self-alignment-X . 0)
1585 (self-alignment-Y . 0)
1586 (script-priority . 100)
1587 (stencil . ,ly:text-interface::print)
1588 (direction . ,ly:script-interface::calc-direction)
1589 (font-encoding . fetaText)
1590 (font-size . -5) ; don't overlap when next to heads.
1591 (meta . ((class . Item)
1592 (interfaces . (finger-interface
1594 text-script-interface
1596 side-position-interface
1597 self-alignment-interface
1598 item-interface))))))
1602 As you can see, the @code{Fingering} object is nothing more than a
1603 bunch of variable settings, and the webpage in the Internals Reference
1604 is directly generated from this definition.
1607 @node Determining the grob property
1608 @subsection Determining the grob property
1610 @c TODO remove this (it's in the LM)
1611 @c Replace with more factual directions
1613 Recall that we wanted to change the position of the @b{2} in
1615 @lilypond[quote,relative=2,verbatim]
1621 Since the @b{2} is vertically positioned next to its note, we have to
1622 meddle with the interface associated with this positioning. This is
1623 done using @code{side-position-interface}. The page for this interface
1627 @code{side-position-interface}
1629 Position a victim object (this one) next to other objects (the
1630 support). The property @code{direction} signifies where to put the
1631 victim object relative to the support (left or right, up or down?)
1636 Below this description, the variable @code{padding} is described as
1641 (dimension, in staff space)
1643 Add this much extra space between objects that are next to each other.
1647 By increasing the value of @code{padding}, we can move the
1648 fingering away from the note head. The following command inserts
1649 3 staff spaces of white
1650 between the note and the fingering:
1652 \once \override Voice.Fingering.padding = #3
1655 Inserting this command before the Fingering object is created,
1656 i.e., before @code{c2}, yields the following result:
1658 @lilypond[quote,relative=2,verbatim]
1659 \once \override Voice.Fingering.padding = #3
1666 In this case, the context for this tweak is @code{Voice}. This
1667 fact can also be deduced from the program reference, for the page for
1668 the @rinternals{Fingering_engraver} plug-in says
1671 Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
1675 @node Naming conventions
1676 @subsection Naming conventions
1678 Another thing that is needed, is an overview of the various naming
1682 @item scheme functions: lowercase-with-hyphens (incl. one-word
1684 @item scheme functions: ly:plus-scheme-style
1685 @item music events, music classes and music properties:
1687 @item Grob interfaces: scheme-style
1688 @item backend properties: scheme-style (but X and Y!)
1689 @item contexts (and MusicExpressions and grobs): Capitalized or
1691 @item context properties: lowercaseFollowedByCamelCase
1693 Capitalized_followed_by_lowercase_and_with_underscores
1696 Questions to be answered:
1698 @item Which of these are conventions and which are rules?
1699 @item Which are rules of the underlying language, and which are
1703 @node Modifying properties
1704 @section Modifying properties
1706 @c TODO change the menu and subsection node names to use
1707 @c backslash once the new macro to handle the refs
1708 @c is available. Need to find and change all refs at
1709 @c the same time. -td
1712 * Overview of modifying properties::
1714 * The override command::
1715 * The tweak command::
1716 * set versus override::
1717 * Modifying alists::
1721 @node Overview of modifying properties
1722 @subsection Overview of modifying properties
1724 Each context is responsible for creating certain types of graphical
1725 objects. The settings used for printing these objects are also stored by
1726 context. By changing these settings, the appearance of objects can be
1729 There are two different kinds of properties stored in contexts:
1730 context properties and grob properties. Context properties are
1731 properties that apply to the context as a whole and control
1732 how the context itself is displayed. In contrast, grob properties
1733 apply to specific grob types that will be displayed in the context.
1735 The @code{\set} and @code{\unset} commands are used to change values
1736 for context properties. The @code{\override} and @code{\revert}
1737 commands are used to change values for grob properties.
1740 The syntax for this is
1743 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1746 Here @var{name} is the name of a graphical object, like
1747 @code{Stem} or @code{NoteHead}, and @var{property} is an internal
1748 variable of the formatting system (@q{grob property} or @q{layout
1749 property}). The latter is a symbol, so it must be quoted. The
1750 subsection @ref{Modifying properties}, explains what to fill in
1751 for @var{name}, @var{property}, and @var{value}. Here we only
1752 discuss the functionality of this command.
1757 \override Staff.Stem.thickness = #4.0
1761 makes stems thicker (the default is 1.3, with staff line thickness as a
1762 unit). Since the command specifies @code{Staff} as context, it only
1763 applies to the current staff. Other staves will keep their normal
1764 appearance. Here we see the command in action:
1766 @lilypond[quote,verbatim,relative=2]
1768 \override Staff.Stem.thickness = #4.0
1774 The @code{\override} command changes the definition of the @code{Stem}
1775 within the current @code{Staff}. After the command is interpreted
1776 all stems are thickened.
1778 Analogous to @code{\set}, the @var{context} argument may be left out,
1779 causing the default context @code{Voice} to be used. Adding
1780 @code{\once} applies the change during one timestep only.
1782 @lilypond[quote,verbatim,relative=2]
1784 \once \override Stem.thickness = #4.0
1789 The @code{\override} must be done before the object is
1790 started. Therefore, when altering @emph{Spanner} objects such as slurs
1791 or beams, the @code{\override} command must be executed at the moment
1792 when the object is created. In this example,
1794 @lilypond[quote,verbatim,relative=2]
1795 \override Slur.thickness = #3.0
1797 \override Beam.beam-thickness = #0.6
1802 the slur is fatter but the beam is not. This is because the command for
1803 @code{Beam} comes after the Beam is started, so it has no effect.
1805 Analogous to @code{\unset}, the @code{\revert} command for a context
1806 undoes an @code{\override} command; like with @code{\unset}, it only
1807 affects settings that were made in the same context. In other words, the
1808 @code{\revert} in the next example does not do anything.
1811 \override Voice.Stem.thickness = #4.0
1812 \revert Staff.Stem.thickness
1815 Some tweakable options are called @q{subproperties} and reside inside
1816 properties. To tweak those, use commands of the form
1818 @c leave this as a long long
1820 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1827 \override Stem.details.beamed-lengths = #'(4 4 3)
1833 Internals Reference:
1834 @rinternals{Backend},
1835 @rinternals{All layout objects},
1836 @rinternals{OverrideProperty},
1837 @rinternals{RevertProperty},
1838 @rinternals{PropertySet}.
1841 The back-end is not very strict in type-checking object properties.
1842 Cyclic references in Scheme values for properties can cause hangs
1843 or crashes, or both.
1846 @node The set command
1847 @subsection The @code{@bs{}set} command
1851 @cindex changing properties
1853 Each context has a set of @emph{properties}, variables contained
1854 in that context. Context properties are changed with the @code{\set}
1855 command, which has the following syntax:
1858 \set @var{context}.@var{property} = #@var{value}
1861 @var{value} is a Scheme object, which is why it must be preceded by
1862 the @code{#}@tie{}character.
1864 Contexts properties are usually named in
1865 @code{studlyCaps}. They mostly control the translation from
1866 music to notation, e.g. @code{localKeySignature} (for determining
1867 whether to print accidentals), or @code{measurePosition} (for
1868 determining when to print a bar line). Context properties can
1869 change value over time while interpreting a piece of music;
1870 @code{measurePosition} is an obvious example of
1871 this. Context properties are modified with @code{\set}.
1873 For example, multimeasure rests will be combined into a single bar
1874 if the context property @code{skipBars} is set to @code{#t}:
1876 @lilypond[quote,verbatim,relative=2]
1878 \set Score.skipBars = ##t
1882 If the @var{context} argument is left out, then the property will be
1883 set in the current bottom context (typically @code{ChordNames},
1884 @code{Voice}, @code{TabVoice}, or @code{Lyrics}).
1886 @lilypond[quote,verbatim,relative=2]
1887 \set Score.autoBeaming = ##f
1891 \set autoBeaming = ##t
1899 The change is applied @q{on-the-fly}, during the music, so that the
1900 setting only affects the second group of eighth notes.
1902 Note that the bottom-most context does not always contain the property
1903 that you wish to change -- for example, attempting to set the
1904 @code{skipBars} property of the default bottom context, in this case
1905 @code{Voice}, will have no effect, because skipBars is a property of
1906 the @code{Score} context.
1908 @lilypond[quote,verbatim,relative=2]
1914 Contexts are hierarchical, so if an enclosing context was specified, for
1915 example @code{Staff}, then the change would also apply to all
1916 @code{Voice}s in the current staff.
1920 The @code{\unset} command:
1923 \unset @var{context}.@var{property}
1927 is used to remove the definition of @var{property} from
1928 @var{context}. This command removes
1929 the definition only if it is set in @var{context}.
1930 Properties that have been set in enclosing contexts will
1931 not be altered by an unset in an enclosed context:
1933 @lilypond[quote,verbatim,relative=2]
1934 \set Score.autoBeaming = ##t
1939 \unset Score.autoBeaming
1947 Like @code{\set}, the @var{context} argument does not have to be
1948 specified for a bottom context, so the two statements
1951 \set Voice.autoBeaming = ##t
1952 \set autoBeaming = ##t
1956 are equivalent if the current bottom context is @code{Voice}.
1960 Preceding a @code{\set} command by @code{\once} makes the
1961 setting apply to only a single time-step:
1963 @lilypond[quote,verbatim,relative=2]
1965 \once \set fontSize = #4.7
1970 A full description of all available context properties is in the
1971 internals reference, see
1973 @rinternals{Tunable context properties}.
1976 Translation @expansion{} Tunable context properties.
1980 Internals Reference:
1981 @rinternals{Tunable context properties}.
1984 @node The override command
1985 @subsection The @code{\override} command
1987 @cindex grob properties
1988 @cindex properties, grob
1991 There is a special type of context property: the grob
1992 description. Grob descriptions are named in @code{StudlyCaps}
1993 (starting with capital letters). They contain the
1994 @q{default settings} for a particular kind of grob as an
1995 association list. See @file{scm/define-grobs.scm}
1996 to see the settings for each grob description. Grob descriptions
1997 are modified with @code{\override}.
1999 The syntax for the @code{\override} command is
2002 \override [@var{context}.]@var{GrobName}.@var{property} = #@var{value}
2005 For example, we can increase the thickness of a note stem by
2006 overriding the @code{thickness} property of the @code{Stem}
2009 @lilypond[quote,verbatim,relative=2]
2011 \override Voice.Stem.thickness = #3.0
2015 If no context is specified in an @code{\override}, the bottom
2018 @lilypond[quote,verbatim,relative=2]
2019 { \override Staff.Stem.thickness = #3.0
2023 \override Stem.thickness = #0.5
2032 Some tweakable options are called @q{subproperties} and reside inside
2033 properties. To tweak those, use commands in the form
2036 \override Stem.details.beamed-lengths = #'(4 4 3)
2039 or to modify the ends of spanners, use a form like these
2042 \override TextSpanner.bound-details.left.text = #"left text"
2043 \override TextSpanner.bound-details.right.text = #"right text"
2047 @cindex reverting overrides
2048 @cindex overrides, reverting
2050 The effects of @code{\override} can be undone by @code{\revert}.
2052 The syntax for the @code{\revert} command is
2055 \revert [@var{context}.]@var{GrobName}.@var{property}
2060 @lilypond[quote,verbatim,relative=2]
2062 \override Voice.Stem.thickness = #3.0
2064 \revert Voice.Stem.thickness
2068 The effects of @code{\override} and @code{\revert} apply to all
2069 grobs in the affected context from the current time forward:
2071 @lilypond[quote,verbatim,relative=2]
2076 \override Staff.Stem.thickness = #3.0
2080 \revert Staff.Stem.thickness
2088 @cindex overriding for only one moment
2090 @code{\once} can be used with @code{\override}
2091 to affect only the current time step:
2093 @lilypond[quote,verbatim,relative=2]
2097 \override Stem.thickness = #3.0
2101 \once \override Stem.thickness = #3.0
2110 Commands which change output generally look like
2113 \override Voice.Stem.thickness = #3.0
2117 To construct this tweak we must determine these bits of information:
2120 @item the context: here @code{Voice}.
2121 @item the layout object: here @code{Stem}.
2122 @item the layout property: here @code{thickness}.
2123 @item a sensible value: here @code{3.0}.
2126 @cindex internal documentation
2127 @cindex finding graphical objects
2128 @cindex graphical object descriptions
2131 @cindex internal documentation
2133 For many properties, regardless of the data type of the property, setting the
2134 property to false (@code{#f}) will result in turning it off, causing
2135 LilyPond to ignore that property entirely. This is particularly useful for
2136 turning off grob properties which may otherwise be causing problems.
2138 We demonstrate how to glean this information from the notation manual
2139 and the program reference.
2143 Internals Reference:
2144 @rinternals{Backend}
2147 @node The tweak command
2148 @subsection The @code{\tweak} command
2153 Changing grob properties
2154 with @code{\override} causes the changes to apply to all of the
2155 given grobs in the context at the moment the change applies.
2156 Sometimes, however, it is desirable to have changes apply to just
2157 one grob, rather than to all grobs in the affected context. This is
2158 accomplished with the @code{\tweak} command, which has the following
2162 \tweak [@var{layout-object}.]@var{grob-property} @var{value}
2165 Specifying @var{layout-object} is optional.
2166 The @code{\tweak} command applies to the music object that immediately
2167 follows @var{value} in the music stream.
2170 In some cases, it is possible to take a short-cut for tuning
2171 graphical objects. For objects that are created directly from
2172 an item in the input file, you can use the @code{\tweak} command.
2175 @lilypond[relative=2,verbatim,quote]
2180 \tweak duration-log #1
2189 The main use of the @code{\tweak} command is to modify just
2190 one of a number of notation elements which start at the same musical
2191 moment, like the notes of a chord, or tuplet brackets which start
2194 The @code{\tweak} command sets a property in the following object
2195 directly, without requiring the grob name or context to be
2196 specified. For this to work, it is necessary for the @code{\tweak}
2197 command to remain immediately adjacent to the object to which it is
2198 to apply after the input file has been converted to a music stream.
2199 This is often not the case, as many additional elements are inserted
2200 into the music stream implicitly. For example, when a note which is
2201 not part of a chord is processed, LilyPond implicitly inserts a
2202 @code{ChordEvent} event before the note, so separating the tweak
2203 from the note. However, if chord symbols are placed round the
2204 tweak and the note, the @code{\tweak} command comes after the
2205 @code{ChordEvent} in the music stream, so remaining adjacent to the
2206 note, and able to modify it.
2210 @lilypond[relative=2,verbatim,quote]
2211 <\tweak color #red c>4
2217 @lilypond[relative=2,verbatim,quote]
2218 \tweak color #red c4
2223 For an introduction to the syntax and uses of the tweak command
2224 see @rlearning{Tweaking methods}.
2226 When several similar items are placed at the same musical moment,
2227 the @code{\override} command cannot be used to modify just one of
2228 them -- this is where the @code{\tweak} command must be used.
2229 Items which may appear more than once at the same musical moment
2230 include the following:
2232 @c TODO expand to include any further uses of \tweak
2234 @item note heads of notes inside a chord
2235 @item articulation signs on a single note
2236 @item ties between notes in a chord
2237 @item tuplet brackets starting at the same time
2240 @c TODO add examples of these
2242 @cindex chord, modifying one note in
2244 In this example, the color of one note head and the type of another
2245 note head are modified within a single chord:
2247 @lilypond[relative=2,verbatim,quote]
2252 \tweak duration-log #1
2257 @code{\tweak} can be used to modify slurs:
2259 @lilypond[verbatim,quote,relative=1]
2260 c-\tweak thickness #5 ( d e f)
2264 For the @code{\tweak} command to work, it must
2265 remain immediately adjacent to the object to which it is
2266 to apply after the input file has been converted to a music stream.
2267 Tweaking a whole chord does not do anything since its music event
2268 only acts as a container, and all layout objects are created from events
2269 inside of the @code{EventChord}:
2271 @lilypond[relative=2,verbatim,quote]
2272 \tweak color #red c4
2273 \tweak color #red <c e>4
2274 <\tweak color #red c e>4
2277 The simple @code{\tweak} command cannot be used to modify any object
2278 that is not directly created from the input. In particular
2279 it will not affect stems, automatic
2280 beams or accidentals, since these are generated later by
2281 @code{NoteHead} layout objects rather than by music elements in the
2284 Such indirectly created layout objects can be tweaked using the form
2285 of the @code{\tweak} command in which the grob name is specified
2288 @lilypond[relative=2,verbatim,quote]
2289 \tweak Stem.color #red
2290 \tweak Beam.color #green c8 e
2291 <c e \tweak Accidental.font-size #-3 ges>4
2294 @code{\tweak} cannot be used to modify clefs or time
2295 signatures, since these become separated from any preceding
2296 @code{\tweak} command in the input stream by the automatic
2297 insertion of extra elements required to specify the context.
2299 Several @code{\tweak} commands may be placed before a
2300 notational element -- all affect it:
2302 @lilypond[verbatim,quote,relative=1]
2304 -\tweak style #'dashed-line
2305 -\tweak dash-fraction #0.2
2306 -\tweak thickness #3
2312 The music stream which is generated from a section of an input file,
2313 including any automatically inserted elements, may be examined,
2314 see @rextend{Displaying music expressions}. This may be helpful in
2315 determining what may be modified by a @code{\tweak} command, or
2316 in determining how to adjust the input to make a @code{\tweak}
2321 @rlearning{Tweaking methods}.
2324 @rextend{Displaying music expressions}.
2328 @cindex tweaking control points
2329 @cindex control points, tweaking
2331 The @code{\tweak} command cannot be used to modify the control
2332 points of just one of several ties in a chord, other than the first
2333 one encountered in the input file.
2335 @node set versus override
2336 @subsection @code{\set} vs. @code{\override}
2338 @c TODO -- This section is probably unnecessary now.
2341 We have seen two methods of changing properties: @code{\set} and
2342 @code{\override}. There are actually two different kinds of
2345 @code{fontSize} is a special property: it is equivalent to
2346 entering @code{\override ... #'font-size} for all pertinent
2347 objects. Since this is a common change, the special
2348 property (modified with @code{\set}) was created.
2353 @node Modifying alists
2354 @subsection Modifying alists
2356 Some user-configurable properties are internally represented as
2357 @emph{alists} (association lists), which store pairs of
2358 @emph{keys} and @emph{values}. The structure of an alist is:
2361 '((@var{key1} . @var{value1})
2362 (@var{key2} . @var{value2})
2363 (@var{key3} . @var{value3})
2367 If an alist is a grob property or @code{\paper} variable, its keys
2368 can be modified individually without affecting other keys.
2370 For example, to reduce the space between adjacent staves in a
2371 staff-group, use the @code{staff-staff-spacing} property of the
2372 @code{StaffGrouper} grob. The property is an alist with four
2373 keys: @code{basic-distance}, @code{minimum-distance},
2374 @code{padding}, and @code{stretchability}. The standard settings
2375 for this property are listed in the @qq{Backend} section of the
2376 Internals Reference (see @rinternals{StaffGrouper}):
2379 '((basic-distance . 9)
2380 (minimum-distance . 7)
2382 (stretchability . 5))
2385 One way to bring the staves closer together is by reducing the
2386 value of the @code{basic-distance} key (@code{9}) to match the
2387 value of @code{minimum-distance} (@code{7}). To modify a single
2388 key individually, use a @emph{nested declaration}:
2390 @lilypond[quote,verbatim]
2391 % default space between staves
2393 \new Staff { \clef treble c''1 }
2394 \new Staff { \clef bass c1 }
2397 % reduced space between staves
2398 \new PianoStaff \with {
2399 % this is the nested declaration
2400 \override StaffGrouper.staff-staff-spacing.basic-distance = #7
2402 \new Staff { \clef treble c''1 }
2403 \new Staff { \clef bass c1 }
2407 Using a nested declaration will update the specified key (such as
2408 @code{basic-distance} in the above example) without altering any
2409 other keys already set for the same property.
2411 Now suppose we want the staves to be as close as possible without
2412 overlapping. The simplest way to do this is to set all four alist
2413 keys to zero. However, it is not necessary to enter four nested
2414 declarations, one for each key. Instead, the property can be
2415 completely re-defined with one declaration, as an alist:
2417 @lilypond[quote,verbatim]
2418 \new PianoStaff \with {
2419 \override StaffGrouper.staff-staff-spacing =
2420 #'((basic-distance . 0)
2421 (minimum-distance . 0)
2423 (stretchability . 0))
2425 \new Staff { \clef treble c''1 }
2426 \new Staff { \clef bass c1 }
2430 Note that any keys not explicitly listed in the alist definition
2431 will be reset to their @emph{default-when-unset} values. In the
2432 case of @code{staff-staff-spacing}, any unset key-values would be
2433 reset to zero (except @code{stretchability}, which takes the value
2434 of @code{basic-distance} when unset). Thus the following two
2435 declarations are equivalent:
2438 \override StaffGrouper.staff-staff-spacing =
2439 #'((basic-distance . 7))
2441 \override StaffGrouper.staff-staff-spacing =
2442 #'((basic-distance . 7)
2443 (minimum-distance . 0)
2445 (stretchability . 7))
2448 One (possibly unintended) consequence of this is the removal of
2449 any standard settings that are set in an initialization file and
2450 loaded each time an input file is compiled. In the above example,
2451 the standard settings for @code{padding} and
2452 @code{minimum-distance} (defined in @file{scm/define-grobs.scm})
2453 are reset to their default-when-unset values (zero for both keys).
2454 Defining a property or variable as an alist (of any size) will
2455 always reset all unset key-values to their default-when-unset
2456 values. Unless this is the intended result, it is safer to update
2457 key-values individually with a nested declaration.
2459 @warning{Nested declarations will not work for context property
2460 alists (such as @code{beamExceptions}, @code{keySignature},
2461 @code{timeSignatureSettings}, etc.). These properties can only be
2462 modified by completely re-defining them as alists.}
2465 @node Useful concepts and properties
2466 @section Useful concepts and properties
2471 * Direction and placement::
2472 * Distances and measurements::
2473 * Staff symbol properties::
2475 * Visibility of objects::
2477 * Rotating objects::
2481 @subsection Input modes
2483 The way in which the notation contained within an input file is
2484 interpreted is determined by the current input mode.
2488 This is activated with the @code{\chordmode} command, and causes
2489 input to be interpreted with the syntax of chord notation, see
2490 @ref{Chord notation}. Chords are rendered as notes on a staff.
2492 Chord mode is also activated with the @code{\chords} command.
2493 This also creates a new @code{ChordNames} context and
2494 causes the following input to be interpreted with the syntax of
2495 chord notation and rendered as chord names in the @code{ChordNames}
2496 context, see @ref{Printing chord names}.
2500 This is activated with the @code{\drummode} command, and causes
2501 input to be interpreted with the syntax of drum notation, see
2502 @ref{Basic percussion notation}.
2504 Drum mode is also activated with the @code{\drums} command.
2505 This also creates a new @code{DrumStaff} context and causes the
2506 following input to be interpreted with the syntax of drum notation
2507 and rendered as drum symbols on a drum staff, see @ref{Basic
2508 percussion notation}.
2510 @strong{Figure mode}
2512 This is activated with the @code{\figuremode} command, and causes
2513 input to be interpreted with the syntax of figured bass, see
2514 @ref{Entering figured bass}.
2516 Figure mode is also activated with the @code{\figures} command.
2517 This also creates a new @code{FiguredBass} context and causes the
2518 following input to be interpreted with the figured bass syntax
2519 and rendered as figured bass symbols in the @code{FiguredBass}
2520 context, see @ref{Introduction to figured bass}.
2522 @strong{Fret and tab modes}
2524 There are no special input modes for entering fret and tab symbols.
2526 To create tab diagrams, enter notes or chords in note mode and
2527 render them in a @code{TabStaff} context, see
2528 @ref{Default tablatures}.
2530 To create fret diagrams above a staff, you have two choices.
2531 You can either use the @code{FretBoards} context (see
2532 @ref{Automatic fret diagrams} or you can enter them as a markup
2533 above the notes using the @code{\fret-diagram} command (see
2534 @ref{Fret diagram markups}).
2536 @strong{Lyrics mode}
2538 This is activated with the @code{\lyricmode} command, and causes
2539 input to be interpreted as lyric syllables with optional durations
2540 and associated lyric modifiers, see @ref{Vocal music}.
2542 Lyric mode is also activated with the @code{\addlyrics} command.
2543 This also creates a new @code{Lyrics} context and an implicit
2544 @code{\lyricsto} command which associates the following lyrics
2545 with the preceding music.
2547 @strong{Markup mode}
2549 This is activated with the @code{\markup} command, and causes
2550 input to be interpreted with the syntax of markup, see
2551 @ref{Text markup commands}.
2553 @c silly work-around for texinfo broken-ness
2554 @c (@strong{Note...} causes a spurious cross-reference in Info)
2557 This is the default mode or it may be activated with the
2558 @code{\notemode} command. Input is interpreted as pitches,
2559 durations, markup, etc and typeset as musical notation on a staff.
2561 It is not normally necessary to specify note mode explicitly, but
2562 it may be useful to do so in certain situations, for example if you
2563 are in lyric mode, chord mode or any other mode and want to insert
2564 something that only can be done with note mode syntax.
2566 For example, to indicate dynamic markings for the verses of a
2567 choral pieces it is necessary to enter note mode to interpret
2570 @lilypond[verbatim,relative=2,quote]
2573 \notemode{\set stanza = \markup{ \dynamic f 1. } }
2577 \notemode{\set stanza = \markup{ \dynamic p 2. } }
2584 @node Direction and placement
2585 @subsection Direction and placement
2587 In typesetting music the direction and placement of many items is
2588 a matter of choice. For example, the stems of notes can
2589 be directed up or down; lyrics, dynamics, and other expressive
2590 marks may be placed above or below the staff; text may be aligned
2591 left, right or center; etc. Most of these choices may be left to
2592 be determined automatically by LilyPond, but in some cases it may
2593 be desirable to force a particular direction or placement.
2596 * Articulation direction indicators::
2597 * The direction property::
2600 @node Articulation direction indicators
2601 @unnumberedsubsubsec Articulation direction indicators
2603 By default some directions are always up or always down (e.g.
2604 dynamics or fermata), while other things can alternate between
2605 up or down based on the stem direction (like slurs or accents).
2607 @c TODO Add table showing these
2609 The default action may be overridden by prefixing the articulation
2610 by a @emph{direction indicator}. Three direction indicators are
2611 available: @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down})
2612 and @code{-} (meaning @qq{use default direction}). The direction
2613 indicator can usually be omitted, in which case @code{-} is assumed,
2614 but a direction indicator is @strong{always} required before
2617 @item @code{\tweak} commands
2618 @item @code{\markup} commands
2619 @item @code{\tag} commands
2620 @item string markups, e.g. -"string"
2621 @item fingering instructions, e.g. @w{@code{-1}}
2622 @item articulation shortcuts, e.g. @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
2625 Direction indicators affect only the next note:
2627 @lilypond[verbatim,quote,relative=2]
2634 @node The direction property
2635 @unnumberedsubsubsec The direction property
2637 The position or direction of many layout objects is controlled by the
2638 @code{direction} property.
2640 The value of the @code{direction} property may be set to @code{1},
2641 meaning @qq{up} or @qq{above}, or to @w{@code{-1}}, meaning @qq{down} or
2642 @qq{below}. The symbols @code{UP} and @code{DOWN} may be used instead
2643 of @code{1} and @w{@code{-1}} respectively. The default direction may
2644 be specified by setting @code{direction} to @code{0} or @code{CENTER}.
2645 Alternatively, in many cases predefined commands exist to specify the
2646 direction. These are of the form
2649 @code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
2653 where @code{\xxxNeutral} means @qq{use the default} direction.
2654 See @rlearning{Within-staff objects}.
2656 In a few cases, arpeggio for example, the value of the @code{direction}
2657 property can specify whether the object is to be placed to the right or
2658 left of the parent. In this case @w{@code{-1}} or @code{LEFT} means
2659 @qq{to the left} and @code{1} or @code{RIGHT} means @qq{to the right}.
2660 @code{0} or @code{CENTER} means @qq{use the default} direction.
2663 These all have side-axis set to #X
2664 AmbitusAccidental - direction has no effect
2666 StanzaNumber - not tried
2667 TrillPitchAccidental - not tried
2668 TrillPitchGroup - not tried
2671 These indications affect all notes until they are canceled.
2673 @lilypond[verbatim,quote,relative=2]
2682 In polyphonic music, it is generally better to specify an explicit
2683 @code{voice} than change an object's direction. For more information.
2684 See @ref{Multiple voices}.
2688 @rlearning{Within-staff objects}.
2691 @ref{Multiple voices}.
2694 @node Distances and measurements
2695 @subsection Distances and measurements
2697 @cindex distances, absolute
2698 @cindex distances, scaled
2705 Distances in LilyPond are of two types: absolute and scaled.
2707 Absolute distances are used for specifying margins, indents, and
2708 other page layout details, and are by default specified in
2709 millimeters. Distances may be specified in other units by
2710 following the quantity by @code{\mm}, @code{\cm},
2711 @code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27 of
2712 an inch). Page layout distances can also be specified in scalable
2713 units (see the following paragraph) by appending
2714 @code{\staff-space} to the quantity. Page layout is described in
2715 detail in @ref{Page layout}.
2717 Scaled distances are always specified in units of the staff-space
2718 or, rarely, the half staff-space. The staff-space is the distance
2719 between two adjacent staff lines. The default value can be changed
2720 globally by setting the global staff size, or it can be overridden
2721 locally by changing the @code{staff-space} property of
2722 @code{StaffSymbol}. Scaled distances automatically scale with any
2723 change to the either the global staff size or the
2724 @code{staff-space} property of @code{StaffSymbol}, but fonts scale
2725 automatically only with changes to the global staff size.
2726 The global staff size thus enables the overall size of a rendered
2727 score to be easily varied. For the methods of setting the global
2728 staff size see @ref{Setting the staff size}.
2732 If just a section of a score needs to be rendered to a different
2733 scale, for example an ossia section or a footnote, the global staff
2734 size cannot simply be changed as this would affect the entire score.
2735 In such cases the change in size is made by overriding both the
2736 @code{staff-space} property of @code{StaffSymbol} and the size of
2737 the fonts. A Scheme function, @code{magstep}, is available to
2738 convert from a font size change to the equivalent change in
2739 @code{staff-space}. For an explanation and an example of its use,
2740 see @rlearning{Length and thickness of objects}.
2744 @rlearning{Length and thickness of objects}.
2748 @ref{Setting the staff size}.
2751 @node Staff symbol properties
2752 @subsection Staff symbol properties
2754 @cindex adjusting staff symbol
2755 @cindex drawing staff symbol
2756 @cindex staff symbol, setting of
2758 @c TODO Extend or remove this section. See also NR 1.6.2 Staff symbol
2759 @c Need to think of uses for these properties. Eg 'line-positions
2760 @c is used in a snippet to thicken centre line.
2761 @c If retained, add @ref to here in 1.6.2 -td
2763 The vertical position of staff lines and the number of staff lines
2764 can be defined at the same time. As the following example shows,
2765 note positions are not influenced by the staff line positions.
2767 @warning{The @code{'line-positions} property overrides the
2768 @code{'line-count} property. The number of staff lines is
2769 implicitly defined by the number of elements in the list of values
2770 for @code{'line-positions}.}
2772 @lilypond[verbatim,quote,relative=1]
2774 \override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7)
2779 The width of a staff can be modified. The units are staff
2780 spaces. The spacing of objects inside the staff is not affected by
2783 @lilypond[verbatim,quote,relative=1]
2785 \override StaffSymbol.width = #23
2792 @subsection Spanners
2794 Many objects of musical notation extend over several notes or even
2795 several bars. Examples are slurs, beams, tuplet brackets, volta
2796 repeat brackets, crescendi, trills, and glissandi. Such objects
2797 are collectively called @qq{spanners}, and have special properties to control
2798 their appearance and behaviour. Some of these properties are common
2799 to all spanners; others are restricted to a sub-set of the spanners.
2801 All spanners support the @code{spanner-interface}. A few, essentially
2802 those that draw a straight line between the two objects, support in
2803 addition the @code{line-spanner-interface}.
2806 * Using the spanner-interface::
2807 * Using the line-spanner-interface::
2810 @node Using the spanner-interface
2811 @unnumberedsubsubsec Using the @code{spanner-interface}
2813 This interface provides two properties that apply to several spanners.
2815 @subsubsubheading The @code{minimum-length} property
2817 The minimum length of the spanner is specified by the
2818 @code{minimum-length} property. Increasing this usually has the
2819 necessary effect of increasing the spacing of the notes between the
2820 two end points. However, this override has no effect on
2821 many spanners, as their length is determined by other considerations.
2822 A few examples where it is effective are shown below.
2832 Works as long as callback is made:
2836 Works not at all for:
2845 @lilypond[verbatim,quote,relative=2]
2848 % increase the length of the tie
2849 -\tweak minimum-length #5
2853 @lilypond[verbatim,quote,relative=2]
2855 \compressFullBarRests
2857 % increase the length of the rest bar
2858 \once \override MultiMeasureRest.minimum-length = #20
2863 @lilypond[verbatim,quote,relative=2]
2865 % increase the length of the hairpin
2866 \override Hairpin.minimum-length = #20
2870 This override can also be used to increase the length of slurs and
2873 @lilypond[verbatim,quote,relative=2]
2876 -\tweak minimum-length #5
2881 -\tweak minimum-length #5
2885 For some layout objects, the @code{minimum-length} property becomes
2886 effective only if the @code{set-spacing-rods} procedure is called
2887 explicitly. To do this, the @code{springs-and-rods} property should
2888 be set to @code{ly:spanner::set-spacing-rods}. For example,
2889 the minimum length of a glissando has no effect unless the
2890 @code{springs-and-rods} property is set:
2892 @lilypond[verbatim,quote,relative=1]
2896 % not effective alone
2897 \once \override Glissando.minimum-length = #20
2900 % effective only when both overrides are present
2901 \once \override Glissando.minimum-length = #20
2902 \once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods
2906 The same is true of the @code{Beam} object:
2908 @lilypond[verbatim,quote,relative=1]
2909 % not effective alone
2910 \once \override Beam.minimum-length = #20
2913 % effective only when both overrides are present
2914 \once \override Beam.minimum-length = #20
2915 \once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods
2919 @subsubsubheading The @code{to-barline} property
2921 The second useful property of the @code{spanner-interface} is
2922 @code{to-barline}. By default this is true, causing hairpins and
2923 other spanners which are terminated on the first note of a measure to
2924 end instead on the immediately preceding bar line. If set to false,
2925 the spanner will extend beyond the bar line and end on the note
2928 @lilypond[verbatim,quote,relative=2]
2929 a \< a a a a \! a a a \break
2930 \override Hairpin.to-barline = ##f
2931 a \< a a a a \! a a a
2934 This property is not effective for all spanners. For example,
2935 setting it to @code{#t} has no effect on slurs or phrasing slurs
2936 or on other spanners for which terminating on the bar line would
2939 @node Using the line-spanner-interface
2940 @unnumberedsubsubsec Using the @code{line-spanner-interface}
2942 Objects which support the @code{line-spanner-interface} include
2945 @item @code{DynamicTextSpanner}
2946 @item @code{Glissando}
2947 @item @code{TextSpanner}
2948 @item @code{TrillSpanner}
2949 @item @code{VoiceFollower}
2952 The routine responsible for drawing the stencils for these spanners is
2953 @code{ly:line-interface::print}. This routine determines the
2954 exact location of the two end points and draws a line
2955 between them, in the style requested. The locations of the two
2956 end points of the spanner are computed on-the-fly, but it is
2957 possible to override their Y-coordinates. The
2958 properties which need to be specified are nested
2959 two levels down within the property hierarchy, but the syntax of
2960 the @code{\override} command is quite simple:
2962 @lilypond[relative=2,quote,verbatim]
2964 \once \override Glissando.bound-details.left.Y = #3
2965 \once \override Glissando.bound-details.right.Y = #-2
2969 The units for the @code{Y} property are @code{staff-space}s,
2970 with the center line of the staff being the zero point.
2971 For the glissando, this is the value for @code{Y} at the
2972 X-coordinate corresponding to the center point of each note head,
2973 if the line is imagined to be extended to there.
2975 If @code{Y} is not set, the value is computed from the vertical
2976 position of the corresponding attachment point of the spanner.
2978 In case of a line break, the values for the end points are
2979 specified by the @code{left-broken} and @code{right-broken}
2980 sub-lists of @code{bound-details}. For example:
2982 @lilypond[relative=2,ragged-right,verbatim,quote]
2983 \override Glissando.breakable = ##t
2984 \override Glissando.bound-details.right-broken.Y = #-3
2985 c1 \glissando \break
2990 A number of further properties of the @code{left} and
2991 @code{right} sub-lists of the @code{bound-details} property
2992 may be modified in the same way as @code{Y}:
2996 This sets the Y-coordinate of the end point, in @code{staff-space}s
2997 offset from the staff center line. By default, it is the center of
2998 the bound object, so a glissando points to the vertical center of
3001 For horizontal spanners, such as text spanners and trill spanners,
3002 it is hardcoded to 0.
3005 This determines where the line starts and ends in the X-direction,
3006 relative to the bound object. So, a value of @w{@code{-1}} (or
3007 @code{LEFT}) makes the line start/end at the left side of the note
3008 head it is attached to.
3011 This is the absolute X-coordinate of the end point. It is usually
3012 computed on the fly, and overriding it has little useful effect.
3015 Line spanners may have symbols at the beginning or end, which is
3016 contained in this sub-property. This is for internal use; it is
3017 recommended that @code{text} be used instead.
3020 This is a markup that is evaluated to yield the stencil. It is used
3021 to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
3023 @lilypond[quote,ragged-right,relative=2,verbatim]
3024 \override TextSpanner.bound-details.left.text
3025 = \markup { \small \bold Slower }
3026 c2\startTextSpan b c a\stopTextSpan
3029 @item stencil-align-dir-y
3030 @item stencil-offset
3031 Without setting one of these, the stencil is simply put at the
3032 end-point, centered on the line, as defined by the @code{X} and
3033 @code{Y} sub-properties. Setting either @code{stencil-align-dir-y}
3034 or @code{stencil-offset} will move the symbol at the edge vertically
3035 relative to the end point of the line:
3037 @lilypond[relative=1,quote,verbatim]
3038 \override TextSpanner.bound-details.left.stencil-align-dir-y = #-2
3039 \override TextSpanner.bound-details.right.stencil-align-dir-y = #UP
3041 \override TextSpanner.bound-details.left.text = #"ggg"
3042 \override TextSpanner.bound-details.right.text = #"hhh"
3043 c4^\startTextSpan c c c \stopTextSpan
3046 Note that negative values move the text @emph{up}, contrary to the
3047 effect that might be expected, as a value of @w{@code{-1}} or
3048 @code{DOWN} means align the @emph{bottom} edge of the text with
3049 the spanner line. A value of @code{1} or @code{UP} aligns
3050 the top edge of the text with the spanner line.
3053 Setting this sub-property to @code{#t} produces an arrowhead at the
3057 This sub-property controls the space between the specified
3058 end point of the line and the actual end. Without padding, a
3059 glissando would start and end in the center of each note head.
3063 The music function @code{\endSpanners} terminates the spanner
3064 which starts on the immediately following note prematurely. It
3065 is terminated after exactly one note, or at the following bar line
3066 if @code{to-barline} is true and a bar line occurs before the next
3069 @lilypond[verbatim,quote,ragged-right,relative=2]
3071 c2 \startTextSpan c2 c2
3076 When using @code{\endSpanners} it is not necessary to close
3077 \startTextSpan with \stopTextSpan, nor is it necessary to close
3078 hairpins with @code{\!}.
3081 Internals Reference:
3082 @rinternals{TextSpanner},
3083 @rinternals{Glissando},
3084 @rinternals{VoiceFollower},
3085 @rinternals{TrillSpanner},
3086 @rinternals{line-spanner-interface}.
3089 @node Visibility of objects
3090 @subsection Visibility of objects
3092 @cindex objects, visibility of
3093 @cindex grobs, visibility of
3094 @cindex visibility of objects
3096 There are four main ways in which the visibility of layout objects
3097 can be controlled: their stencil can be removed, they can be made
3098 transparent, they can be colored white, or their
3099 @code{break-visibility} property can be overridden. The first
3100 three apply to all layout objects; the last to just a few -- the
3101 @emph{breakable} objects. The Learning Manual introduces these
3102 four techniques, see @rlearning{Visibility and color of objects}.
3104 There are also a few other techniques which are specific to
3105 certain layout objects. These are covered under Special
3109 * Removing the stencil::
3110 * Making objects transparent::
3111 * Painting objects white::
3112 * Using break-visibility::
3113 * Special considerations::
3117 @node Removing the stencil
3118 @unnumberedsubsubsec Removing the stencil
3120 @cindex stencil, removing
3122 Every layout object has a stencil property. By default this is set
3123 to the specific function which draws that object. If this property
3124 is overridden to @code{#f} no function will be called and the object
3125 will not be drawn. The default action can be recovered with
3128 @lilypond[quote,verbatim,relative=1]
3130 \override Score.BarLine.stencil = ##f
3132 \revert Score.BarLine.stencil
3136 @node Making objects transparent
3137 @unnumberedsubsubsec Making objects transparent
3139 @cindex transparent, making objects
3141 Every layout object has a transparent property which by default is
3142 set to @code{#f}. If set to @code{#t} the object still occupies
3143 space but is made invisible.
3145 @lilypond[quote,verbatim,relative=2]
3147 \once \override NoteHead.transparent = ##t
3151 @node Painting objects white
3152 @unnumberedsubsubsec Painting objects white
3154 @cindex objects, coloring
3155 @cindex coloring objects
3157 @cindex printing order
3158 @cindex overwriting objects
3159 @cindex objects, overwriting
3160 @cindex grobs, overwriting
3162 Every layout object has a color property which by default is set
3163 to @code{black}. If this is overridden to @code{white} the object
3164 will be indistinguishable from the white background. However,
3165 if the object crosses other objects the color of the crossing
3166 points will be determined by the order in which they are drawn,
3167 and this may leave a ghostly image of the white object, as shown
3170 @lilypond[quote,verbatim,relative=2]
3171 \override Staff.Clef.color = #white
3175 This may be avoided by changing the order of printing the objects.
3176 All layout objects have a @code{layer} property which should be set
3177 to an integer. Objects with the lowest value of @code{layer} are
3178 drawn first, then objects with progressively higher values are drawn,
3179 so objects with higher values overwrite objects with lower values.
3180 By default most objects are assigned a @code{layer} value of
3181 @code{1}, although a few objects, including @code{StaffSymbol} and
3182 @code{BarLine}, are assigned a value of @code{0}. The order of
3183 printing objects with the same value of @code{layer} is indeterminate.
3185 In the example above the white clef, with a default @code{layer}
3186 value of @code{1}, is drawn after the staff lines (default
3187 @code{layer} value @code{0}), so overwriting them. To change this,
3188 the @code{Clef} object must be given in a lower value of
3189 @code{layer}, say @w{@code{-1}}, so that it is drawn earlier:
3191 @lilypond[quote,verbatim,relative=2]
3192 \override Staff.Clef.color = #white
3193 \override Staff.Clef.layer = #-1
3197 @node Using break-visibility
3198 @unnumberedsubsubsec Using break-visibility
3200 @c TODO Add making other objects breakable
3202 @cindex break-visibility
3204 Most layout objects are printed only once, but some like
3205 bar lines, clefs, time signatures and key signatures, may need
3206 to be printed twice when a line break occurs -- once at the end
3207 of the line and again at the start of the next line. Such
3208 objects are called @emph{breakable}, and have a property, the
3209 @code{break-visibility} property to control their visibility
3210 at the three positions in which they may appear -- at the
3211 start of a line, within a line if they are changed, and at the
3212 end of a line if a change takes place there.
3214 For example, the time signature
3215 by default will be printed at the start of the first line, but
3216 nowhere else unless it changes, when it will be printed at the
3217 point at which the change occurs. If this change occurs at the
3218 end of a line the new time signature will be printed at the start
3219 of the next line and a cautionary time signature will be printed
3220 at the end of the previous line as well.
3222 This behaviour is controlled by the @code{break-visibility}
3223 property, which is explained in
3224 @c Leave this ref on a newline - formats incorrectly otherwise -td
3225 @rlearning{Visibility and color of objects}. This property takes
3226 a vector of three booleans which, in order, determine whether the
3227 object is printed at the end of, within the body of, or at the
3228 beginning of a line. Or to be more precise, before a line break,
3229 where there is no line break, or after a line break.
3231 Alternatively, these eight combinations may be specified
3232 by pre-defined functions, defined in @file{scm/output-lib.scm},
3233 where the last three columns indicate whether the layout objects
3234 will be visible in the positions shown at the head of the columns:
3236 @multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}
3237 @headitem Function @tab Vector @tab Before @tab At no @tab After
3238 @headitem form @tab form @tab break @tab break @tab break
3240 @item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes
3241 @item @code{begin-of-line-visible} @tab @code{'#(#f #f #t)} @tab no @tab no @tab yes
3242 @item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no
3243 @item @code{end-of-line-visible} @tab @code{'#(#t #f #f)} @tab yes @tab no @tab no
3244 @item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no
3245 @item @code{center-invisible} @tab @code{'#(#t #f #t)} @tab yes @tab no @tab yes
3246 @item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes
3247 @item @code{all-invisible} @tab @code{'#(#f #f #f)} @tab no @tab no @tab no
3250 The default settings of @code{break-visibility} depend on the
3251 layout object. The following table shows all the layout objects
3252 of interest which are affected by @code{break-visibility} and the
3253 default setting of this property:
3255 @multitable @columnfractions .3 .3 .4
3257 @headitem Layout object @tab Usual context @tab Default setting
3259 @c omit Ambitus as it appears not to be affected by break-visibility -td
3260 @c @item @code{Ambitus} @tab as specified @tab @code{begin-of-line-visible}
3261 @item @code{BarLine} @tab @code{Score} @tab calculated
3262 @item @code{BarNumber} @tab @code{Score} @tab @code{begin-of-line-visible}
3263 @c omit the following item until it can be explained -td
3264 @c @item @code{BreakAlignGroup} @tab @code{Score} @tab calculated
3265 @item @code{BreathingSign} @tab @code{Voice} @tab @code{begin-of-line-invisible}
3266 @item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible}
3267 @item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible}
3268 @item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible}
3269 @item @code{KeyCancellation} @tab @code{Staff} @tab @code{begin-of-line-invisible}
3270 @item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible}
3271 @c omit LeftEdge until it can be explained -td
3272 @c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible}
3273 @item @code{OctavateEight} @tab @code{Staff} @tab @code{begin-of-line-visible}
3274 @item @code{RehearsalMark} @tab @code{Score} @tab @code{end-of-line-invisible}
3275 @item @code{TimeSignature} @tab @code{Staff} @tab @code{all-visible}
3279 The example below shows the use of the vector form to control the
3280 visibility of bar lines:
3282 @lilypond[quote,verbatim,relative=1,ragged-right]
3285 % Remove bar line at the end of the current line
3286 \once \override Score.BarLine.break-visibility = ##(#f #t #t)
3292 Although all three components of the vector used to override
3293 @code{break-visibility} must be present, not all of them are
3294 effective with every layout object, and some combinations may
3295 even give errors. The following limitations apply:
3298 @item Bar lines cannot be printed at start of line.
3299 @item A bar number cannot be printed at the start of the first
3300 line unless it is set to be different from 1.
3301 @item Clef -- see below
3302 @item Double percent repeats are either all printed or all
3303 suppressed. Use begin-of line-invisible to print and
3304 all-invisible to suppress.
3305 @item Key signature -- see below
3306 @item OctavateEight -- see below
3309 @node Special considerations
3310 @unnumberedsubsubsec Special considerations
3312 @subsubsubheading Visibility following explicit changes
3314 @cindex key signature, visibility following explicit change
3315 @cindex explicitKeySignatureVisibility
3316 @cindex clef, visibility following explicit change
3317 @cindex explicitClefVisibility
3319 The @code{break-visibility} property controls the visibility of
3320 key signatures and changes of clef only at the start of lines,
3321 i.e. after a break. It has no effect on the visibility of the
3322 key signature or clef following an explicit key change or an
3323 explicit clef change within or at the end of a line. In the
3324 following example the key signature following the explicit change
3325 to B-flat major is still visible, even though @code{all-invisible}
3328 @lilypond[quote,verbatim,relative=1,ragged-right]
3331 % Try to remove all key signatures
3332 \override Staff.KeySignature.break-visibility = #all-invisible
3340 The visibility of such explicit key signature and clef changes is
3341 controlled by the @code{explicitKeySignatureVisibility} and
3342 @code{explicitClefVisibility} properties. These are the equivalent
3343 of the @code{break-visibility} property and both take a vector of
3344 three booleans or the predefined functions listed above, exactly like
3345 @code{break-visibility}. Both are properties of the Staff context,
3346 not the layout objects themselves, and so they are set using the
3347 @code{\set} command. Both are set by default to @code{all-visible}.
3348 These properties control only the visibility of key signatures and
3349 clefs resulting from explicit changes and do not affect key
3350 signatures and clefs at the beginning of lines;
3351 @code{break-visibility} must still be overridden in the appropriate
3352 object to remove these.
3354 @lilypond[quote,verbatim,relative=1,ragged-right]
3357 \set Staff.explicitKeySignatureVisibility = #all-invisible
3358 \override Staff.KeySignature.break-visibility = #all-invisible
3365 @subsubsubheading Visibility of cancelling accidentals
3367 To remove the cancelling accidentals printed at an explicit key
3368 change, set the Staff context property @code{printKeyCancellation}
3371 @lilypond[quote,verbatim,relative=1,ragged-right]
3374 \set Staff.explicitKeySignatureVisibility = #all-invisible
3375 \set Staff.printKeyCancellation = ##f
3376 \override Staff.KeySignature.break-visibility = #all-invisible
3383 With these overrides only the accidentals before the notes remain
3384 to indicate the change of key.
3386 Note that when changing the key to C@tie{}major or A@tie{}minor
3387 the cancelling accidentals would be the @emph{only} indication of
3388 the key change. In this case setting @code{printKeyCancellation} to
3389 @code{#f} has no effect:
3391 @lilypond[quote,verbatim,relative=1,ragged-right]
3394 \set Staff.explicitKeySignatureVisibility = #all-invisible
3395 \set Staff.printKeyCancellation = ##f
3402 To suppress the cancelling accidentals even when the key is
3403 changed to C@tie{}major or A@tie{}minor, override
3404 the visibility of the @code{KeyCancellation} grob instead:
3406 @lilypond[quote,verbatim,relative=1,ragged-right]
3409 \set Staff.explicitKeySignatureVisibility = #all-invisible
3410 \override Staff.KeyCancellation.break-visibility = #all-invisible
3417 @c TODO Add visibility of cautionary accidentals before notes
3419 @subsubsubheading Automatic bars
3421 @cindex automaticBars
3422 @cindex bar lines, suppressing
3424 As a special case, the printing of bar lines can also be turned off
3425 by setting the @code{automaticBars} property in the Score context.
3426 If set to @code{#f}, bar lines will not be printed automatically;
3427 they must be explicitly created with a @code{\bar} command. Unlike
3428 the @code{\cadenzaOn} predefined command, measures are still counted.
3429 Bar generation will resume according to that count if this property
3430 is later set to @code{#t}. When set to @code{#f}, line breaks can
3431 occur only at explicit @code{\bar} commands.
3435 @subsubsubheading Octavated clefs
3437 @cindex octavated clefs, visibility of
3438 @cindex visibility of octavated clefs
3439 @cindex clefs, visibility of octavation
3441 The small octavation symbol on octavated clefs is produced by the
3442 @code{OctavateEight} layout object. Its visibility is automatically
3443 inherited from the @code{Clef} object, so it is not necessary to apply
3444 any required @code{break-visibility} overrides to the @code{OctavateEight}
3445 layout objects to suppress octavation symbols for invisible clefs.
3447 For explicit clef changes, the @code{explicitClefVisibility}
3448 property controls both the clef symbol and any octavation symbol
3453 @rlearning{Visibility and color of objects}.
3457 @subsection Line styles
3459 Some performance indications, e.g., @i{rallentando} and
3460 @i{accelerando} and @i{trills} are written as text and are
3461 extended over many measures with lines, sometimes dotted or wavy.
3463 These all use the same routines as the glissando for drawing the
3464 texts and the lines, and tuning their behavior is therefore also
3465 done in the same way. It is done with a spanner, and the routine
3466 responsible for drawing the spanners is
3467 @code{ly:line-interface::print}. This routine determines the
3468 exact location of the two @i{span points} and draws a line
3469 between them, in the style requested.
3471 Here is an example showing the different line styles available,
3472 and how to tune them.
3474 @lilypond[relative=2,ragged-right,verbatim,quote]
3476 \once \override Glissando.style = #'dashed-line
3478 \override Glissando.style = #'dotted-line
3480 \override Glissando.style = #'zigzag
3482 \override Glissando.style = #'trill
3486 The locations of the end-points of the spanner are computed
3487 on-the-fly for every graphic object, but it is possible to
3491 @lilypond[relative=2,ragged-right,verbatim,quote]
3493 \once \override Glissando.bound-details.right.Y = #-2
3497 The value for @code{Y} is set to @w{@code{-2}} for the right end
3498 point. The left side may be similarly adjusted by specifying
3499 @code{left} instead of @code{right}.
3501 If @code{Y} is not set, the value is computed from the vertical
3502 position of the left and right attachment points of the spanner.
3504 Other adjustments of spanners are possible, for details, see
3507 @node Rotating objects
3508 @subsection Rotating objects
3510 Both layout objects and elements of markup text can be rotated by
3511 any angle about any point, but the method of doing so differs.
3514 * Rotating layout objects::
3518 @node Rotating layout objects
3519 @unnumberedsubsubsec Rotating layout objects
3521 @cindex rotating objects
3522 @cindex objects, rotating
3524 All layout objects which support the @code{grob-interface} can be
3525 rotated by setting their @code{rotation} property. This takes a
3526 list of three items: the angle of rotation counter-clockwise,
3527 and the x and y coordinates of the point relative to the object's
3528 reference point about which the rotation is to be performed. The
3529 angle of rotation is specified in degrees and the coordinates in
3532 The angle of rotation and the coordinates of the rotation point must
3533 be determined by trial and error.
3535 @cindex hairpins, angled
3536 @cindex angled hairpins
3538 There are only a few situations where the rotation of layout
3539 objects is useful; the following example shows one situation where
3542 @lilypond[quote,verbatim,relative=1]
3544 \override Hairpin.rotation = #'(20 -1 0)
3548 @node Rotating markup
3549 @unnumberedsubsubsec Rotating markup
3551 All markup text can be rotated to lie at any angle by prefixing it
3552 with the @code{\rotate} command. The command takes two arguments:
3553 the angle of rotation in degrees counter-clockwise and the text to
3554 be rotated. The extents of the text are not rotated: they take
3555 their values from the extremes of the x and y coordinates of the
3556 rotated text. In the following example the
3557 @code{outside-staff-priority} property for text is set to @code{#f}
3558 to disable the automatic collision avoidance, which would push some
3559 of the text too high.
3561 @lilypond[quote,verbatim,relative=1]
3562 \override TextScript.outside-staff-priority = ##f
3563 g4^\markup { \rotate #30 "a G" }
3564 b^\markup { \rotate #30 "a B" }
3565 des^\markup { \rotate #30 "a D-Flat" }
3566 fis^\markup { \rotate #30 "an F-Sharp" }
3569 @node Advanced tweaks
3570 @section Advanced tweaks
3572 This section discusses various approaches to fine tuning the
3573 appearance of the printed score.
3576 * Aligning objects::
3577 * Vertical grouping of grobs::
3578 * Modifying stencils::
3579 * Modifying shapes::
3580 * Unpure-pure containers::
3585 @rlearning{Tweaking output},
3586 @rlearning{Other sources of information}.
3589 @ref{Explaining the Internals Reference},
3590 @ref{Modifying properties}.
3593 @rextend{Interfaces for programmers}.
3596 @file{scm/define-grobs.scm}.
3599 @rlsr{Tweaks and overrides}.
3601 Internals Reference:
3602 @rinternals{All layout objects}.
3605 @node Aligning objects
3606 @subsection Aligning objects
3608 Graphical objects which support the @code{self-alignment-interface}
3609 and/or the @code{side-position-interface} can be aligned to a previously
3610 placed object in a variety of ways. For a list of these objects, see
3611 @rinternals{self-alignment-interface} and @rinternals{side-position-interface}.
3613 All graphical objects have a reference point, a horizontal extent and a
3614 vertical extent. The horizontal extent is a pair of numbers
3615 giving the displacements from the reference point of the left and
3616 right edges, displacements to the left being negative. The vertical
3617 extent is a pair of numbers giving the displacement from the reference
3618 point to the bottom and top edges, displacements down being negative.
3620 An object's position on a staff is given by the values of the
3621 @code{X-offset} and @code{Y-offset} properties. The value of
3622 @code{X-offset} gives the displacement from the X coordinate of
3623 the reference point of the parent object, and the value of
3624 @code{Y-offset} gives the displacement from the center line of the
3625 staff. The values of @code{X-offset} and @code{Y-offset} may
3626 be set directly or may be set to be calculated by procedures in order
3627 to achieve alignment with the parent object.
3629 @warning{Many objects have special positioning considerations which
3630 cause any setting of @code{X-offset} or @code{Y-offset} to be
3631 ignored or modified, even though the object supports the
3632 @code{self-alignment-interface}. Overriding the @code{X-offset}
3633 or @code{Y-offset} properties to a fixed value causes the respective
3634 @code{self-alignment} property to be disregarded.}
3636 For example, an accidental can be repositioned vertically by setting
3637 @code{Y-offset} but any changes to @code{X-offset} have no effect.
3639 Rehearsal marks may be aligned with breakable objects such as bar
3640 lines, clef symbols, time signature symbols and key signatures. There
3641 are special properties to be found in the @code{break-aligned-interface}
3642 for positioning rehearsal marks on such objects.
3646 @ref{Using the break-alignable-interface}.
3649 @rextend{Callback functions}.
3652 * Setting X-offset and Y-offset directly::
3653 * Using the side-position-interface::
3654 * Using the self-alignment-interface::
3655 * Using the break-alignable-interface::
3658 @node Setting X-offset and Y-offset directly
3659 @unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly
3661 Numerical values may be given to the @code{X-offset} and @code{Y-offset}
3662 properties of many objects. The following example shows three
3663 notes with the default fingering position and the positions with @code{X-offset}
3664 and @code{Y-offset} modified.
3666 @lilypond[verbatim,quote,relative=2]
3673 -\tweak X-offset #-1
3680 @node Using the side-position-interface
3681 @unnumberedsubsubsec Using the @code{side-position-interface}
3683 An object which supports the @code{side-position-interface} can be
3684 placed next to its parent object so that
3685 the specified edges of the two objects touch. The object may be
3686 placed above, below, to the right or to the left of the parent.
3687 The parent cannot be specified; it is determined by the order of
3688 elements in the input stream. Most objects have the associated
3689 note head as their parent.
3691 The values of the @code{side-axis} and @code{direction} properties
3692 determine where the object is to be placed, as follows:
3694 @c TODO add an example of each to the table
3696 @multitable @columnfractions .3 .3 .3
3697 @headitem @code{side-axis} @tab @code{direction} @tab
3698 @headitem property @tab property @tab Placement
3700 @item @code{0} @tab @code{-1} @tab left
3701 @item @code{0} @tab @code{1} @tab right
3702 @item @code{1} @tab @code{-1} @tab below
3703 @item @code{1} @tab @code{1} @tab above
3707 When @code{side-axis} is @code{0}, @code{X-offset} should be set to
3708 the procedure @code{ly:side-position-interface::x-aligned-side}.
3709 This procedure will return the correct value of @code{X-offset} to
3710 place the object to the left or right side of the parent according
3711 to value of @code{direction}.
3713 When @code{side-axis} is @code{1}, @code{Y-offset} should be set to
3714 the procedure @code{ly:side-position-interface::y-aligned-side}.
3715 This procedure will return the correct value of @code{Y-offset} to
3716 place the object to the top or bottom of the parent according
3717 to value of @code{direction}.
3719 @c TODO Add examples
3721 @node Using the self-alignment-interface
3722 @unnumberedsubsubsec Using the @code{self-alignment-interface}
3724 @subsubsubheading Self-aligning objects horizontally
3726 The horizontal alignment of an object which supports the
3727 @code{self-alignment-interface} is controlled by the value of
3728 the @code{self-alignment-X} property, provided the object's
3729 @code{X-offset} property is set to
3730 @code{ly:self-alignment-interface::x-aligned-on-self}.
3731 @code{self-alignment-X} may be given any
3732 real value, in units of half the total X extent of the
3733 object. Negative values move the object to the right, positive
3734 to the left. A value of @code{0} centers the object on the
3735 reference point of its parent, a value of @w{@code{-1}} aligns the
3736 left edge of the object on the reference point of its parent,
3737 and a value of @code{1} aligns the right edge of the object on the
3738 reference point of its parent. The symbols @code{LEFT},
3739 @code{CENTER}, and @code{RIGHT} may be used instead of the values
3740 @w{@code{-1}}, @code{0}, and @code{1}, respectively.
3742 Normally the @code{\override} command would be used to modify the
3743 value of @code{self-alignment-X}, but the @code{\tweak} command
3744 can be used to separately align several annotations on a single
3747 @lilypond[quote,verbatim,relative=1]
3749 -\tweak self-alignment-X #-1
3751 -\tweak self-alignment-X #0
3753 -\tweak self-alignment-X #RIGHT
3755 -\tweak self-alignment-X #-2.5
3756 ^"aligned further to the right"
3759 @subsubsubheading Self-aligning objects vertically
3761 Objects may be aligned vertically in an analogous way to aligning
3762 them horizontally if the @code{Y-offset} property is set to
3763 @code{ly:self-alignment-interface::y-aligned-on-self}. However,
3764 other mechanisms are often involved in vertical alignment: the
3765 value of @code{Y-offset} is just one variable taken into account.
3766 This may make adjusting the value of some objects tricky.
3767 The units are just half the vertical extent of the object, which
3768 is usually quite small, so quite large numbers may be required.
3769 A value of @w{@code{-1}} aligns the lower edge of the object with
3770 the reference point of the parent object, a value of @code{0}
3771 aligns the center of the object with the reference point of the
3772 parent, and a value of @code{1} aligns the top edge of the object
3773 with the reference point of the parent. The symbols @code{DOWN},
3774 @code{CENTER}, and @code{UP} may be substituted for @w{@code{-1}},
3775 @code{0}, and @code{1}, respectively.
3777 @subsubsubheading Self-aligning objects in both directions
3779 By setting both @code{X-offset} and @code{Y-offset}, an object may
3780 be aligned in both directions simultaneously.
3782 The following example shows how to adjust a fingering mark so
3783 that it nestles close to the note head.
3785 @lilypond[quote,verbatim,relative=2]
3787 -\tweak self-alignment-X #0.5 % move horizontally left
3788 -\tweak Y-offset #ly:self-alignment-interface::y-aligned-on-self
3789 -\tweak self-alignment-Y #-1 % move vertically up
3794 @unnumberedsubsubsec Using the @code{aligned-on-parent} procedures
3796 @c Cannot document as they do not seem to operate consistently on all objects -td
3797 @c TODO investigate further
3799 The @code{aligned-on-parent} procedures are used in the same way
3800 as the @code{aligned-on-self} procedures, they difference being
3801 that they permit an object to be aligned with the @emph{edges} of
3802 the parent rather than the parent's reference point. The following
3803 example shows the difference:
3807 @lilypond[verbatim,quote]
3813 @unnumberedsubsubsec Using the @code{centered-on-parent} procedures
3815 @c Cannot document as they do not seem to operate consistently on all objects -td
3816 @c TODO investigate further
3820 @c TODO The align-interface, BassFigureAlignment and VerticalAlignment
3822 @node Using the break-alignable-interface
3823 @unnumberedsubsubsec Using the @code{break-alignable-interface}
3825 @cindex align to objects
3826 @cindex break-align-symbols
3828 Rehearsal marks and bar numbers may be aligned with notation
3829 objects other than bar lines. These objects include @code{ambitus},
3830 @code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
3831 @code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
3832 @code{time-signature}.
3834 By default, rehearsal marks and bar numbers will be horizontally
3835 centered above the object:
3837 @lilypond[verbatim,quote,relative=1]
3838 % The rehearsal mark will be centered above the Clef
3839 \override Score.RehearsalMark.break-align-symbols = #'(clef)
3844 % The rehearsal mark will be centered above the Time Signature
3845 \override Score.RehearsalMark.break-align-symbols = #'(time-signature)
3851 % The rehearsal mark will be centered above the Breath Mark
3852 \override Score.RehearsalMark.break-align-symbols = #'(breathing-sign)
3861 A list of possible target alignment objects may be specified. If
3862 some of the objects are invisible at that point due to the setting
3863 of @code{break-visibility} or the explicit visibility settings for
3864 keys and clefs, the rehearsal mark or bar number is aligned to the
3865 first object in the list which is visible. If no objects in the
3866 list are visible the object is aligned to the bar line. If the bar
3867 line is invisible the object is aligned to the place where the bar
3870 @lilypond[verbatim,quote,relative=1]
3871 % The rehearsal mark will be centered above the Key Signature
3872 \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
3877 % The rehearsal mark will be centered above the Clef
3878 \set Staff.explicitKeySignatureVisibility = #all-invisible
3879 \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
3884 % The rehearsal mark will be centered above the Bar Line
3885 \set Staff.explicitKeySignatureVisibility = #all-invisible
3886 \set Staff.explicitClefVisibility = #all-invisible
3887 \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
3894 The alignment of the rehearsal mark relative to the notation object
3895 can be changed, as shown in the following example. In a score with
3896 multiple staves, this setting should be done for all the staves.
3898 @lilypond[verbatim,quote,relative=1]
3899 % The RehearsalMark will be centered above the Key Signature
3900 \override Score.RehearsalMark.break-align-symbols = #'(key-signature)
3906 % The RehearsalMark will be aligned with the left edge of the Key Signature
3907 \once \override Score.KeySignature.break-align-anchor-alignment = #LEFT
3911 % The RehearsalMark will be aligned with the right edge of the Key Signature
3912 \once \override Score.KeySignature.break-align-anchor-alignment = #RIGHT
3918 The rehearsal mark can also be offset to the right or left of the left
3919 edge by an arbitrary amount. The units are staff-spaces:
3921 @lilypond[verbatim,quote,relative=1]
3922 % The RehearsalMark will be aligned with the left edge of the Key Signature
3923 % and then shifted right by 3.5 staff-spaces
3924 \override Score.RehearsalMark.break-align-symbols = #'(key-signature)
3925 \once \override Score.KeySignature.break-align-anchor = #3.5
3929 % The RehearsalMark will be aligned with the left edge of the Key Signature
3930 % and then shifted left by 2 staff-spaces
3931 \once \override Score.KeySignature.break-align-anchor = #-2
3938 @node Vertical grouping of grobs
3939 @subsection Vertical grouping of grobs
3941 @c TODO Expand this section
3943 The VerticalAlignment and VerticalAxisGroup grobs work together.
3944 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
3945 etc. VerticalAlignment then vertically aligns the different grobs
3946 grouped together by VerticalAxisGroup. There is usually only one
3947 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
3951 @node Modifying stencils
3952 @subsection Modifying stencils
3954 All layout objects have a @code{stencil} property which is part of
3955 the @code{grob-interface}. By default, this property is usually
3956 set to a function specific to the object that is tailor-made to
3957 render the symbol which represents it in the output. For example,
3958 the standard setting for the @code{stencil} property of the
3959 @code{MultiMeasureRest} object is @code{ly:multi-measure-rest::print}.
3961 The standard symbol for any object can be replaced by modifying the
3962 @code{stencil} property to reference a different, specially-written,
3963 procedure. This requires a high level of knowledge of the internal
3964 workings of LilyPond, but there is an easier way which can often
3965 produce adequate results.
3967 This is to set the @code{stencil} property to the procedure which
3968 prints text -- @code{ly:text-interface::print} -- and to add a
3969 @code{text} property to the object which is set to contain the
3970 markup text which produces the required symbol. Due to the
3971 flexibility of markup, much can be achieved -- see in particular
3972 @ref{Graphic notation inside markup}.
3974 The following example demonstrates this by changing the note head
3975 symbol to a cross within a circle.
3977 @lilypond[verbatim,quote]
3979 \once \override NoteHead.stencil = #ly:text-interface::print
3980 \once \override NoteHead.text = \markup {
3982 \halign #-0.7 \draw-circle #0.85 #0.2 ##f
3983 \musicglyph #"noteheads.s2cross"
3991 Any of the glyphs in the feta Font can be supplied to the
3992 @code{\musicglyph} markup command -- see @ref{The Feta font}.
3994 @c TODO Add inserting eps files or ref to later
3996 @c TODO Add inserting Postscript or ref to later
4000 @ref{Graphic notation inside markup},
4001 @ref{Formatting text},
4002 @ref{Text markup commands},
4003 @ref{The Feta font}.
4006 @node Modifying shapes
4007 @subsection Modifying shapes
4010 * Modifying ties and slurs::
4013 @node Modifying ties and slurs
4014 @unnumberedsubsubsec Modifying ties and slurs
4016 @cindex slurs, modifying
4017 @cindex ties, modifying
4018 @cindex Bézier curves, control points
4019 @cindex control points, Bézier curves
4021 @code{Tie}s, @code{Slur}s, @code{PhrasingSlur}s,
4022 @code{LaissezVibrerTie}s and @code{RepeatTie}s are all drawn as
4023 third-order Bézier curves. If the shape of the tie or slur which
4024 is calculated automatically is not optimum, the shape may be
4025 modified manually in two ways:
4029 by specifying the displacements to be made to the control points
4030 of the automatically calculated Bézier curve, or
4033 by explicitly specifying the positions of the four control points
4034 required to define the wanted curve.
4037 Both methods are explained below. The first method is more suitable
4038 if only slight adjustments to the curve are required; the second may
4039 be better for creating curves which are related to just a single
4042 @subsubsubheading Cubic Bézier curves
4044 Third-order or cubic Bézier curves are defined by four control
4045 points. The first and fourth control points are precisely the
4046 starting and ending points of the curve. The intermediate two
4047 control points define the shape. Animations showing how the curve
4048 is drawn can be found on the web, but the following description
4049 may be helpful. The curve starts from the first control point
4050 heading directly towards the second, gradually bending over to
4051 head towards the third and continuing to bend over to head towards
4052 the fourth, arriving there travelling directly from the third
4053 control point. The curve is entirely contained in the
4054 quadrilateral defined by the four control points. Translations,
4055 rotations and scaling of the control points all result in exactly
4056 the same operations on the curve.
4058 @subsubsubheading Specifying displacements from current control points
4060 @cindex shaping slurs and ties
4063 In this example the automatic placement of the tie is not optimum,
4064 and @code{\tieDown} would not help.
4066 @lilypond[verbatim,quote,relative=1]
4070 { r4 <g c,> <g c,> <g c,> }
4074 Adjusting the control points of the tie with @code{\shape} allows
4075 the collisions to be avoided.
4077 The syntax of @code{\shape} is
4080 [-]@code{\shape} @var{displacements} @var{item}
4083 This will reposition the control-points of @var{item} by the amounts
4084 given by @var{displacements}. The @var{displacements} argument is a
4085 list of number pairs or a list of such lists. Each element of a pair
4086 represents the displacement of one of the coordinates of a
4087 control-point. If @var{item} is a string, the result is
4088 @code{\once\override} for the specified grob type. If @var{item} is
4089 a music expression, the result is the same music expression with an
4090 appropriate tweak applied.
4092 In other words, the @code{\shape} function can act as either a
4093 @code{\once\override} command or a @code{\tweak} command depending
4094 on whether the @var{item} argument is a grob name, like @qq{Slur},
4095 or a music expression, like @qq{(}. The @var{displacements} argument
4096 specifies the displacements of the four control points as a list of
4097 four pairs of (dx . dy) values in units of staff-spaces (or a list
4098 of such lists if the curve has more than one segment).
4100 The leading hyphen is required if and only if the @code{\tweak} form
4103 So, using the same example as above and the @code{\once\override}
4104 form of @code{\shape}, this will raise the tie by half a staff-space:
4106 @lilypond[verbatim,quote,relative=1]
4109 \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
4113 { r4 <g c,> <g c,> <g c,> }
4117 This positioning of the tie is better, but maybe it should be raised
4118 more in the center. The following example does this, this time using
4119 the alternative @code{\tweak} form:
4121 @lilypond[verbatim,quote,relative=1]
4124 e1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e
4127 { r4 <g c,> <g c,> <g c,> }
4131 Changes to the horizontal positions of the control points may be made
4132 in the same way, and two different curves starting at the same
4133 musical moment may also be shaped:
4135 @lilypond[verbatim,quote,ragged-right,relative=2]
4137 \shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
4138 \shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
4142 The @code{\shape} function can also displace the control points of
4143 curves which stretch across line breaks. Each piece of the broken
4144 curve can be given its own list of offsets. If changes to a
4145 particular segment are not needed, the empty list can serve as a
4146 placeholder. In this example the line break makes the single slur
4149 @lilypond[verbatim,quote,ragged-right,relative=1]
4155 Changing the shapes of the two halves of the slur makes it clearer
4156 that the slur continues over the line break:
4158 @lilypond[verbatim,quote,ragged-right,relative=1]
4159 % () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
4160 % if any of the segments does not need to be changed
4162 (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
4163 ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
4170 If an S-shaped curve is required the control points must always be
4171 adjusted manually --- LilyPond will never select such shapes
4174 @lilypond[verbatim,quote,relative=2]
4175 c8( e b-> f d' a e-> g)
4176 \shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
4177 c8\( e b-> f d' a e-> g\)
4180 @subsubsubheading Specifying control points explicitly
4182 The coordinates of the Bézier control points are specified in units
4183 of staff-spaces. The X@tie{}coordinate is relative to the reference
4184 point of the note to which the tie or slur is attached, and the
4185 Y@tie{}coordinate is relative to the staff center line. The
4186 coordinates are specified as a list of four pairs of decimal numbers
4187 (reals). One approach is to estimate the coordinates of the two
4188 end points, and then guess the two intermediate points. The optimum
4189 values are then found by trial and error. Be aware that these values
4190 may need to be manually adjusted if any further changes are made to
4191 the music or the layout.
4193 One situation where specifying the control points explicitly is
4194 preferable to specifying displacements is when they need to be
4195 specified relative to a single note. Here is an example of this.
4196 It shows one way of indicating a slur extending into alternative
4197 sections of a volta repeat.
4199 @lilypond[verbatim,quote,relative=2]
4201 \repeat volta 3 { c4 d( e f }
4206 % create a slur and move it to a new position
4207 % the <> is just an empty chord to carry the slur termination
4208 -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
4213 % create a slur and move it to a new position
4214 -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
4221 It is not possible to modify shapes of ties or slurs by changing
4222 the @code{control-points} property if there are multiple ties or slurs
4223 at the same musical moment -- the @code{\tweak} command will also not
4224 work in this case. However, the @code{tie-configuration} property of
4225 @code{TieColumn} can be overridden to set start line and direction as
4229 Internals Reference:
4230 @rinternals{TieColumn}.
4233 @node Unpure-pure containers
4234 @subsection Unpure-pure containers
4236 @cindex Scheme, pure containers
4237 @cindex Scheme, unpure containers
4238 @cindex pure containers, Scheme
4239 @cindex unpure containers, Scheme
4240 @cindex horizontal spacing, overriding
4242 Unpure-pure containers are useful for overriding @emph{Y-axis} spacing
4243 calculations - specifically @code{Y-offset} and @code{Y-extent} - with a
4244 Scheme function instead of a literal (i.e. a number or pair).
4246 For certain grobs, the @code{Y-extent} is based on the @code{stencil}
4247 property, overriding the stencil property of one of these will
4248 require an additional @code{Y-extent} override with an unpure-pure
4249 container. When a function overrides a @code{Y-offset} and/or
4250 @code{Y-extent} it is assumed that this will trigger line breaking
4251 calculations too early during compilation. So the function is not
4252 evaluated at all (usually returning a value of @samp{0} or
4253 @samp{'(0 . 0)}) which can result in collisions. A @q{pure} function
4254 will not affect properties, objects or grob suicides and therefore will
4255 always have its Y-axis-related evaluated correctly.
4257 Currently, there are about thirty functions that are already considered
4258 @q{pure} and Unpure-pure containers are a way to set functions not on
4259 this list as @q{pure}. The @q{pure} function is evaluated @emph{before}
4260 any line-breaking and so the horizontal spacing can be adjusted
4261 @q{in time}. The @q{unpure} function is then evaluated @emph{after}
4264 @warning{As it is difficult to always know which functions are on this
4265 list we recommend that any @q{pure} functions you create do not use
4266 @code{Beam} or @code{VerticalAlignment} grobs.}
4268 An unpure-pure container is constructed as follows;
4270 @code{(ly:make-unpure-pure-container f0 f1)}
4272 where @code{f0} is a function taking @var{n} arguments (@var{n >= 1})
4273 and the first argument must always be the grob. This is the function
4274 that gives the actual result. @var{f1} is the function being labeled
4275 as @q{pure} that takes @var{n + 2} arguments. Again, the first argument
4276 must always still be the grob but the second and third are @q{start}
4277 and @q{end} arguments.
4279 @var{start} and @var{end} are, for all intents and purposes, dummy
4280 values that only matter for @code{Spanners} (i.e @code{Hairpin} or
4281 @code{Beam}), that can return different height estimations based on a
4282 starting and ending column.
4284 The rest are the other arguments to the first function (which
4285 may be none if @var{n = 1}).
4287 The results of the second function are used as an approximation of the
4288 value needed which is then used by the first function to get the real
4289 value which is then used for fine-tuning much later during the spacing
4292 @lilypond[verbatim,quote,ragged-right]
4293 #(define (square-line-circle-space grob)
4294 (let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
4295 (notename (ly:pitch-notename pitch)))
4296 (if (= 0 (modulo notename 2))
4297 (make-circle-stencil 0.5 0.0 #t)
4298 (make-filled-box-stencil '(0 . 1.0)
4301 squareLineCircleSpace = {
4302 \override NoteHead.stencil = #square-line-circle-space
4305 smartSquareLineCircleSpace = {
4306 \squareLineCircleSpace
4307 \override NoteHead.Y-extent =
4308 #(ly:make-unpure-pure-container
4309 ly:grob::stencil-height
4310 (lambda (grob start end) (ly:grob::stencil-height grob)))
4313 \new Voice \with { \remove "Stem_engraver" }
4315 \squareLineCircleSpace
4317 \smartSquareLineCircleSpace
4322 In the first measure, without the unpure-pure container, the spacing
4323 engine does not know the width of the note head and lets it collide with
4324 the accidentals. In the second measure, with unpure-pure containers,
4325 the spacing engine knows the width of the note heads and avoids the
4326 collision by lengthening the line accordingly.
4328 Usually for simple calculations nearly-identical functions for both the
4329 @q{unpure} and @q{pure} parts can be used, by only changing the number
4330 of arguments passed to, and the scope of, the function.
4332 @warning{If a function is labeled as @q{pure} and it turns out not to
4333 be, the results can be unexpected.}
4336 @node Using music functions
4337 @section Using music functions
4339 @c TODO -- add @seealso, etc. to these subsections
4341 Where tweaks need to be reused with different music expressions,
4342 it is often convenient to make the tweak part of a @emph{music
4343 function}. In this section, we discuss only @emph{substitution}
4344 functions, where the object is to substitute a variable into a
4345 piece of LilyPond input code. Other more complex functions are
4346 described in @rextend{Music functions}.
4349 * Substitution function syntax::
4350 * Substitution function examples::
4353 @node Substitution function syntax
4354 @subsection Substitution function syntax
4356 Making a function that substitutes a variable into LilyPond
4357 code is easy. The general form of these functions is
4361 #(define-music-function
4362 (parser location @var{arg1} @var{arg2} @dots{})
4363 (@var{type1?} @var{type2?} @dots{})
4365 @var{@dots{}music@dots{}}
4372 @multitable @columnfractions .33 .66
4373 @item @code{@var{argN}}
4374 @tab @var{n}th argument
4376 @item @code{@var{typeN?}}
4377 @tab a scheme @emph{type predicate} for which @code{@var{argN}}
4378 must return @code{#t}.
4380 @item @code{@var{@dots{}music@dots{}}}
4381 @tab normal LilyPond input, using @code{$} (in places where only
4382 Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
4383 value or music function argument or music inside of music lists) to
4388 The @code{parser} and @code{location} arguments are mandatory, and
4389 are used in some advanced situations as described in the
4390 @q{Extending} manual (see @rextend{Music functions}). For
4391 substitution functions, just be sure to include them.
4393 The list of type predicates is also required. Some of the most
4394 common type predicates used in music functions are:
4398 cheap-list? @emph{(use instead of }@q{list?}@emph{ for faster processing)}
4410 For a list of available type predicates, see
4411 @ref{Predefined type predicates}. User-defined type predicates
4416 @ref{Predefined type predicates}.
4419 @rextend{Music functions}.
4422 @file{lily/music-scheme.cc},
4424 @file{scm/lily.scm}.
4427 @node Substitution function examples
4428 @subsection Substitution function examples
4430 This section introduces some substitution function examples.
4431 These are not intended to be exhaustive, but rather to demonstrate
4432 some of the possibilities of simple substitution functions.
4434 In the first example, a function is defined that simplifies
4435 setting the padding of a TextScript:
4437 @lilypond[quote,verbatim,ragged-right]
4439 #(define-music-function
4440 (parser location padding)
4443 \once \override TextScript.padding = #padding
4447 c4^"piu mosso" b a b
4449 c4^"piu mosso" d e f
4451 c4^"piu mosso" fis a g
4455 In addition to numbers, we can use music expressions such
4456 as notes for arguments to music functions:
4458 @lilypond[quote,verbatim,ragged-right]
4460 #(define-music-function
4461 (parser location note)
4464 \tweak NoteHead.stencil #ly:text-interface::print
4465 \tweak NoteHead.text
4466 \markup \musicglyph #"custodes.mensural.u0"
4467 \tweak Stem.stencil ##f
4471 \relative c' { c4 d e f \custosNote g }
4474 Substitution functions with multiple arguments can be defined:
4476 @lilypond[quote,verbatim,ragged-right]
4478 #(define-music-function
4479 (parser location padding tempotext)
4482 \once \override Score.MetronomeMark.padding = #padding
4483 \tempo \markup { \bold #tempotext }
4487 \tempo \markup { "Low tempo" }
4489 \tempoPadded #4.0 "High tempo"
4494 @c TODO: add appropriate @@ref's here.