5. Overriding LilyPond grobs

>>> import abjad

LilyPond models music notation as a collection of graphic objects or grobs.

5.1. Grobs control typography

LilyPond grobs control the typographic details of the score:

>>> staff = abjad.Staff("c'4 ( d'4 ) e'4 ( f'4 ) g'4 ( a'4 ) g'2")
>>> f(staff)
\new Staff {
    c'4 (
    d'4 )
    e'4 (
    f'4 )
    g'4 (
    a'4 )
>>> show(staff)

In the example above LilyPond creates a grob for every printed glyph. This includes the clef and time signature as well as the note-heads, stems and slurs. If the example included beams, articulations or an explicit key signature then LilyPond would create grobs for those as well.

5.2. Abjad grob-override component plug-ins

Abjad lets you work with LilyPond grobs.

All Abjad containers have a grob-override plug-in:

>>> staff = abjad.Staff("c'4 d'4 e'4 f'4 g'4 a'4 g'2")
>>> show(staff)
>>> abjad.override(staff).staff_symbol.color = 'blue'
>>> show(staff)

All Abjad leaves have a grob-override plug-in, too:

>>> leaf = staff[-1]
>>> override(leaf).note_head.color = 'red'
>>> override(leaf).stem.color = 'red'
>>> show(staff)

And so do Abjad spanners:

>>> slur = abjad.Slur()
>>> attach(slur, staff[:])
>>> abjad.override(slur).slur.color = 'red'
>>> show(staff)

5.3. Nested Grob properties can be overriden

In the above example, staff_symbol, note_head and stem correspond to the LilyPond grobs StaffSymbol, NoteHead and Stem, while color in each case is the color properties of that graphic object.

It is not uncommon in LilyPond scores to see more complex overrides, consisting of a grob name and a list of two or more property names:

\override StaffGrouper #'staff-staff-spacing #'basic-distance = #7

To achieve the Abjad equivalent, concatenate the property names with double-underscores:

>>> staff = abjad.Staff()
>>> abjad.override(staff).staff_grouper.staff_staff_spacing__basic_distance = 7
>>> f(staff)
\new Staff \with {
    \override StaffGrouper.staff-staff-spacing.basic-distance = #7
} {

Abjad will explode the double-underscore delimited Python property into a LilyPond property list.

5.4. Check the LilyPond docs

New grobs are added to LilyPond from time to time.

For a complete list of LilyPond grobs see the LilyPond documentation.