Overriding LilyPond grobs
=========================

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


Grobs control typography
------------------------

LilyPond grobs control the typographic details of the score:

<abjad>
staff = Staff("c'4 ( d'4 ) e'4 ( f'4 ) g'4 ( a'4 ) g'2")
</abjad>

<abjad>
f(staff)
</abjad>

<abjad>
show(staff)
</abjad>

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.


Abjad grob-override component plug-ins
--------------------------------------

Abjad lets you work with LilyPond grobs.

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

<abjad>
staff = Staff("c'4 d'4 e'4 f'4 g'4 a'4 g'2")
show(staff)
</abjad>

<abjad>
override(staff).staff_symbol.color = 'blue'
</abjad>

<abjad>
show(staff)
</abjad>

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

<abjad>
leaf = staff[-1]
</abjad>

<abjad>
override(leaf).note_head.color = 'red'
override(leaf).stem.color = 'red'
</abjad>

<abjad>
show(staff)
</abjad>

And so do Abjad spanners:

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

<abjad>
show(staff)
</abjad>


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, simply concatenate the property names with
double-underscores:

<abjad>
staff = Staff()
override(staff).staff_grouper.staff_staff_spacing__basic_distance = 7
f(staff)
</abjad>

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


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
<http://lilypond.org/doc/v2.13/Documentation/internals/all-layout-objects>`__.
