GNU LilyPond

Welcome to the home of the GNU Music Typesetter

Node:Tuning groups of grobs, Next:Tuning per grob, Up:Tuning output

Tuning groups of grobs

A grob definition is a Scheme association list, that is stored in a context property. By assigning to that property (using plain \property), you can change the resulting grobs.

c'4 \property Voice.Stem  = #'((meta . ((interfaces . ())))) c'4

The \property assignment effectively empties the definition of the Stem object. One of the effects is that the recipe of how it should be printed is erased, with the effect of rendering it invisible. The above assignment is available as a standard identifier, for the case that you find this useful:

  \property Voice.Stem = \turnOff

This mechanism is fairly crude, since you can only set, but not modify, the definition of a grob. For this reason, there is a more advanced mechanism.

The definition of a grob is actually a list of default grob properties. For example, the definition of the Stem grob (available in scm/grob-description.scm), defines the following values for Stem

        (thickness . 0.8)
        (beamed-lengths . (0.0 2.5 2.0 1.5))
        (Y-extent-callback . ,Stem::height)
        ...

You can add a property on top of the existing definition, or remove a property, thus overriding the system defaults:

c'4 \property Voice.Stem \override #'thickness = #4.0
c'4 \property Voice.Stem \revert #'thickness
c'4

You should balance \override and \revert. If that's too much work, you can use the \set shorthand. It performs a revert followed by an override. The following example gives exactly the same result as the previous one.

c'4 \property Voice.Stem \set #'thickness = #4.0
c'4 \property Voice.Stem \set #'thickness = #0.8
c'4

If you use \set, you must explicitly restore the default.

Formally the syntax for these constructions is

\property context.grobname \override symbol = value
\property context.grobname \set symbol = value
\property context.grobname \revert symbol

If you revert a setting which was not set in the first place, then it has no effect. However, if the setting was set as a system default, it may remove the default value, and this may give surprising results, including crashes. In other words, \override and \revert, must be carefully balanced.

These are examples of correct nesting of \override, \set, \revert.

A clumsy but correct form:

  \override \revert \override \revert \override \revert

Shorter version of the same:

  \override \set \set  \revert

A short form, using only \set. This requires you to know the default value:

  \set \set \set \set to default value

If there is no default (i.e. by default, the grob property is unset), then you can use

  \set \set \set \revert

For the digirati, the grob description is an Scheme association list. Since a Scheme list is a singly linked list, we can treat it as a stack, and \override and \revert are just push and pop operations. This pushing and popping is also used for overriding automatic beaming settings.

BUGS

LilyPond will hang or crash if value contains cyclic references. The backend is not very strict in type-checking grob properties. If you \revert properties that are expected to be set by default, LilyPond may crash.

Some grobs are created at the moment that their context is created. An example of such a grob is the staff itself (i.e. the horizontal lines). You can not change the appearance of the staff symbol by manipulating \property Staff.StaffSymbol. At the moment that \property Staff is interpreted, a Staff context is made, and the StaffSymbol is created before any \override is effective. You can deal with this either overriding properties in a \translator definition, or by using \outputproperty.

Please send GNU LilyPond questions and comments to lilypond-user@gnu.org.

Please send comments on these web pages to lilypond@packages.debian.org

Copyright (c) 1997--2001 Han-Wen Nienhuys and Jan Nieuwenhuizen.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.