Constructing a tweak - GNU LilyPond

Next: Applyoutput, Previous: Tuning objects, Up: Tuning output

4.17.2 Constructing a tweak

Three pieces of information are required to use \override and \set: the name of the layout object, the context and the name of the property. We demonstrate how to glean this information from the notation manual and the generated documentation.

The generated documentation is a set of HTML pages which should be included if you installed a binary distribution, typically in /usr/share/doc/lilypond. They are also available on the web: go to the LilyPond website, click “Documentation”, select the correct version, and click then “Program reference.” It is advisable to bookmark the local HTML files. They will load faster than the ones on the web. If you use the version from the web, you must check whether the documentation matches the program version: it is generated from the definitions that the program uses, and therefore it is strongly tied to the LilyPond version.

Suppose we want to move the fingering indication in the fragment below:

     c-2
     \stemUp
     f

If you visit the documentation of Fingering (in Fingering instructions), you will notice that there is written:

See also

FingerEvent (lilypond-internals) and Fingering (lilypond-internals).

In other words, the fingerings once entered, are internally stored as FingerEvent music objects. When printed, a Fingering layout object is created for every FingerEvent.

The Fingering object has a number of different functions, and each of those is captured in an interface. The interfaces are listed under Fingering (lilypond-internals) in the program reference.

The Fingering object has a fixed size (item-interface (lilypond-internals)), the symbol is a piece of text (text-interface (lilypond-internals)), whose font can be set (font-interface (lilypond-internals)). It is centered horizontally (self-alignment-interface (lilypond-internals)), it is placed next to other objects (side-position-interface (lilypond-internals)) vertically, and its placement is coordinated with other scripts (text-script-interface (lilypond-internals)). It also has the standard grob-interface (lilypond-internals) (grob stands for Graphical object) with all the variables that come with it. Finally, it denotes a fingering instruction, so it has finger-interface (lilypond-internals).

For the vertical placement, we have to look under side-position-interface:

side-position-interface
Position a victim object (this one) next to other objects (the support). In this case, the property direction signifies where to put the victim object relative to the support (left or right, up or down?)

below this description, the variable padding is described as

padding
(dimension, in staff space)
add this much extra space between objects that are next to each other. Default value: 0.6

By increasing the value of padding, we can move away the fingering. The following command inserts 3 staff spaces of white between the note and the fingering:

     \once \property Voice.Fingering \set #'padding = #3

Inserting this command before the Fingering object is created, i.e. before c2, yields the following result:

     \once \property Voice.Fingering
       \set #'padding = #3
     c-2
     \stemUp
     f

The context name Voice in the example above can be determined as follows. In the documentation for Fingering (lilypond-internals), it says

Fingering grobs are created by: Fingering_engraver (lilypond-internals)

Clicking Fingering_engraver shows the documentation of the module responsible for interpreting the fingering instructions and translating them to a Fingering object. Such a module is called an engraver. The documentation of the Fingering_engraver says

     Fingering_engraver is part of contexts: Voice

so tuning the settings for Fingering should be done with

       \property Voice.Fingering \set ...

Of course, the tweak may also done in a larger context than Voice, for example, Staff (lilypond-internals) or Score (lilypond-internals).