<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<html lang="en">
<head>
<title>Modifying context properties - GNU LilyPond Learning Manual</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="GNU LilyPond Learning Manual">
<meta name="generator" content="makeinfo 4.11">
<link title="Top" rel="start" href="index.de.html#Top">
<link rel="up" href="Contexts-and-engravers.de.html#Contexts-and-engravers" title="Contexts and engravers">
<link rel="prev" href="Engravers-explained.de.html#Engravers-explained" title="Engravers explained">
<link rel="next" href="Adding-and-removing-engravers.de.html#Adding-and-removing-engravers" title="Adding and removing engravers">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1999--2007 by the authors
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections. A copy of the license is
included in the section entitled ``GNU Free Documentation
License''.
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
hr { border:0; height:1; color: #000000; background-color: #000000; }
/* hr {
border: none;
height: 1px;
color: #666666;
background-color: #666666;
}
body {
border-left: 1px solid #666666;
border-right: 1px solid #666666;
color: #332d28;
margin-right: auto;
margin-left: auto;
width: 60em;
list-style-type: square;
font-family: Arial,Helvetica,sans-serif;
padding-right: 1em;
padding-left: 1em;
}
a {
border-bottom: 1px dashed #344242;
text-decoration: none;
color: #344242;
}
a:link {
text-decoration: none;
}
a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
a:active {
border-bottom: 1px solid #00cccc;
color: #00cccc;
}
a:hover {
border-bottom: 1px solid #1d7b85;
color: #1d7b85;
}
blockquote {
border: 1px solid #cccccc;
padding: 3px;
width: 40em;
}
.node {
border-left: 1px solid #666666;
margin: -0.5em 0px 1em;
padding: 2px 1px 0px;
font-style: italic;
}
.node a {
border: none;
text-decoration: underline;
font-style: normal;
font-weight: bold;
}
.verbatim {
font-family: "Courier New",Courier,monospace;
}
.unnumberedsubsubsec {
font-size: large;
color: #1d7b85;
}
.subsubheading {
font-size: large;
color: #3b220d;
}
.contents {
border: 1px dashed #339999;
margin: 3px 2em;
list-style-type: square;
padding-right: 1em;
width: 40em;
background-color: #fcfff9;
}
.contents a {
border-bottom: 1px dashed #423d34;
text-decoration: none;
color: #423d34;
}
.contents a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
.contents a:active {
border-bottom: 1px solid #f0d86d;
color: #f0d86d;
}
.contents a:hover {
border-bottom: 1px solid #3b220d;
color: #3b220d;
}
.menu {
border-left: 1px dashed #339999;
margin: 3px 2em 1em;
list-style-type: square;
padding-left: 1.4em;
width: 40em;
}
.unnumbered {
}
h2 {
font-size: x-large;
color: #1d7b85;
}
*/
--></style>
</head>
<BODY BGCOLOR=WHITE TEXT=BLACK>
<div class="node">
<p>
<a name="Modifying-context-properties"></a>
Next: <a rel="next" accesskey="n" href="Adding-and-removing-engravers.de.html#Adding-and-removing-engravers">Adding and removing engravers</a>,
Previous: <a rel="previous" accesskey="p" href="Engravers-explained.de.html#Engravers-explained">Engravers explained</a>,
Up: <a rel="up" accesskey="u" href="Contexts-and-engravers.de.html#Contexts-and-engravers">Contexts and engravers</a>
<hr>
</div>
<h4 class="subsection">3.3.4 Modifying context properties</h4>
<p><a name="index-context-properties-296"></a><a name="index-context-properties_002c-modifying-297"></a><a name="index-modifying-context-properties-298"></a><a name="index-g_t_005cset-299"></a><a name="index-g_t_005cset-300"></a>
<a name="index-g_t_005cunset-301"></a><a name="index-g_t_005cunset-302"></a>
<p>Contexts are responsible for holding the values of a number of
context <em>properties</em>. 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
<code>\set</code> command. This takes the form
<pre class="example">\set <em>ContextName</em>.<em>propertyName</em> = #<em>value</em>
</pre>
<p>Where the <em>ContextName</em> is usually <code>Score</code>,
<code>Staff</code> or <code>Voice</code>. It may be omitted,
in which case <code>Voice</code> is assumed.
<p>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.
<!-- attempt to force this onto a new page -->
<p><table summary=""><tr align="left"><th valign="top" width="25%">propertyName
</th><th valign="top" width="15%">Type
</th><th valign="top" width="45%">Function
</th><th valign="top" width="15%">Example Value
<br></th></tr><tr align="left"><td valign="top" width="25%">extraNatural
</td><td valign="top" width="15%">Boolean
</td><td valign="top" width="45%">If true, set extra natural signs before accidentals
</td><td valign="top" width="15%"><code>#t</code>, <code>#f</code>
<br></td></tr><tr align="left"><td valign="top" width="25%">currentBarNumber
</td><td valign="top" width="15%">Integer
</td><td valign="top" width="45%">Set the current bar number
</td><td valign="top" width="15%"><code>50</code>
<br></td></tr><tr align="left"><td valign="top" width="25%">doubleSlurs
</td><td valign="top" width="15%">Boolean
</td><td valign="top" width="45%">If true, print slurs both above and below notes
</td><td valign="top" width="15%"><code>#t</code>, <code>#f</code>
<br></td></tr><tr align="left"><td valign="top" width="25%">instrumentName
</td><td valign="top" width="15%">Text
</td><td valign="top" width="45%">Set the name to be placed at the start of the staff
</td><td valign="top" width="15%"><code>"Cello I"</code>
<br></td></tr><tr align="left"><td valign="top" width="25%">fontSize
</td><td valign="top" width="15%">Real
</td><td valign="top" width="45%">Increase or decrease the font size
</td><td valign="top" width="15%"><code>2.4</code>
<br></td></tr><tr align="left"><td valign="top" width="25%">stanza
</td><td valign="top" width="15%">Text
</td><td valign="top" width="45%">Set the text to print before the start of a verse
</td><td valign="top" width="15%"><code>"2"</code>
<br></td></tr></table>
<p class="noindent">where a Boolean is either True (<code>#t</code>) or False (<code>#f</code>),
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,
(<code>#</code>), in two different places – as part of the Boolean
value before the <code>t</code> or <code>f</code>, and before <em>value</em>
in the <code>\set</code> statement. So when a Boolean is being
entered you need to code two hash signs, e.g., <code>##t</code>.
<p>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
<code>instrumentName</code> clearly lives in the <code>Staff</code> 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.
<blockquote>
<pre class="verbatim">
<<
\new Staff \relative c'' {
\set Staff.instrumentName = #"Soprano"
c4 c
}
\new Staff \relative c' {
\set instrumentName = #"Alto" % Wrong!
d4 d
}
>>
</pre>
<p>
<a href="../73/lily-26476fe0.ly">
<img align="middle"
border="0" src="../73/lily-26476fe0.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>Remember the default context name is <code>Voice</code>, so the second
<code>\set</code> command set the property <code>instrumentName</code> in the
<code>Voice</code> context to “Alto”, but as LilyPond does not look
for any such property in the <code>Voice</code> context, no
further action took place. This is not an error, and no error
message is logged in the log file.
<p>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 <code>\set</code> 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 <a name="index-Tunable-context-properties-303"></a><a href="../lilypond-internals/Tunable-context-properties.de.html#Tunable-context-properties">Tunable context properties</a>, or
<a name="index-Contexts-304"></a><a href="../lilypond-internals/Contexts.de.html#Contexts">Contexts</a>.
<p>The <code>instrumentName</code> property will take effect only
if it is set in the <code>Staff</code> context, but
some properties can be set in more than one context.
For example, the property <code>extraNatural</code> is by
default set to ##t (true) for all staves.
If it is set to ##f (false) in one particular <code>Staff</code>
context it applies just to the accidentals on that staff.
If it is set to false in the <code>Score</code> context
it applies to all staves.
<p>So this turns off extra naturals in one staff:
<blockquote>
<pre class="verbatim">
<<
\new Staff \relative c'' {
ais4 aes
}
\new Staff \relative c'' {
\set Staff.extraNatural = ##f
ais4 aes
}
>>
</pre>
<p>
<a href="../58/lily-ebcd81e3.ly">
<img align="middle"
border="0" src="../58/lily-ebcd81e3.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p class="noindent">and this turns them off in all staves:
<blockquote>
<pre class="verbatim">
<<
\new Staff \relative c'' {
ais4 aes
}
\new Staff \relative c'' {
\set Score.extraNatural = ##f
ais4 aes
}
>>
</pre>
<p>
<a href="../d5/lily-767072b1.ly">
<img align="middle"
border="0" src="../d5/lily-767072b1.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>As another example, if <code>clefOctavation</code> is set in
the <code>Score</code> context this immediately changes the value
of the octavation in all current staves and sets a new default
value which will be applied to all staves.
<p>The opposite command, <code>\unset</code>, effectively removes the
property from the context, which causes most properties to
revert to their default value. Usually <code>\unset</code> is not
required as a new <code>\set</code> command will achieve what is
wanted.
<p>The <code>\set</code> and <code>\unset</code> 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
<code>\set</code> or <code>\unset</code> 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.
<blockquote>
<pre class="verbatim">
c4
% make note heads smaller
\set fontSize = #-4
d e
% make note heads larger
\set fontSize = #2.5
f g
% return to default size
\unset fontSize
a b
</pre>
<p>
<a href="../46/lily-ce378e56.ly">
<img align="middle"
border="0" src="../46/lily-ce378e56.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>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, <code>#</code>, while a true or false value is specified by
<code>##t</code> and <code>##f</code>, 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 <code>markup</code> command.
<h5 class="unnumberedsubsubsec">Setting context properties with <code>\with</code></h5>
<p><a name="index-g_t_005cwith-305"></a><a name="index-g_t_005cwith-306"></a>
<a name="index-context-properties_002c-setting-with-_005cwith-307"></a>
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 <code>\new</code>
command it may be followed immediately by a
<code>\with { .. }</code> 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:
<pre class="example">\new Staff \with { extraNatural = ##f }
</pre>
<p class="noindent">like this:
<blockquote>
<pre class="verbatim">
<<
\new Staff
\relative c'' {
gis ges aes ais
}
\new Staff \with { extraNatural = ##f }
\relative c'' {
gis ges aes ais
}
>>
</pre>
<p>
<a href="../60/lily-b6cbcf03.ly">
<img align="middle"
border="0" src="../60/lily-b6cbcf03.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>Properties set in this way may still be changed dynamically using
<code>\set</code> and returned to their default value with <code>\unset</code>.
<p>The <code>fontSize</code> property is treated differently. If this is
set in a <code>\with</code> clause it effectively resets the default
value of the font size. If it is later changed with <code>\set</code>,
this new default value may be restored with the
<code>\unset fontSize</code> command.
<h5 class="unnumberedsubsubsec">Setting context properties with <code>\context</code></h5>
<p>The values of context properties may be set in <em>all</em> contexts
of a particular type, such as all <code>Staff</code> contexts, with a single
command. The context type is identified by using its
type name, like <code>Staff</code>, prefixed by a back-slash: <code>\Staff</code>.
The statement which sets the property value is the same as that in a
<code>\with</code> block, introduced above. It is placed in a
<code>\context</code> block within a <code>\layout</code> block. Each
<code>\context</code> block will affect all contexts of the type specified
throughout the <code>\score</code> or <code>\book</code> block in which the
<code>\layout</code> block appears. Here is a example to show the format:
<blockquote>
<pre class="verbatim">
\score {
\new Staff {
\relative c'' {
cis4 e d ces
}
}
\layout {
\context {
\Staff
extraNatural = ##t
}
}
}
</pre>
<p>
<a href="../c1/lily-bfa598af.ly">
<img align="middle"
border="0" src="../c1/lily-bfa598af.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p class="noindent">Context properties set in this way may be overridden for particular
instances of contexts by statements in a <code>\with</code> block, and by
<code>\set</code> commands embedded in music statements.
<p class="noindent">
<h5 class="subsubheading">See also</h5>
<p class="indent">
<p>Notation Reference:
<a name="index-Changing-context-default-settings-308"></a><a href="../lilypond/Changing-context-default-settings.de.html#Changing-context-default-settings">Changing context default settings</a>.
<!-- FIXME -->
<!-- uncomment when backslash-node-name issue is resolved -pm -->
<!-- @ruser{The set command}. -->
<p>Internals Reference:
<a name="index-Contexts-309"></a><a href="../lilypond-internals/Contexts.de.html#Contexts">Contexts</a>,
<a name="index-Tunable-context-properties-310"></a><a href="../lilypond-internals/Tunable-context-properties.de.html#Tunable-context-properties">Tunable context properties</a>.
<!-- footer_tag --><br><hr>
<div class="node">
<p>
Next: <a rel="next" accesskey="n" href="Adding-and-removing-engravers.de.html#Adding-and-removing-engravers">Adding and removing engravers</a>,
Previous: <a rel="previous" accesskey="p" href="Engravers-explained.de.html#Engravers-explained">Engravers explained</a>,
Up: <a rel="up" accesskey="u" href="Contexts-and-engravers.de.html#Contexts-and-engravers">Contexts and engravers</a>
</div>
<div style="background-color: #e8ffe8; padding: 2; border: #c0ffc0 1px solid;">
<p>
<font size="-1">
Diese Seite ist für LilyPond-2.11.57 (Entwicklungszweig).
<br>
<address>
Fehler bitte an <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs</a> melden. </address>
<br>
Ihre <a href="http://lilypond.org/web/devel/participating/documentation-adding">Vorschläge für die Dokumentation</a> sind willkommen.
</font>
</p>
</div>
<P>
Andere Sprachen: <a href="Modifying-context-properties.fr.html">français</a>, <a href="Modifying-context-properties.es.html">español</a>.
<BR>
</P>
</BODY></html>
