1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
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. See TRANSLATION for details.
10 @node Changing defaults
11 @chapter Changing defaults
14 The purpose of LilyPond's design is to provide the finest output
15 quality as a default. Nevertheless, it may happen that you need to
16 change this default layout. The layout is controlled through a large
17 number of proverbial @q{knobs and switches.} This chapter does not
18 list each and every knob. Rather, it outlines what groups of controls
19 are available and explains how to lookup which knob to use for a
23 @cindex Program reference
25 The controls available for tuning are described in a separate
28 Program reference manual.
31 @ref{Top,Program reference,,lilypond-internals}.
34 lists all different variables, functions and options available in
35 LilyPond. It is written as a HTML document, which is available
36 @c leave the @uref as one long line.
37 @uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
38 but is also included with the LilyPond documentation package.
40 There are four areas where the default settings may be changed:
44 Automatic notation: changing the automatic creation of notation
45 elements. For example, changing the beaming rules.
48 Output: changing the appearance of individual
49 objects. For example, changing stem directions or the location of
53 Context: changing aspects of the translation from music events to
54 notation. For example, giving each staff a separate time signature.
57 Page layout: changing the appearance of the spacing, line
58 breaks, and page dimensions. These modifications are discussed
59 in @ref{Non-musical notation}, and @ref{Spacing issues}.
62 Internally, LilyPond uses Scheme (a LISP dialect) to provide
63 infrastructure. Overriding layout decisions in effect accesses the
64 program internals, which requires Scheme input. Scheme elements are
65 introduced in a @code{.ly} file with the hash mark
66 @code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
67 on entering numbers, lists, strings, and symbols in Scheme.}
71 * Interpretation contexts::
72 * The \override command::
76 @node Interpretation contexts
77 @section Interpretation contexts
79 This section describes what contexts are, and how to modify them.
82 * Contexts explained::
84 * Changing context properties on the fly::
85 * Modifying context plug-ins::
86 * Layout tunings within contexts::
87 * Changing context default settings::
88 * Defining new contexts::
90 * Vertical grouping of grobs::
94 @node Contexts explained
95 @subsection Contexts explained
97 When music is printed, a lot of notational elements must be added to the
98 output. For example, compare the input and output of the following example:
100 @lilypond[quote,verbatim,relative=2,fragment]
104 The input is rather sparse, but in the output, bar lines, accidentals,
105 clef, and time signature are added. LilyPond @emph{interprets} the
106 input. During this step, the musical information is inspected in time
107 order, similar to reading a score from left to right. While reading
108 the input, the program remembers where measure boundaries are, and which
109 pitches require explicit accidentals. This information can be presented on
110 several levels. For example, the effect of an accidental is limited
111 to a single staff, while a bar line must be synchronized across the
114 Within LilyPond, these rules and bits of information are grouped in
115 @emph{Contexts}. Some examples of contexts are @context{Voice},
116 @context{Staff}, and @context{Score}. They are hierarchical, for
117 example: a @context{Staff} can contain many @context{Voice}s, and a
118 @context{Score} can contain many @context{Staff} contexts.
121 @image{context-example,5cm,,}
124 Each context has the responsibility for enforcing some notation rules,
125 creating some notation objects and maintaining the associated
126 properties. For example, the @context{Voice} context may introduce an
127 accidental and then the @context{Staff} context maintains the rule to
128 show or suppress the accidental for the remainder of the measure. The
129 synchronization of bar lines is handled at @context{Score} context.
131 However, in some music we may not want the bar lines to be
132 synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
133 such cases, we must modify the default settings of the @context{Score}
134 and @context{Staff} contexts.
136 For very simple scores, contexts are created implicitly, and you need
137 not be aware of them. For larger pieces, such as anything with more
138 than one staff, they must be
139 created explicitly to make sure that you get as many staves as you
140 need, and that they are in the correct order. For typesetting pieces
141 with specialized notation, it can be useful to modify existing or
142 to define new contexts.
145 A complete description of all available contexts is in the program
148 @internalsref{Contexts}.
151 Translation @expansion{} Context.
154 @c [TODO: describe propagation]
157 @node Creating contexts
158 @subsection Creating contexts
160 For scores with only one voice and one staff, contexts are
161 created automatically. For more complex scores, it is necessary to
162 create them by hand. There are three commands that do this.
167 The easiest command is @code{\new}, and it also the quickest to type.
168 It is prepended to a music expression, for example
172 @cindex Context, creating
175 \new @var{type} @var{music expression}
179 where @var{type} is a context name (like @code{Staff} or
180 @code{Voice}). This command creates a new context, and starts
181 interpreting the @var{music expression} with that.
183 A practical application of @code{\new} is a score with many
184 staves. Each part that should be on its own staff, is preceded with
187 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
194 The @code{\new} command may also give a name to the context,
197 \new @var{type} = @var{id} @var{music}
199 However, this user specified name is only used if there is no other
200 context already earlier with the same name.
206 Like @code{\new}, the @code{\context} command also directs a music
207 expression to a context object, but gives the context an explicit name. The
211 \context @var{type} = @var{id} @var{music}
214 This form will search for an existing context of type @var{type}
215 called @var{id}. If that context does not exist yet, a new
216 context with the specified name is created. This is useful if
217 the context is referred to later on. For example, when
218 setting lyrics the melody is in a named context
221 \context Voice = "@b{tenor}" @var{music}
225 so the texts can be properly aligned to its notes,
228 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
233 Another possible use of named contexts is funneling two different
234 music expressions into one context. In the following example,
235 articulations and notes are entered separately,
239 arts = @{ s4-. s4-> @}
242 They are combined by sending both to the same @context{Voice} context,
246 \new Staff \context Voice = "A" \music
247 \context Voice = "A" \arts
250 @lilypond[quote,ragged-right]
254 \new Staff \context Voice = "A" \music
255 \context Voice = "A" \arts
259 With this mechanism, it is possible to define an Urtext (original
260 edition), with the option to put several distinct articulations on the
263 @cindex creating contexts
266 The third command for creating contexts is
268 \context @var{type} @var{music}
273 This is similar to @code{\context} with @code{= @var{id}}, but matches
274 any context of type @var{type}, regardless of its given name.
276 This variant is used with music expressions that can be interpreted at
277 several levels. For example, the @code{\applyOutput} command (see
278 @ref{Running a function on all layout objects}). Without an explicit
279 @code{\context}, it is usually applied to @context{Voice}
282 \applyOutput #'@var{context} #@var{function} % apply to Voice
285 To have it interpreted at the @context{Score} or @context{Staff} level use
289 \applyOutput #'Score #@var{function}
290 \applyOutput #'Staff #@var{function}
296 @node Changing context properties on the fly
297 @subsection Changing context properties on the fly
301 @cindex changing properties
303 Each context can have different @emph{properties}, variables contained
304 in that context. They can be changed during the interpretation step.
305 This is achieved by inserting the @code{\set} command in the music,
308 \set @var{context}.@var{prop} = #@var{value}
312 @lilypond[quote,verbatim,relative=2,fragment]
314 \set Score.skipBars = ##t
318 This command skips measures that have no notes. The result is that
319 multi-rests are condensed. The value assigned is a Scheme object. In
320 this case, it is @code{#t}, the boolean True value.
322 If the @var{context} argument is left out, then the current bottom-most
323 context (typically @context{ChordNames}, @context{Voice}, or
324 @context{Lyrics}) is used. In this example,
326 @lilypond[quote,verbatim,relative=2,fragment]
328 \set autoBeaming = ##f
333 the @var{context} argument to @code{\set} is left out, so automatic
334 beaming is switched off in the current @internalsref{Voice}. Note that
335 the bottom-most context does not always contain the property that you
336 wish to change -- for example, attempting to set the @code{skipBars}
337 property (of the bottom-most context, in this case @code{Voice}) will
340 @lilypond[quote,verbatim,relative=2,fragment]
346 Contexts are hierarchical, so if a bigger context was specified, for
347 example @context{Staff}, then the change would also apply to all
348 @context{Voice}s in the current stave. The change is applied
349 @q{on-the-fly}, during the music, so that the setting only affects the
350 second group of eighth notes.
354 There is also an @code{\unset} command,
356 \unset @var{context}.@var{prop}
360 which removes the definition of @var{prop}. This command removes
361 the definition only if it is set in @var{context}, so
364 \set Staff.autoBeaming = ##f
368 introduces a property setting at @code{Staff} level. The setting also
369 applies to the current @code{Voice}. However,
372 \unset Voice.autoBeaming
376 does not have any effect. To cancel this setting, the @code{\unset}
377 must be specified on the same level as the original @code{\set}. In
378 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
381 \unset Staff.autoBeaming
384 Like @code{\set}, the @var{context} argument does not have to be
385 specified for a bottom context, so the two statements
388 \set Voice.autoBeaming = ##t
389 \set autoBeaming = ##t
397 Settings that should only apply to a single time-step can be entered
398 with @code{\once}, for example in
400 @lilypond[quote,verbatim,relative=2,fragment]
402 \once \set fontSize = #4.7
407 the property @code{fontSize} is unset automatically after the second
410 A full description of all available context properties is in the
411 program reference, see
413 @internalsref{Tunable context properties}.
416 Translation @expansion{} Tunable context properties.
420 @node Modifying context plug-ins
421 @subsection Modifying context plug-ins
423 Notation contexts (like @code{Score} and @code{Staff}) not only
425 they also contain plug-ins called @q{engravers} that create notation
426 elements. For example, the @code{Voice} context contains a
427 @code{Note_head_engraver} and the @code{Staff} context contains a
428 @code{Key_signature_engraver}.
430 For a full a description of each plug-in, see
432 @internalsref{Engravers}.
435 Program reference @expansion{} Translation @expansion{} Engravers.
437 Every context described in
439 @internalsref{Contexts}
442 Program reference @expansion{} Translation @expansion{} Context.
444 lists the engravers used for that context.
447 It can be useful to shuffle around these plug-ins. This is done by
448 starting a new context with @code{\new} or @code{\context}, and
454 \new @var{context} \with @{
467 where the @dots{} should be the name of an engraver. Here is a simple
468 example which removes @code{Time_signature_engraver} and
469 @code{Clef_engraver} from a @code{Staff} context,
471 @lilypond[quote,relative=1,verbatim,fragment]
477 \remove "Time_signature_engraver"
478 \remove "Clef_engraver"
485 In the second staff there are no time signature or clef symbols. This
486 is a rather crude method of making objects disappear since it will affect
487 the entire staff. This method also influences the spacing, which may or
488 may not be desirable. A more
489 sophisticated method of blanking objects is shown in @rlearning{Common tweaks}.
491 The next example shows a practical application. Bar lines and time
492 signatures are normally synchronized across the score. This is done
493 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
494 This plug-in keeps an administration of time signature, location
495 within the measure, etc. By moving thes engraver from @code{Score} to
496 @code{Staff} context, we can have a score where each staff has its own
499 @cindex polymetric scores
500 @cindex Time signatures, multiple
502 @lilypond[quote,relative=1,ragged-right,verbatim,fragment]
504 \remove "Timing_translator"
505 \remove "Default_bar_line_engraver"
508 \consists "Timing_translator"
509 \consists "Default_bar_line_engraver"
515 \consists "Timing_translator"
516 \consists "Default_bar_line_engraver"
525 @node Layout tunings within contexts
526 @subsection Layout tunings within contexts
528 Each context is responsible for creating certain types of graphical
529 objects. The settings used for printing these objects are also stored by
530 context. By changing these settings, the appearance of objects can be
533 The syntax for this is
536 \override @var{context}.@var{name} #'@var{property} = #@var{value}
539 Here @var{name} is the name of a graphical object, like @code{Stem} or
540 @code{NoteHead}, and @var{property} is an internal variable of the
541 formatting system (@q{grob property} or @q{layout property}). The latter is a
542 symbol, so it must be quoted. The subsection @ref{Constructing a
543 tweak}, explains what to fill in for @var{name}, @var{property}, and
544 @var{value}. Here we only discuss the functionality of this command.
549 \override Staff.Stem #'thickness = #4.0
553 makes stems thicker (the default is 1.3, with staff line thickness as a
554 unit). Since the command specifies @context{Staff} as context, it only
555 applies to the current staff. Other staves will keep their normal
556 appearance. Here we see the command in action:
558 @lilypond[quote,verbatim,relative=2,fragment]
560 \override Staff.Stem #'thickness = #4.0
566 The @code{\override} command changes the definition of the @code{Stem}
567 within the current @context{Staff}. After the command is interpreted
568 all stems are thickened.
570 Analogous to @code{\set}, the @var{context} argument may be left out,
571 causing the default context @context{Voice} to be used. Adding
572 @code{\once} applies the change during one timestep only.
574 @lilypond[quote,fragment,verbatim,relative=2]
576 \once \override Stem #'thickness = #4.0
581 The @code{\override} must be done before the object is
582 started. Therefore, when altering @emph{Spanner} objects such as slurs
583 or beams, the @code{\override} command must be executed at the moment
584 when the object is created. In this example,
586 @lilypond[quote,fragment,verbatim,relative=2]
587 \override Slur #'thickness = #3.0
589 \override Beam #'thickness = #0.6
594 the slur is fatter but the beam is not. This is because the command for
595 @code{Beam} comes after the Beam is started, so it has no effect.
597 Analogous to @code{\unset}, the @code{\revert} command for a context
598 undoes an @code{\override} command; like with @code{\unset}, it only
599 affects settings that were made in the same context. In other words, the
600 @code{\revert} in the next example does not do anything.
603 \override Voice.Stem #'thickness = #4.0
604 \revert Staff.Stem #'thickness
607 Some tweakable options are called @q{subproperties} and reside inside
608 properties. To tweak those, use commands of the form
610 @c leave this as a long long
612 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
619 \override Stem #'details #'beamed-lengths = #'(4 4 3)
625 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
626 @internalsref{PropertySet}, @internalsref{Backend}, and
627 @internalsref{All layout objects}.
632 The back-end is not very strict in type-checking object properties.
633 Cyclic references in Scheme values for properties can cause hangs
637 @node Changing context default settings
638 @subsection Changing context default settings
640 The adjustments of the previous subsections (@ref{Changing context
641 properties on the fly}, @ref{Modifying context plug-ins}, and
642 @ref{Layout tunings within contexts}) can also be entered separately
643 from the music in the @code{\layout} block,
652 \override Stem #'thickness = #4.0
653 \remove "Time_signature_engraver"
658 The @code{\Staff} command brings in the existing definition of the
659 staff context so that it can be modified.
664 \override Stem #'thickness = #4.0
665 \remove "Time_signature_engraver"
669 affect all staves in the score. Other contexts can be modified
672 The @code{\set} keyword is optional within the @code{\layout} block, so
688 It is not possible to collect context changes in a variable and apply
689 them to a @code{\context} definition by referring to that variable.
691 The @code{\RemoveEmptyStaffContext} will overwrite your current
692 @code{\Staff} settings. If you wish to change the defaults for a
693 staff which uses @code{\RemoveEmptyStaffContext}, you must do so
694 after calling @code{\RemoveEmptyStaffContext}, ie
699 \RemoveEmptyStaffContext
701 \override Stem #'thickness = #4.0
707 @node Defining new contexts
708 @subsection Defining new contexts
710 Specific contexts, like @context{Staff} and @code{Voice}, are made of
711 simple building blocks. It is possible to create new types of
712 contexts with different combinations of engraver plug-ins.
714 The next example shows how to build a different type of
715 @context{Voice} context from scratch. It will be similar to
716 @code{Voice}, but only prints centered slash noteheads. It can be used
717 to indicate improvisation in jazz pieces,
719 @lilypond[quote,ragged-right]
722 \type "Engraver_group"
723 \consists "Note_heads_engraver"
724 \consists "Text_engraver"
725 \consists Pitch_squash_engraver
726 squashedPosition = #0
727 \override NoteHead #'style = #'slash
728 \override Stem #'transparent = ##t
732 \accepts "ImproVoice"
736 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
737 c4 c^"undress" c_"while playing :)" c }
743 These settings are defined within a @code{\context} block inside a
744 @code{\layout} block,
754 In the following discussion, the example input shown should go in place
755 of the @dots{} in the previous fragment.
757 First it is necessary to define a name for the new context:
763 Since it is similar to the @context{Voice}, we want commands that work
764 on (existing) @context{Voice}s to remain working. This is achieved by
765 giving the new context an alias @context{Voice},
771 The context will print notes and instructive texts, so we need to add
772 the engravers which provide this functionality,
775 \consists Note_heads_engraver
776 \consists Text_engraver
779 but we only need this on the center line,
782 \consists Pitch_squash_engraver
783 squashedPosition = #0
786 The @internalsref{Pitch_squash_engraver} modifies note heads (created
787 by @internalsref{Note_heads_engraver}) and sets their vertical
788 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
791 The notes look like a slash, and have no stem,
794 \override NoteHead #'style = #'slash
795 \override Stem #'transparent = ##t
798 All these plug-ins have to cooperate, and this is achieved with a
799 special plug-in, which must be marked with the keyword @code{\type}.
800 This should always be @internalsref{Engraver_group},
803 \type "Engraver_group"
811 \type "Engraver_group"
812 \consists "Note_heads_engraver"
813 \consists "Text_engraver"
814 \consists Pitch_squash_engraver
815 squashedPosition = #0
816 \override NoteHead #'style = #'slash
817 \override Stem #'transparent = ##t
823 Contexts form hierarchies. We want to hang the @context{ImproVoice}
824 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
825 modify the @code{Staff} definition with the @code{\accepts}
836 The opposite of @code{\accepts} is @code{\denies},
837 which is sometimes needed when reusing existing context definitions.
839 Putting both into a @code{\layout} block, like
849 \accepts "ImproVoice"
854 Then the output at the start of this subsection can be entered as
862 c c_"while playing :)"
869 @node Aligning contexts
870 @subsection Aligning contexts
872 New contexts may be aligned above or below exisiting contexts. This
873 could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
877 @findex alignAboveContext
878 @findex alignBelowContext
880 @lilypond[quote,ragged-right]
883 \relative c' \new Staff = "main" {
886 \new Staff \with {alignAboveContext=main} \ossia
894 @node Vertical grouping of grobs
895 @subsection Vertical grouping of grobs
897 The VerticalAlignment and VerticalAxisGroup grobs work together.
898 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
899 etc. VerticalAlignment then vertically aligns the different grobs
900 grouped together by VerticalAxisGroup. There is usually only one
901 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
905 @node The \override command
906 @section The @code{\override} command
908 In the previous section, we have already touched on a command that
909 changes layout details: the @code{\override} command. In this section,
910 we will look in more detail at how to use the command in practice. The
911 general syntax of this command is:
914 \override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
917 This will set the @var{layout_property} of the specified @var{layout_object},
918 which is a member of the @var{context}, to the @var{value}.
921 * Constructing a tweak::
922 * Navigating the program reference::
923 * Layout interfaces::
924 * Determining the grob property::
925 * Objects connected to the input::
926 * Using Scheme code instead of \tweak::
927 * \set versus \override::
933 @node Constructing a tweak
934 @subsection Constructing a tweak
936 Commands which change output generally look like
939 \override Voice.Stem #'thickness = #3.0
943 To construct this tweak we must determine these bits of information:
946 @item the context: here @context{Voice}.
947 @item the layout object: here @code{Stem}.
948 @item the layout property: here @code{thickness}.
949 @item a sensible value: here @code{3.0}.
952 Some tweakable options are called @q{subproperties} and reside inside
953 properties. To tweak those, use commands in the form
956 \override Stem #'details #'beamed-lengths = #'(4 4 3)
959 @cindex internal documentation
960 @cindex finding graphical objects
961 @cindex graphical object descriptions
964 @cindex internal documentation
966 For many properties, regardless of the data type of the property, setting the
967 property to false ( @code{##f} ) will result in turning it off, causing
968 Lilypond to ignore that property entirely. This is particularly useful for
969 turning off grob properties which may otherwise be causing problems.
971 We demonstrate how to glean this information from the notation manual
972 and the program reference.
977 @node Navigating the program reference
978 @subsection Navigating the program reference
980 Suppose we want to move the fingering indication in the fragment
983 @lilypond[quote,fragment,relative=2,verbatim]
989 If you visit the documentation on fingering instructions (in
990 @ref{Fingering instructions}), you will notice:
995 Program reference: @internalsref{Fingering}.
1000 @c outdated info; probably will delete.
1002 This fragment points to two parts of the program reference: a page
1003 on @code{FingerEvent} and one on @code{Fingering}.
1005 The page on @code{FingerEvent} describes the properties of the music
1006 expression for the input @code{-2}. The page contains many links
1007 forward. For example, it says
1010 Accepted by: @internalsref{Fingering_engraver},
1014 That link brings us to the documentation for the Engraver, the
1018 This engraver creates the following layout objects: @internalsref{Fingering}.
1021 In other words, once the @code{FingerEvent}s are interpreted, the
1022 @code{Fingering_engraver} plug-in will process them.
1026 @c I can't figure out what this is supposed to mean. -gp
1028 The @code{Fingering_engraver} is also listed to create
1029 @internalsref{Fingering} objects,
1031 @c old info? it doesn't make any sense to me with our current docs.
1033 second bit of information listed under @b{See also} in the Notation
1038 The programmer's reference is available as an HTML document. It is
1039 highly recommended that you read it in HTML form, either online or
1040 by downloading the HTML documentation. This section will be much more
1041 difficult to understand if you are using the
1045 Follow the link to @internalsref{Fingering}. At the top of the
1049 Fingering objects are created by: @internalsref{Fingering_engraver} and
1050 @internalsref{New_fingering_engraver}.
1053 By following related links inside the program reference, we can follow the
1054 flow of information within the program:
1058 @item @internalsref{Fingering}:
1059 @internalsref{Fingering} objects are created by:
1060 @internalsref{Fingering_engraver}
1062 @item @internalsref{Fingering_engraver}:
1063 Music types accepted: @internalsref{fingering-event}
1065 @item @internalsref{fingering-event}:
1066 Music event type @code{fingering-event} is in Music expressions named
1067 @internalsref{FingerEvent}
1070 This path goes against the flow of information in the program: it
1071 starts from the output, and ends at the input event. You could
1072 also start at an input event, and read with the flow of
1073 information, eventually ending up at the output object(s).
1075 The program reference can also be browsed like a normal document. It
1076 contains chapters on
1078 @internalsref{Music definitions},
1081 @code{Music definitions}
1083 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1084 chapter lists all the definitions used and all properties that may be
1088 @node Layout interfaces
1089 @subsection Layout interfaces
1091 @cindex interface, layout
1092 @cindex layout interface
1095 The HTML page that we found in the previous section describes the
1096 layout object called @internalsref{Fingering}. Such an object is a
1097 symbol within the score. It has properties that store numbers (like
1098 thicknesses and directions), but also pointers to related objects. A
1099 layout object is also called a @emph{Grob}, which is short for Graphical
1100 Object. For more details about Grobs, see @internalsref{grob-interface}.
1102 The page for @code{Fingering} lists the definitions for the
1103 @code{Fingering} object. For example, the page says
1106 @code{padding} (dimension, in staff space):
1112 which means that the number will be kept at a distance of at least 0.5
1116 Each layout object may have several functions as a notational or
1117 typographical element. For example, the Fingering object
1118 has the following aspects
1122 Its size is independent of the horizontal spacing, unlike slurs or beams.
1125 It is a piece of text. Granted, it is usually a very short text.
1128 That piece of text is typeset with a font, unlike slurs or beams.
1131 Horizontally, the center of the symbol should be aligned to the
1132 center of the notehead.
1135 Vertically, the symbol is placed next to the note and the staff.
1138 The vertical position is also coordinated with other superscript
1139 and subscript symbols.
1142 Each of these aspects is captured in so-called @emph{interface}s,
1143 which are listed on the @internalsref{Fingering} page at the bottom
1146 This object supports the following interfaces:
1147 @internalsref{item-interface},
1148 @internalsref{self-alignment-interface},
1149 @internalsref{side-position-interface}, @internalsref{text-interface},
1150 @internalsref{text-script-interface}, @internalsref{font-interface},
1151 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1154 Clicking any of the links will take you to the page of the respective
1155 object interface. Each interface has a number of properties. Some of
1156 them are not user-serviceable (@q{Internal properties}), but others
1159 We have been talking of @emph{the} @code{Fingering} object, but actually it
1160 does not amount to much. The initialization file (see
1161 @rlearning{Default files})
1162 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
1167 (avoid-slur . around)
1168 (slur-padding . 0.2)
1169 (staff-padding . 0.5)
1170 (self-alignment-X . 0)
1171 (self-alignment-Y . 0)
1172 (script-priority . 100)
1173 (stencil . ,ly:text-interface::print)
1174 (direction . ,ly:script-interface::calc-direction)
1175 (font-encoding . fetaNumber)
1176 (font-size . -5) ; don't overlap when next to heads.
1177 (meta . ((class . Item)
1178 (interfaces . (finger-interface
1180 text-script-interface
1182 side-position-interface
1183 self-alignment-interface
1184 item-interface))))))
1188 As you can see, the @code{Fingering} object is nothing more than a
1189 bunch of variable settings, and the webpage in the Program Reference
1190 is directly generated from this definition.
1193 @node Determining the grob property
1194 @subsection Determining the grob property
1196 Recall that we wanted to change the position of the @b{2} in
1198 @lilypond[quote,fragment,relative=2,verbatim]
1204 Since the @b{2} is vertically positioned next to its note, we have to
1205 meddle with the interface associated with this positioning. This is
1206 done using @code{side-position-interface}. The page for this interface
1210 @code{side-position-interface}
1212 Position a victim object (this one) next to other objects (the
1213 support). The property @code{direction} signifies where to put the
1214 victim object relative to the support (left or right, up or down?)
1219 Below this description, the variable @code{padding} is described as
1224 (dimension, in staff space)
1226 Add this much extra space between objects that are next to each other.
1230 By increasing the value of @code{padding}, we can move the
1231 fingering away from the notehead. The following command inserts
1232 3 staff spaces of white
1233 between the note and the fingering:
1235 \once \override Voice.Fingering #'padding = #3
1238 Inserting this command before the Fingering object is created,
1239 i.e., before @code{c2}, yields the following result:
1241 @lilypond[quote,relative=2,fragment,verbatim]
1242 \once \override Voice.Fingering #'padding = #3
1249 In this case, the context for this tweak is @context{Voice}. This
1250 fact can also be deduced from the program reference, for the page for
1251 the @internalsref{Fingering_engraver} plug-in says
1254 Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
1258 @node Objects connected to the input
1259 @subsection Objects connected to the input
1263 In some cases, it is possible to take a short-cut for tuning graphical
1264 objects. For objects that result directly from a piece of the input,
1265 you can use the @code{\tweak} function, for example
1267 @lilypond[relative=2,fragment,verbatim,ragged-right]
1270 \tweak #'color #red d
1272 \tweak #'duration-log #1 a
1273 >4-\tweak #'padding #10 -.
1276 As you can see, properties are set in the objects directly,
1277 without mentioning the grob name or context where this should be
1280 This technique only works for objects that are directly connected to
1281 an @internalsref{Event} from the input, for example
1284 @item note heads, caused by chord-pitch (i.e., notes inside a chord)
1285 @item articulation signs, caused by articulation instructions
1288 It notably does not work for stems and accidentals (these are caused
1289 by note heads, not by music events) or clefs (these are not caused by
1290 music inputs, but rather by the change of a property value).
1292 There are very few objects which are @emph{directly} connected to
1293 output. A normal note (like @code{c4}) is not directly connected
1297 \tweak #'color #red c4
1301 does not change color. See @ref{Displaying music expressions}, for
1305 @node Using Scheme code instead of \tweak
1306 @subsection Using Scheme code instead of @code{\tweak}
1308 The main disadvantage of @code{\tweak} is its syntactical
1309 inflexibility. For example, the following produces a syntax error.
1312 F = \tweak #'font-size #-3 -\flageolet
1320 With other words, @code{\tweak} doesn't behave like an articulation
1321 regarding the syntax; in particular, it can't be attached with
1322 @samp{^} and @samp{_}.
1324 Using Scheme, this problem can be circumvented. The route to the
1325 result is given in @ref{Adding articulation to notes (example)},
1326 especially how to use @code{\displayMusic} as a helping guide.
1329 F = #(let ((m (make-music 'ArticulationEvent
1330 'articulation-type "flageolet")))
1331 (set! (ly:music-property m 'tweaks)
1332 (acons 'font-size -3
1333 (ly:music-property m 'tweaks)))
1342 Here, the @code{tweaks} properties of the flageolet object
1343 @samp{m} (created with @code{make-music}) are extracted with
1344 @code{ly:music-property}, a new key-value pair to change the
1345 font size is prepended to the property list with the
1346 @code{acons} Scheme function, and the result is finally
1347 written back with @code{set!}. The last element of the
1348 @code{let} block is the return value, @samp{m} itself.
1351 @node \set versus \override
1352 @subsection @code{\set} vs. @code{\override}
1354 We have seen two methods of changing properties: @code{\set} and
1355 @code{\override}. There are actually two different kinds of
1358 Contexts can have properties, which are usually named in
1359 @code{studlyCaps}. They mostly control the translation from
1360 music to notatino, eg. @code{localKeySignature} (for determining
1361 whether to print accidentals), @code{measurePosition} (for
1362 determining when to print a barline). Context properties can
1363 change value over time while interpreting a piece of music;
1364 @code{measurePosition} is an obvious example of
1365 this. Context properties are modified with @code{\set}.
1367 There is a special type of context property: the element
1368 description. These properties are named in @code{StudlyCaps}
1369 (starting with capital letters). They contain the
1370 @q{default settings} for said graphical object as an
1371 association list. See @file{scm/@/define@/-grobs@/.scm}
1372 to see what kind of settings there are. Element descriptions
1373 may be modified with @code{\override}.
1375 @code{\override} is actually a shorthand;
1378 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1382 is more or less equivalent to
1384 @c leave this long line -gp
1386 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1389 The value of @code{context} (the alist) is used to initalize
1390 the properties of individual grobs. Grobs also have
1391 properties, named in Scheme style, with
1392 @code{dashed-words}. The values of grob properties change
1393 during the formatting process: formatting basically amounts
1394 to computing properties using callback functions.
1396 @code{fontSize} is a special property: it is equivalent to
1397 entering @code{\override ... #'font-size} for all pertinent
1398 objects. Since this is a common change, the special
1399 property (modified with @code{\set}) was created.
1402 @node Difficult tweaks
1403 @subsection Difficult tweaks
1405 There are a few classes of difficult adjustments.
1411 One type of difficult adjustment is the appearance of spanner objects,
1412 such as slur and tie. Initially, only one of these objects is created,
1413 and they can be adjusted with the normal mechanism. However, in some
1414 cases the spanners cross line breaks. If this happens, these objects
1415 are cloned. A separate object is created for every system that it is
1416 in. These are clones of the original object and inherit all
1417 properties, including @code{\override}s.
1420 In other words, an @code{\override} always affects all pieces of a
1421 broken spanner. To change only one part of a spanner at a line break,
1422 it is necessary to hook into the formatting process. The
1423 @code{after-line-breaking} callback contains the Scheme procedure that
1424 is called after the line breaks have been determined, and layout
1425 objects have been split over different systems.
1427 In the following example, we define a procedure
1428 @code{my-callback}. This procedure
1432 determines if we have been split across line breaks
1434 if yes, retrieves all the split objects
1436 checks if we are the last of the split objects
1438 if yes, it sets @code{extra-offset}.
1441 This procedure is installed into @internalsref{Tie}, so the last part
1442 of the broken tie is translated up.
1444 @lilypond[quote,verbatim,ragged-right]
1445 #(define (my-callback grob)
1447 ; have we been split?
1448 (orig (ly:grob-original grob))
1450 ; if yes, get the split pieces (our siblings)
1451 (siblings (if (ly:grob? orig)
1452 (ly:spanner-broken-into orig) '() )))
1454 (if (and (>= (length siblings) 2)
1455 (eq? (car (last-pair siblings)) grob))
1456 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1459 \override Tie #'after-line-breaking =
1466 When applying this trick, the new @code{after-line-breaking} callback
1467 should also call the old one @code{after-line-breaking}, if there is
1468 one. For example, if using this with @code{Hairpin},
1469 @code{ly:hairpin::after-line-breaking} should also be called.
1472 @item Some objects cannot be changed with @code{\override} for
1473 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1474 and @code{PaperColumn}. They can be changed with the
1475 @code{\overrideProperty} function, which works similar to @code{\once
1476 \override}, but uses a different syntax.
1480 #"Score.NonMusicalPaperColumn" % Grob name
1481 #'line-break-system-details % Property name
1482 #'((next-padding . 20)) % Value
1485 Note, however, that @code{\override}, applied to
1486 @code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
1487 expected within @code{\context} blocks.