Next: Adding and removing engravers, Previous: Engravers explained, Up: Contexts and engravers
Contexts are responsible for holding the values of a number of
context properties. Many of them can be changed to
influence the interpretation of the input and so change the
appearance of the output. They are changed by the
\set
command. This takes the form
\set ContextName.propertyName = #value
Where the ContextName is usually Score
,
Staff
or Voice
. It may be omitted,
in which case Voice
is assumed.
The names of context properties consist of words joined together with no hyphens or underscores, all except the first having a capital letter. Here are a few examples of some commonly used ones. There are many more.
propertyName | Type | Function | Example Value
|
---|---|---|---|
extraNatural | Boolean | If true, set extra natural signs before accidentals | #t , #f
|
currentBarNumber | Integer | Set the current bar number | 50
|
doubleSlurs | Boolean | If true, print slurs both above and below notes | #t , #f
|
instrumentName | Text | Set the name to be placed at the start of the staff | "Cello I"
|
fontSize | Real | Increase or decrease the font size | 2.4
|
stanza | Text | Set the text to print before the start of a verse | "2"
|
where a Boolean is either True (#t
) or False (#f
),
an Integer is a positive whole number, a Real is a positive
or negative decimal number, and text is enclosed in double
apostrophes. Note the occurrence of hash signs,
(#
), in two different places – as part of the Boolean
value before the t
or f
, and before value
in the \set
statement. So when a Boolean is being
entered you need to code two hash signs, e.g., ##t
.
Before we can set any of these properties we need to know
in which context they operate. Sometimes this is obvious,
but occasionally it can be tricky. If the wrong context
is specified, no error message is produced, but the expected
action will not take place. For example, the
instrumentName
clearly lives in the Staff context, since
it is the staff that is to be named.
In this example the first staff is labelled, but not the second,
because we omitted the context name.
<< \new Staff \relative c'' { \set Staff.instrumentName = #"Soprano" c4 c } \new Staff \relative c' { \set instrumentName = #"Alto" % Wrong! d4 d } >>
Remember the default context name is Voice, so the second
\set
command set the property instrumentName
in the
Voice context to “Alto”, but as LilyPond does not look
for any such property in the Voice
context, no
further action took place. This is not an error, and no error
message is logged in the log file.
Similarly, if the property name is mis-spelt no error message
is produced, and clearly the expected action cannot be performed.
If fact, you can set any (fictitious) ‘property’ using any
name you like in any context that exists by using the
\set
command. But if the name is not
known to LilyPond it will not cause any action to be taken.
This is one of the reasons why it is highly recommended to
use a context-sensitive editor with syntax highlighting for
editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
since unknown property names will be highlighted differently.
The instrumentName
property will take effect only
if it is set in the Staff
context, but
some properties can be set in more than one context.
For example, the property extraNatural
is by
default set to ##t (true) for all staves.
If it is set to ##f (false) in one particular Staff
context it applies just to the accidentals on that staff.
If it is set to false in the Score
context
it applies to all staves.
So this turns off extra naturals in one staff:
<< \new Staff \relative c'' { ais4 aes } \new Staff \relative c'' { \set Staff.extraNatural = ##f ais4 aes } >>
and this turns them off in all staves:
<< \new Staff \relative c'' { ais4 aes } \new Staff \relative c'' { \set Score.extraNatural = ##f ais4 aes } >>
The value of every property set in this way can be reset
to its original value with the \unset
command.
The \set
and \unset
commands can appear anywhere
in the input file and will take effect from the time they are
encountered until the end of the score or until the property is
\set
or \unset
again. Let's try changing the
font size, which affects the size of the note heads (among
other things) several times. The change is from the default
value, not the current value.
c4 % make note heads smaller \set fontSize = #-4 d e % make note heads larger \set fontSize = #2.5 f g % return to original size \unset fontSize a b
We have now seen how to set the values of several different
types of property. Note that integers and numbers are alway
preceded by a hash sign, #
, while a true or false value
is specified by ##t and ##f, with two hash signs. A text
property should be enclosed in double quotation signs, as above,
although we shall see later that text can actually be specified
in a much more general way by using the very powerful
markup
command.
Context properties may also be set at the time the context is
created. Sometimes this is a clearer way of specifying a
property value if it is to remain fixed for the duration of
the context. When a context is created with a \new
command it may be followed immediately by a
\with { .. }
block in which the property values are
set. For example, if we wish to suppress the printing of
extra naturals for the duration of a staff we would write:
\new Staff \with { extraNatural = ##f }
like this:
<< \new Staff \relative c'' { gis ges aes ais } \new Staff \with { extraNatural = ##f } \relative c'' { gis ges aes ais } >>
In effect this overrides the default value of the property. It
may still be changed dynamically using \set
and returned
to its (new) default value with \unset
.
Next: Adding and removing engravers, Previous: Engravers explained, Up: Contexts and engravers
This page is for LilyPond-2.11.40 (development-branch).
Report errors to http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs.
Your suggestions for the documentation are welcome.