The definition of an object is a list of default object
properties. For example, the definition of the Stem object (available
in scm/define-grobs.scm
), includes the following definitions
for Stem:
(thickness . 1.3) (beamed-lengths . (0.0 2.5 2.0 1.5)) (Y-extent-callback . ,Stem::height) ...
Adding variables on top of this existing definition overrides the system default, and alters the resulting appearance of the layout object.
Changing a variable for only one object is commonly achieved with
\once
:
\once \property context.objectname \override symbol = valueHere symbol is a Scheme expression of symbol type, context and objectname is a string and value is a Scheme expression. This command applies a setting only during one moment in the score.
In the following example, only one Stem object is changed from its original setting:
c4 \once \property Voice.Stem \set #'thickness = #4 c4 c4
For changing more objects, the same command, without \once
can
be used:
\property context.objectname \override symbol = valueThis command adds
symbol =
value
to the definition
of objectname in the context context, and this definition
stays in place until it is removed.
An existing definition may be removed by the following command:
\property context.objectname \revert symbolAll
\override
and \revert
commands should be balanced.
The \set
shorthand performs a revert followed by an override,
and is often more convenient to use
\property context.objectname \set symbol = value
Some examples:
c'4 \property Voice.Stem \override #'thickness = #4.0 c'4 c'4 \property Voice.Stem \revert #'thickness c'4
The following example gives exactly the same result as the previous one (assuming the system default for stem thickness is 1.3):
c'4 \property Voice.Stem \set #'thickness = #4.0 c'4 c'4 \property Voice.Stem \set #'thickness = #1.3 c'4
Reverting a setting which was not set in the first place has no
effect. However, if the setting was set as a system default, this may
remove the default value, and this may give surprising results,
including crashes. In other words, \override
and
\revert
must be carefully balanced. The following are examples
of correct nesting of \override
, \set
, \revert
:
\override \revert \override \revert \override \revert
\override \set \set \revert
\set
. This requires you to know the
default value:
\set \set \set \set to default value
\set \set \set \revert
The object 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 push and pop
operations. The association list is stored in a normal context
property, hence
\property Voice.NoteHead = #'()will effectively erase NoteHeads from the current Voice. Typically, this will blank the object. However, this mechanism should not be used: it may cause crashes or other anomalous behavior.
The backend is not very strict in type-checking object properties. Cyclic references in Scheme values for properties cause hangs and/or crashes. Reverting properties that are system defaults may also lead to crashes.
This page is for LilyPond-2.0.0 (stable-branch).