For years, I have thought of writing a short introduction to the
art of setting properties in LilyPond. Here comes a first attempt.
Feel free to use it as a draft for a section in the manual if you
find it useful.
What You Need to Know About Property Settings
=
=
The default behaviour of LilyPond can be modified by setting
different properties. There are different types of properties
and the syntax is slightly different depending on the type
of property. Also, there are several different ways to set
a property.
Different ways of setting a property
Here, we describe briefly the syntax for the different methods to
set a property. We show the syntax for setting an object property,
but the same idea applies to context properties, as will be described
below.
* Setting a property that only applies to the next note (or the next
whatever):
\once \property contextname.objectname \set #'propname = #value
For example, if you want the next note head to be diamond shaped, do
\once \property Voice.NoteHead \set #'style = #'diamond
* Setting a property that applies from now on:
\property contextname.objectname \set #'propname = #value
The 'contextname' describes the scope of the setting. If you say
\property Score..., then the settings applies to all contexts of
the score, if you say \property Staff..., then it applies to the
current Staff context and all contexts within it (but not to other
Staff contexts), and so on.
For example, to make all coming slurs in the current stave dashed, do
\property Staff.Slur \set #'dashed = #1
When you use the \set command, the current value will be
overwritten. If, instead, you say
\property contextname.objectname \override #'propname = #value
LilyPond will remember the old value and you can go back
to the previous value by doing
\property contextname.objectname \revert #'propname
* Setting a property that applies to a complete score:
If you want to set a property that applies to a complete score,
then it's often most convenient to set a property in the
\paper{...} definition. For property settings of objects
that are created before the first note, this may also be
the only way (well, see \applycontext below) to set the
property.
\score{
...
\paper{
...
\translator{
\ScoreContext
objectname \set #'propname = #value
...
}
}
}
What happens here, is that you actually change the definition of
how your contexts should behave. The \ScoreContext is an
identifier that contains the default definition of how what a
Score context should do. If you only say \translator{\ScoreContext},
you will tell LilyPond to use exactly this definition as soon as
it creates a Score context. When adding lines in the \translator{...},
you modify this behaviour. (Note that the \ScoreContext identifier
itself will not be changed, though, so if you want to make more
modifications, you have to do them within the same \translator{...}
block.)
All properties of a context are inherited to all contexts created
within it, so setting properties for the \Score context means that
it will be applied also to all other contexts (unless they are
explicitly set differently within the definition of some other
context). So, normally you can do all the settings as described
above, but if you specifically have to do a property setting at
the Voice context level, you could do
\translator{
\VoiceContext
...
}
In the syntax example above, we have placed the \paper{...}
definition within a \score{...}, but if it is placed outside
the \score{...}, it will apply to all subsequent \score{...}
blocks within the file.
* Advanced techniques for property settings:
Normally, a property has to be set before the actual object
it applies to is created. If you know the Scheme programming
language, you can modify an already existing object using
the \applyoutput function. See the documentation of \applyoutput
and the generic-output-property.ly example in the Regression
Test document.
Different types of properties
=
There are basically three types of properties:
- Music properties
- Context properties
- Object properties
The music objects and music properties are used in the input part
of LilyPond to store the information of the input files. As a
normal user, you will almost never have to fiddle with these directly.
The context properties describe how the different contexts should
work when translating your input to graphical objects in the output
layout.
The object properties describe exactly how each graphical object
should be typeset.
Above, we described how to set object properties. The syntax for
setting context properties is very similar:
\property contextname.propname = #value
For example, to set the instrument name of the current stave, do
\property Staff.instrument = #Clarinet
and to tell LilyPond to print a key signature every time
time the clef is
