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 Internals Reference
25 The controls available for tuning are described in a separate
28 Internals Reference manual.
31 @ref{Top,Internals 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 @code{Voice},
116 @code{Staff}, and @code{Score}. They are hierarchical, for
117 example: a @code{Staff} can contain many @code{Voice}s, and a
118 @code{Score} can contain many @code{Staff} contexts.
121 @sourceimage{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 @code{Voice} context may introduce an
127 accidental and then the @code{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 @code{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 @code{Score}
134 and @code{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 @code{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 @code{Voice}
282 \applyOutput #'@var{context} #@var{function} % apply to Voice
285 To have it interpreted at the @code{Score} or @code{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 @code{ChordNames}, @code{Voice}, or
324 @code{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 @code{Staff}, then the change would also apply to all
348 @code{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 Internals Reference @expansion{} Translation @expansion{} Engravers.
437 Every context described in
439 @internalsref{Contexts}
442 Internals 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 @code{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 @code{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 @code{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 @code{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 @code{Voice} context from scratch. It will be similar to
716 @code{Voice}, but only prints centered slash note heads. 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 @code{Voice}, we want commands that work
764 on (existing) @code{Voice}s to remain working. This is achieved by
765 giving the new context an alias @code{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 @code{ImproVoice}
824 under @code{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
876 FIXME: this section doens't work in pdf. (?)
879 @findex alignAboveContext
880 @findex alignBelowContext
882 @lilypond[quote,ragged-right]
885 \relative c' \new Staff = "main" {
888 \new Staff \with {alignAboveContext=main} \ossia
896 @node Vertical grouping of grobs
897 @subsection Vertical grouping of grobs
899 The VerticalAlignment and VerticalAxisGroup grobs work together.
900 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
901 etc. VerticalAlignment then vertically aligns the different grobs
902 grouped together by VerticalAxisGroup. There is usually only one
903 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
907 @node The \override command
908 @section The @code{\override} command
910 In the previous section, we have already touched on a command that
911 changes layout details: the @code{\override} command. In this section,
912 we will look in more detail at how to use the command in practice. The
913 general syntax of this command is:
916 \override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
919 This will set the @var{layout_property} of the specified @var{layout_object},
920 which is a member of the @var{context}, to the @var{value}.
923 * Constructing a tweak::
924 * Navigating the program reference::
925 * Layout interfaces::
926 * Determining the grob property::
927 * Objects connected to the input::
928 * Using Scheme code instead of \tweak::
929 * \set versus \override::
935 @node Constructing a tweak
936 @subsection Constructing a tweak
938 Commands which change output generally look like
941 \override Voice.Stem #'thickness = #3.0
945 To construct this tweak we must determine these bits of information:
948 @item the context: here @code{Voice}.
949 @item the layout object: here @code{Stem}.
950 @item the layout property: here @code{thickness}.
951 @item a sensible value: here @code{3.0}.
954 Some tweakable options are called @q{subproperties} and reside inside
955 properties. To tweak those, use commands in the form
958 \override Stem #'details #'beamed-lengths = #'(4 4 3)
961 @cindex internal documentation
962 @cindex finding graphical objects
963 @cindex graphical object descriptions
966 @cindex internal documentation
968 For many properties, regardless of the data type of the property, setting the
969 property to false ( @code{##f} ) will result in turning it off, causing
970 Lilypond to ignore that property entirely. This is particularly useful for
971 turning off grob properties which may otherwise be causing problems.
973 We demonstrate how to glean this information from the notation manual
974 and the program reference.
979 @node Navigating the program reference
980 @subsection Navigating the program reference
982 Suppose we want to move the fingering indication in the fragment
985 @lilypond[quote,fragment,relative=2,verbatim]
991 If you visit the documentation on fingering instructions (in
992 @ref{Fingering instructions}), you will notice:
997 Internals Reference: @internalsref{Fingering}.
1002 @c outdated info; probably will delete.
1004 This fragment points to two parts of the program reference: a page
1005 on @code{FingerEvent} and one on @code{Fingering}.
1007 The page on @code{FingerEvent} describes the properties of the music
1008 expression for the input @code{-2}. The page contains many links
1009 forward. For example, it says
1012 Accepted by: @internalsref{Fingering_engraver},
1016 That link brings us to the documentation for the Engraver, the
1020 This engraver creates the following layout objects: @internalsref{Fingering}.
1023 In other words, once the @code{FingerEvent}s are interpreted, the
1024 @code{Fingering_engraver} plug-in will process them.
1028 @c I can't figure out what this is supposed to mean. -gp
1030 The @code{Fingering_engraver} is also listed to create
1031 @internalsref{Fingering} objects,
1033 @c old info? it doesn't make any sense to me with our current docs.
1035 second bit of information listed under @b{See also} in the Notation
1040 The programmer's reference is available as an HTML document. It is
1041 highly recommended that you read it in HTML form, either online or
1042 by downloading the HTML documentation. This section will be much more
1043 difficult to understand if you are using the
1047 Follow the link to @internalsref{Fingering}. At the top of the
1051 Fingering objects are created by: @internalsref{Fingering_engraver} and
1052 @internalsref{New_fingering_engraver}.
1055 By following related links inside the program reference, we can follow the
1056 flow of information within the program:
1060 @item @internalsref{Fingering}:
1061 @internalsref{Fingering} objects are created by:
1062 @internalsref{Fingering_engraver}
1064 @item @internalsref{Fingering_engraver}:
1065 Music types accepted: @internalsref{fingering-event}
1067 @item @internalsref{fingering-event}:
1068 Music event type @code{fingering-event} is in Music expressions named
1069 @internalsref{FingerEvent}
1072 This path goes against the flow of information in the program: it
1073 starts from the output, and ends at the input event. You could
1074 also start at an input event, and read with the flow of
1075 information, eventually ending up at the output object(s).
1077 The program reference can also be browsed like a normal document. It
1078 contains chapters on
1080 @internalsref{Music definitions},
1083 @code{Music definitions}
1085 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1086 chapter lists all the definitions used and all properties that may be
1090 @node Layout interfaces
1091 @subsection Layout interfaces
1093 @cindex interface, layout
1094 @cindex layout interface
1097 The HTML page that we found in the previous section describes the
1098 layout object called @internalsref{Fingering}. Such an object is a
1099 symbol within the score. It has properties that store numbers (like
1100 thicknesses and directions), but also pointers to related objects. A
1101 layout object is also called a @emph{Grob}, which is short for Graphical
1102 Object. For more details about Grobs, see @internalsref{grob-interface}.
1104 The page for @code{Fingering} lists the definitions for the
1105 @code{Fingering} object. For example, the page says
1108 @code{padding} (dimension, in staff space):
1114 which means that the number will be kept at a distance of at least 0.5
1118 Each layout object may have several functions as a notational or
1119 typographical element. For example, the Fingering object
1120 has the following aspects
1124 Its size is independent of the horizontal spacing, unlike slurs or beams.
1127 It is a piece of text. Granted, it is usually a very short text.
1130 That piece of text is typeset with a font, unlike slurs or beams.
1133 Horizontally, the center of the symbol should be aligned to the
1134 center of the note head.
1137 Vertically, the symbol is placed next to the note and the staff.
1140 The vertical position is also coordinated with other superscript
1141 and subscript symbols.
1144 Each of these aspects is captured in so-called @emph{interface}s,
1145 which are listed on the @internalsref{Fingering} page at the bottom
1148 This object supports the following interfaces:
1149 @internalsref{item-interface},
1150 @internalsref{self-alignment-interface},
1151 @internalsref{side-position-interface}, @internalsref{text-interface},
1152 @internalsref{text-script-interface}, @internalsref{font-interface},
1153 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1156 Clicking any of the links will take you to the page of the respective
1157 object interface. Each interface has a number of properties. Some of
1158 them are not user-serviceable (@q{Internal properties}), but others
1161 We have been talking of @emph{the} @code{Fingering} object, but actually it
1162 does not amount to much. The initialization file (see
1163 @rlearning{Default files})
1164 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
1169 (avoid-slur . around)
1170 (slur-padding . 0.2)
1171 (staff-padding . 0.5)
1172 (self-alignment-X . 0)
1173 (self-alignment-Y . 0)
1174 (script-priority . 100)
1175 (stencil . ,ly:text-interface::print)
1176 (direction . ,ly:script-interface::calc-direction)
1177 (font-encoding . fetaNumber)
1178 (font-size . -5) ; don't overlap when next to heads.
1179 (meta . ((class . Item)
1180 (interfaces . (finger-interface
1182 text-script-interface
1184 side-position-interface
1185 self-alignment-interface
1186 item-interface))))))
1190 As you can see, the @code{Fingering} object is nothing more than a
1191 bunch of variable settings, and the webpage in the Internals Reference
1192 is directly generated from this definition.
1195 @node Determining the grob property
1196 @subsection Determining the grob property
1198 Recall that we wanted to change the position of the @b{2} in
1200 @lilypond[quote,fragment,relative=2,verbatim]
1206 Since the @b{2} is vertically positioned next to its note, we have to
1207 meddle with the interface associated with this positioning. This is
1208 done using @code{side-position-interface}. The page for this interface
1212 @code{side-position-interface}
1214 Position a victim object (this one) next to other objects (the
1215 support). The property @code{direction} signifies where to put the
1216 victim object relative to the support (left or right, up or down?)
1221 Below this description, the variable @code{padding} is described as
1226 (dimension, in staff space)
1228 Add this much extra space between objects that are next to each other.
1232 By increasing the value of @code{padding}, we can move the
1233 fingering away from the note head. The following command inserts
1234 3 staff spaces of white
1235 between the note and the fingering:
1237 \once \override Voice.Fingering #'padding = #3
1240 Inserting this command before the Fingering object is created,
1241 i.e., before @code{c2}, yields the following result:
1243 @lilypond[quote,relative=2,fragment,verbatim]
1244 \once \override Voice.Fingering #'padding = #3
1251 In this case, the context for this tweak is @code{Voice}. This
1252 fact can also be deduced from the program reference, for the page for
1253 the @internalsref{Fingering_engraver} plug-in says
1256 Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
1260 @node Objects connected to the input
1261 @subsection Objects connected to the input
1265 In some cases, it is possible to take a short-cut for tuning graphical
1266 objects. For objects that result directly from a piece of the input,
1267 you can use the @code{\tweak} function, for example
1269 @lilypond[relative=2,fragment,verbatim,ragged-right]
1272 \tweak #'color #red d
1274 \tweak #'duration-log #1 a
1275 >4-\tweak #'padding #10 -.
1278 As you can see, properties are set in the objects directly,
1279 without mentioning the grob name or context where this should be
1282 This technique only works for objects that are directly connected to
1283 an @internalsref{Event} from the input, for example
1286 @item note heads, caused by chord-pitch (i.e., notes inside a chord)
1287 @item articulation signs, caused by articulation instructions
1290 It notably does not work for stems and accidentals (these are caused
1291 by note heads, not by music events) or clefs (these are not caused by
1292 music inputs, but rather by the change of a property value).
1294 There are very few objects which are @emph{directly} connected to
1295 output. A normal note (like @code{c4}) is not directly connected
1299 \tweak #'color #red c4
1303 does not change color. See @ref{Displaying music expressions}, for
1307 @node Using Scheme code instead of \tweak
1308 @subsection Using Scheme code instead of @code{\tweak}
1310 The main disadvantage of @code{\tweak} is its syntactical
1311 inflexibility. For example, the following produces a syntax error.
1314 F = \tweak #'font-size #-3 -\flageolet
1322 With other words, @code{\tweak} doesn't behave like an articulation
1323 regarding the syntax; in particular, it can't be attached with
1324 @code{^} and @code{_}.
1326 Using Scheme, this problem can be circumvented. The route to the
1327 result is given in @ref{Adding articulation to notes (example)},
1328 especially how to use @code{\displayMusic} as a helping guide.
1331 F = #(let ((m (make-music 'ArticulationEvent
1332 'articulation-type "flageolet")))
1333 (set! (ly:music-property m 'tweaks)
1334 (acons 'font-size -3
1335 (ly:music-property m 'tweaks)))
1344 Here, the @code{tweaks} properties of the flageolet object
1345 @code{m} (created with @code{make-music}) are extracted with
1346 @code{ly:music-property}, a new key-value pair to change the
1347 font size is prepended to the property list with the
1348 @code{acons} Scheme function, and the result is finally
1349 written back with @code{set!}. The last element of the
1350 @code{let} block is the return value, @code{m} itself.
1353 @node \set versus \override
1354 @subsection @code{\set} vs. @code{\override}
1356 We have seen two methods of changing properties: @code{\set} and
1357 @code{\override}. There are actually two different kinds of
1360 Contexts can have properties, which are usually named in
1361 @code{studlyCaps}. They mostly control the translation from
1362 music to notatino, eg. @code{localKeySignature} (for determining
1363 whether to print accidentals), @code{measurePosition} (for
1364 determining when to print a bar line). Context properties can
1365 change value over time while interpreting a piece of music;
1366 @code{measurePosition} is an obvious example of
1367 this. Context properties are modified with @code{\set}.
1369 There is a special type of context property: the element
1370 description. These properties are named in @code{StudlyCaps}
1371 (starting with capital letters). They contain the
1372 @q{default settings} for said graphical object as an
1373 association list. See @file{scm/@/define@/-grobs@/.scm}
1374 to see what kind of settings there are. Element descriptions
1375 may be modified with @code{\override}.
1377 @code{\override} is actually a shorthand;
1380 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1384 is more or less equivalent to
1386 @c leave this long line -gp
1388 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1391 The value of @code{context} (the alist) is used to initalize
1392 the properties of individual grobs. Grobs also have
1393 properties, named in Scheme style, with
1394 @code{dashed-words}. The values of grob properties change
1395 during the formatting process: formatting basically amounts
1396 to computing properties using callback functions.
1398 @code{fontSize} is a special property: it is equivalent to
1399 entering @code{\override ... #'font-size} for all pertinent
1400 objects. Since this is a common change, the special
1401 property (modified with @code{\set}) was created.
1404 @node Difficult tweaks
1405 @subsection Difficult tweaks
1407 There are a few classes of difficult adjustments.
1413 One type of difficult adjustment is the appearance of spanner objects,
1414 such as slur and tie. Initially, only one of these objects is created,
1415 and they can be adjusted with the normal mechanism. However, in some
1416 cases the spanners cross line breaks. If this happens, these objects
1417 are cloned. A separate object is created for every system that it is
1418 in. These are clones of the original object and inherit all
1419 properties, including @code{\override}s.
1422 In other words, an @code{\override} always affects all pieces of a
1423 broken spanner. To change only one part of a spanner at a line break,
1424 it is necessary to hook into the formatting process. The
1425 @code{after-line-breaking} callback contains the Scheme procedure that
1426 is called after the line breaks have been determined, and layout
1427 objects have been split over different systems.
1429 In the following example, we define a procedure
1430 @code{my-callback}. This procedure
1434 determines if we have been split across line breaks
1436 if yes, retrieves all the split objects
1438 checks if we are the last of the split objects
1440 if yes, it sets @code{extra-offset}.
1443 This procedure is installed into @internalsref{Tie}, so the last part
1444 of the broken tie is translated up.
1446 @lilypond[quote,verbatim,ragged-right]
1447 #(define (my-callback grob)
1449 ; have we been split?
1450 (orig (ly:grob-original grob))
1452 ; if yes, get the split pieces (our siblings)
1453 (siblings (if (ly:grob? orig)
1454 (ly:spanner-broken-into orig) '() )))
1456 (if (and (>= (length siblings) 2)
1457 (eq? (car (last-pair siblings)) grob))
1458 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1461 \override Tie #'after-line-breaking =
1468 When applying this trick, the new @code{after-line-breaking} callback
1469 should also call the old one @code{after-line-breaking}, if there is
1470 one. For example, if using this with @code{Hairpin},
1471 @code{ly:hairpin::after-line-breaking} should also be called.
1474 @item Some objects cannot be changed with @code{\override} for
1475 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1476 and @code{PaperColumn}. They can be changed with the
1477 @code{\overrideProperty} function, which works similar to @code{\once
1478 \override}, but uses a different syntax.
1482 #"Score.NonMusicalPaperColumn" % Grob name
1483 #'line-break-system-details % Property name
1484 #'((next-padding . 20)) % Value
1487 Note, however, that @code{\override}, applied to
1488 @code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
1489 expected within @code{\context} blocks.