[ << Changing defaults ]	[Top][Contents][Index][ ? ]			[ Notation manual tables >> ]
[ < set versus override ]		[  Up : Modifying properties ]	[ Useful concepts and properties > ]

5.3.6 Modifying alists

Some user-configurable properties are internally represented as alists (association lists), which store pairs of keys and values. The structure of an alist is:

'((key1 . value1)
  (key2 . value2)
  (key3 . value3)
  …)

If an alist is a grob property or \paper variable, its keys can be modified individually without affecting other keys.

For example, to reduce the space between adjacent staves in a staff-group, use the staff-staff-spacing property of the StaffGrouper grob. The property is an alist with four keys: padding, space, minimum-distance, and stretchability. Three of the four keys have initialized default values; these are listed in the “Backend” section of the Internals Reference (see StaffGrouper):

'((space . 9) (minimum-distance . 7) (padding . 1))

One way to bring the staves closer together is by reducing the value of the space key (9) to match the value of minimum-distance (7). To modify a single key individually, use a nested declaration:

% default space between staves
\new PianoStaff <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

% reduced space between staves
\new PianoStaff \with {
  % this is the nested declaration
  \override StaffGrouper #'staff-staff-spacing #'space = #7
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

Using a nested declaration will update the specified key (such as space in the above example) without altering any other keys already set for the same property.

Now suppose we want the staves to be as close as possible without overlapping. The simplest way to do this is to set all four alist keys to zero. However, it is not necessary to enter four nested declarations, one for each key. Instead, the property can be completely re-defined with one declaration, as an alist:

\new PianoStaff \with {
  \override StaffGrouper #'staff-staff-spacing =
    #'((padding . 0)
       (space . 0)
       (minimum-distance . 0)
       (stretchability . 0))
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

Note that any keys not explicitly listed in the alist definition will be reset to their default-when-unset values. In the case of staff-staff-spacing, any unset key-values would be reset to zero (except stretchability, which takes the value of space when unset). Thus the following two declarations are equivalent:

\override StaffGrouper #'staff-staff-spacing =
  #'((space . 7))

\override StaffGrouper #'staff-staff-spacing =
  #'((padding . 0)
     (space . 7)
     (minimum-distance . 0)
     (stretchability . 7))

One (possibly unintended) consequence of this is the removal of any initialized default values that are set in an initialization file and loaded each time an input file is compiled. In the above example, the initialized default values for padding and minimum-distance (defined in ‘scm/define-grobs.scm’) are reset to their default-when-unset values (zero for both keys). Defining a property or variable as an alist (of any size) will always reset all unset key-values to their default-when-unset values. Unless this is the intended result, it is safer to update key-values individually with a nested declaration.

---

[ << Changing defaults ]	[Top][Contents][Index][ ? ]			[ Notation manual tables >> ]
[ < set versus override ]		[  Up : Modifying properties ]	[ Useful concepts and properties > ]

Andere Sprachen: français.

<< Back to Documentation Index

LilyPond — Notation Reference