lilypond-learning: Modifying context properties
3.3.4 Modifying context properties
----------------------------------
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 the current context (typically ‘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 ‘#t’,
signs before accidentals ‘#f’
currentBarNumber Integer Set the current bar number ‘50’
doubleSlurs Boolean If true, print slurs both ‘#t’,
above and below notes ‘#f’
instrumentName Text Set the name to be placed at ‘"Cello
the start of the staff I"’
fontSize Real Increase or decrease the font ‘2.4’
size
stanza Text Set the text to print before ‘"2"’
the start of a verse
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 labeled,
but not the second, because we omitted the context name.
<<
\new Staff \relative c'' {
\set Staff.instrumentName = #"Soprano"
c2 c
}
\new Staff \relative c' {
\set instrumentName = #"Alto" % Wrong!
d2 d
}
>>
[image src="" alt="[image of music]" text="image of music" ]
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. In 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. Some text
editors with special support for LilyPond input files document property
names with bullets when you hover them with the mouse, like JEdit with
LilyPondTool, or highlight unknown property names differently, like
ConTEXT. If you do not use an editor with such features, it is
recommended to check the property name in the Internals Reference: see
DONTPRINTYET 
(lilypond-internals)Tunable context properties, or *noteDONTPRINTYET (lilypond-internals)Tunable context properties, or
(lilypond-internals)Contexts.
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'' {
aeses2 aes
}
\new Staff \relative c'' {
\set Staff.extraNatural = ##f
aeses2 aes
}
>>
[image src="" alt="[image of music]" text="image of music" ]
and this turns them off in all staves:
<<
\new Staff \relative c'' {
aeses2 aes
}
\new Staff \relative c'' {
\set Score.extraNatural = ##f
aeses2 aes
}
>>
[image src="" alt="[image of music]" text="image of music" ]
As another example, if ‘clefTransposition’ is set in the ‘Score’
context this immediately changes the value of the transposition in all
current staves and sets a new default value which will be applied to all
staves.
The opposite command, ‘\unset’, effectively removes the property from
the context, which causes most properties to revert to their default
value. Usually ‘\unset’ is not required as a new ‘\set’ command will
achieve what is wanted.
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 most recently set value.
c4 d
% make note heads smaller
\set fontSize = #-4
e4 f |
% make note heads larger
\set fontSize = #2.5
g4 a
% return to default size
\unset fontSize
b4 c |
[image src="" alt="[image of music]" text="image of music" ]
We have now seen how to set the values of several different types of
property. Note that integers and numbers are always 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.
Setting context properties with ‘\with’
.......................................
The default value of context properties may be set at the time the
context is created. Sometimes this is a clearer way of setting 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 default 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'' {
gisis4 gis aeses aes
}
}
\new Staff \with { extraNatural = ##f } {
\relative c'' {
gisis4 gis aeses aes
}
}
>>
[image src="" alt="[image of music]" text="image of music" ]
Properties set in this way may still be changed dynamically using
‘\set’ and returned to the default value set in the ‘\with’ block with
‘\unset’.
So if the ‘fontSize’ property is set in a ‘\with’ clause it sets the
default value of the font size. If it is later changed with ‘\set’,
this new default value may be restored with the ‘\unset fontSize’
command.
Setting context properties with ‘\context’
..........................................
The values of context properties may be set in _all_ contexts of a
particular type, such as all ‘Staff’ contexts, with a single command.
The context type is identified by using its type name, like ‘Staff’,
prefixed by a back-slash: ‘\Staff’. The statement which sets the
property value is the same as that in a ‘\with’ block, introduced above.
It is placed in a ‘\context’ block within a ‘\layout’ block. Each
‘\context’ block will affect all contexts of the type specified
throughout the ‘\score’ or ‘\book’ block in which the ‘\layout’ block
appears. Here is an example to show the format:
\score {
\new Staff {
\relative c'' {
cisis4 e d cis
}
}
\layout {
\context {
\Staff
extraNatural = ##t
}
}
}
[image src="" alt="[image of music]" text="image of music" ]
If the property override is to be applied to all staves within the
score:
\score {
<<
\new Staff {
\relative c'' {
gisis4 gis aeses aes
}
}
\new Staff {
\relative c'' {
gisis4 gis aeses aes
}
}
>>
\layout {
\context {
\Score extraNatural = ##f
}
}
}
[image src="" alt="[image of music]" text="image of music" ]
Context properties set in this way may be overridden for particular
instances of contexts by statements in a ‘\with’ block, and by ‘\set’
commands embedded in music statements.
See also
........
Notation Reference: (lilypond-notation)Changing context default
settings. (lilypond-notation)The set command.
DONTPRINTYET Internals Reference: (lilypond-internals)Contexts, *noteDONTPRINTYET Internals Reference: (lilypond-internals)Contexts,
(lilypond-internals)Tunable context properties.
Info Catalog
lilypond-learning: Engravers explained
lilypond-learning: Contexts and engravers
lilypond-learning: Adding and removing engravers