<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<html lang="en">
<head>
<title>Outside staff objects - 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.html#Top">
<link rel="up" href="Placement-of-objects.html#Placement-of-objects" title="Placement of objects">
<link rel="prev" href="Within_002dstaff-objects.html#Within_002dstaff-objects" title="Within-staff objects">
<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="Outside-staff-objects"></a>
Previous: <a rel="previous" accesskey="p" href="Within_002dstaff-objects.html#Within_002dstaff-objects">Within-staff objects</a>,
Up: <a rel="up" accesskey="u" href="Placement-of-objects.html#Placement-of-objects">Placement of objects</a>
<hr>
</div>
<h4 class="subsection">4.4.3 Outside staff objects</h4>
<p>Outside-staff objects are automatically placed to avoid collisions.
Objects with the lower value of the <code>outside-staff-priority</code>
property are placed nearer to the staff, and other outside-staff
objects are then raised as far as necessary to avoid collisions.
The <code>outside-staff-priority</code> is defined in the
<code>grob-interface</code> and so is a property of all layout objects.
By default it is set to <code>#f</code> for all within-staff objects,
and to a numerical value appropriate to each outside-staff object
when the object is created. The following table shows
the default numerical values for some of the commonest
outside-staff objects which are, by default, placed in the
<code>Staff</code> or <code>Voice</code> contexts.
<p><table summary=""><tr align="left"><th valign="top" width="30%">Layout Object
</th><th valign="top" width="30%">Priority
</th><th valign="top" width="30%">Controls position of:
<br></th></tr><tr align="left"><td valign="top" width="30%"><code>MultiMeasureRestText</code>
</td><td valign="top" width="30%"><code>450</code>
</td><td valign="top" width="30%">Text over full-bar rests
<br></td></tr><tr align="left"><td valign="top" width="30%"><code>TextScript</code>
</td><td valign="top" width="30%"><code>450</code>
</td><td valign="top" width="30%">Markup text
<br></td></tr><tr align="left"><td valign="top" width="30%"><code>OttavaBracket</code>
</td><td valign="top" width="30%"><code>400</code>
</td><td valign="top" width="30%">Ottava brackets
<br></td></tr><tr align="left"><td valign="top" width="30%"><code>TextSpanner</code>
</td><td valign="top" width="30%"><code>350</code>
</td><td valign="top" width="30%">Text spanners
<br></td></tr><tr align="left"><td valign="top" width="30%"><code>DynamicLineSpanner</code>
</td><td valign="top" width="30%"><code>250</code>
</td><td valign="top" width="30%">All dynamic markings
<br></td></tr><tr align="left"><td valign="top" width="30%"><code>VoltaBracketSpanner</code>
</td><td valign="top" width="30%"><code>100</code>
</td><td valign="top" width="30%">Volta brackets
<br></td></tr><tr align="left"><td valign="top" width="30%"><code>TrillSpanner</code>
</td><td valign="top" width="30%"><code>50</code>
</td><td valign="top" width="30%">Spanning trills
<br></td></tr></table>
<p>Here is an example showing the default placement of some of
these.
<p><a name="index-text-spanner-392"></a><a name="index-g_t_005cstartTextSpan-393"></a><a name="index-g_t_005cstartTextSpan-394"></a>
<a name="index-g_t_005cstopTextSpan-395"></a><a name="index-g_t_005cstopTextSpan-396"></a>
<a name="index-ottava-bracket-397"></a>
<blockquote>
<pre class="verbatim">
% Set details for later Text Spanner
\override TextSpanner #'bound-details #'left #'text
= \markup { \small \bold Slower }
% Place dynamics above staff
\dynamicUp
% Start Ottava Bracket
\ottava #1
c' \startTextSpan
% Add Dynamic Text
c\pp
% Add Dynamic Line Spanner
c\<
% Add Text Script
c^Text
c c
% Add Dynamic Text
c\ff c \stopTextSpan
% Stop Ottava Bracket
\ottava #0
c, c c c
</pre>
<p>
<a href="../20/lily-769c3018.ly">
<img align="middle"
border="0" src="../20/lily-769c3018.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>This example also shows how to create Text Spanners –
text with extender lines above a section of music. The
spanner extends from the <code>\startTextSpan</code> command to
the <code>\stopTextSpan</code> command, and the format of the
text is defined by the <code>\override TextSpanner</code> command.
For more details see <a name="index-Text-spanners-398"></a><a href="../lilypond/Text-spanners.html#Text-spanners">Text spanners</a>.
<p>It also shows how ottava brackets are created.
<p>Note that bar numbers, metronome marks and rehearsal marks
are not shown. By default these are created in the
<code>Score</code> context and their <code>outside-staff-priority</code>
is ignored relative to the layout objects which are created
in the <code>Staff</code> context.
If you wish to place bar numbers, metronome marks or rehearsal
marks in accordance with the value of their
<code>outside-staff-priority</code> the <code>Bar_number_engraver</code>,
<code>Metronome_mark_engraver</code> or <code>Mark_engraver</code> respectively
should be removed from the <code>Score</code> context and placed in the
top <code>Staff</code> context. If this is done, these marks will be
given the following default <code>outside-staff-priority</code> values:
<p><table summary=""><tr align="left"><th valign="top" width="30%">Layout Object </th><th valign="top" width="30%">Priority
<br></th></tr><tr align="left"><td valign="top" width="30%"><code>RehearsalMark</code> </td><td valign="top" width="30%"><code>1500</code>
<br></td></tr><tr align="left"><td valign="top" width="30%"><code>MetronomeMark</code> </td><td valign="top" width="30%"><code>1000</code>
<br></td></tr><tr align="left"><td valign="top" width="30%"><code>BarNumber</code> </td><td valign="top" width="30%"><code> 100</code>
<br></td></tr></table>
<p>If the default values of <code>outside-staff-priority</code> do not
give you the placing you want, the priority of any of the objects
may be overridden. Suppose we would
like the ottava bracket to be placed below the text spanner in the
example above. All we need to do is to look up the priority of
<code>OttavaBracket</code> in the IR or in the tables above, and reduce
it to a value lower than that of a <code>TextSpanner</code>, remembering
that <code>OttavaBracket</code> is created in the <code>Staff</code> context:
<blockquote>
<pre class="verbatim">
% Set details for later Text Spanner
\override TextSpanner #'bound-details #'left #'text
= \markup { \small \bold Slower }
% Place dynamics above staff
\dynamicUp
%Place following Ottava Bracket below Text Spanners
\once \override Staff.OttavaBracket #'outside-staff-priority = #340
% Start Ottava Bracket
\ottava #1
c' \startTextSpan
% Add Dynamic Text
c\pp
% Add Dynamic Line Spanner
c\<
% Add Text Script
c^Text
c c
% Add Dynamic Text
c\ff c \stopTextSpan
% Stop Ottava Bracket
\ottava #0
c, c c c
</pre>
<p>
<a href="../98/lily-38c8b76a.ly">
<img align="middle"
border="0" src="../98/lily-38c8b76a.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>Changing the <code>outside-staff-priority</code> can also be used to
control the vertical placement of individual objects, although
the results may not always be desirable. Suppose we would
like “Text3” to be placed above “Text4” in the example
under Automatic behavior, above (see <a href="Automatic-behavior.html#Automatic-behavior">Automatic behavior</a>).
All we need to do is to look up the priority of <code>TextScript</code>
in the IR or in the tables above, and increase the priority of
“Text3” to a higher value:
<blockquote>
<pre class="verbatim">
c2^"Text1"
c^"Text2"
\once \override TextScript #'outside-staff-priority = #500
c^"Text3"
c^"Text4"
</pre>
<p>
<a href="../0a/lily-a6c82911.ly">
<img align="middle"
border="0" src="../0a/lily-a6c82911.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>This certainly lifts “Text3” above “Text4” but it also
lifts it above “Text2”, and “Text4” now drops down.
Perhaps this is not so good. What we would really like to do
is to position all the annotation at the same distance above
the staff? To do this, we clearly
will need to space the notes out horizontally to make more
room for the text. This is done using the <code>textLengthOn</code>
command.
<h4 class="subheading">\textLengthOn</h4>
<p><a name="index-g_t_005ctextLengthOn-399"></a><a name="index-g_t_005ctextLengthOn-400"></a>
<a name="index-notes_002c-spreading-out-with-text-401"></a>
By default, text produced by markup takes up no horizontal space
as far as laying out the music is concerned. The <code>\textLengthOn</code>
command reverses this behavior, causing the notes to be spaced
out as far as is necessary to accommodate the text:
<blockquote>
<pre class="verbatim">
\textLengthOn % Cause notes to space out to accommodate text
c2^"Text1"
c^"Text2"
c^"Text3"
c^"Text4"
</pre>
<p>
<a href="../53/lily-b9eff974.ly">
<img align="middle"
border="0" src="../53/lily-b9eff974.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>The command to revert to the default behavior is
<code>\textLengthOff</code>. Remember <code>\once</code> only works with
<code>\override</code>, <code>\set</code>, <code>\revert</code> or <code>unset</code>,
so cannot be used with <code>\textLengthOn</code>.
<p>Markup text will also avoid notes which project above the staff.
If this is not desired, the automatic displacement upwards may
be turned off by setting the priority to <code>#f</code>. Here's an
example to show how markup text interacts with such notes.
<blockquote>
<pre class="verbatim">
% This markup is short enough to fit without collision
c2^"Tex"
c''2
R1
% This is too long to fit, so it is displaced upwards
c,,2^"Text"
c''2
R1
% Turn off collision avoidance
\once \override TextScript #'outside-staff-priority = ##f
c,,2^"Long Text "
c''2
R1
% Turn off collision avoidance
\once \override TextScript #'outside-staff-priority = ##f
\textLengthOn % and turn on textLengthOn
c,,2^"Long Text " % Spaces at end are honored
c''2
</pre>
<p>
<a href="../ab/lily-f3ef3168.ly">
<img align="middle"
border="0" src="../ab/lily-f3ef3168.png" alt="[image of music]">
</a>
</p>
</blockquote>
<h4 class="subheading">Dynamics</h4>
<p>Dynamic markings will normally be positioned beneath the
staff, but may be positioned above with the <code>dynamicUp</code>
command. They will be positioned vertically relative to the
note to which they are attached, and will float below (or above)
all within-staff objects such as phrasing slurs and bar numbers.
This can give quite acceptable results, as this example
shows:
<blockquote>
<pre class="verbatim">
\clef "bass"
\key aes \major
\time 9/8
\dynamicUp
bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! |
ees,2.~\)\mf ees4 r8 |
</pre>
<p>
<a href="../da/lily-f142f3b3.ly">
<img align="middle"
border="0" src="../da/lily-f142f3b3.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>However, if the notes and attached dynamics are close
together the automatic placement will avoid collisions
by displacing later dynamic markings further away, but this may
not be the optimum placement, as this rather artificial example
shows:
<blockquote>
<pre class="verbatim">
\dynamicUp
a4\f b\mf c\mp b\p
</pre>
<p>
<a href="../e9/lily-ce9fa8f2.ly">
<img align="middle"
border="0" src="../e9/lily-ce9fa8f2.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p class="noindent">Should a similar situation arise in ‘real’ music, it may
be preferable to space out the notes
a little further, so the dynamic markings can all fit at the
same vertical distance from the staff. We were able to do this
for markup text by using the <code>\textLengthOn</code> command, but there
is no equivalent command for dynamic marks. So we shall have to
work out how to do this using <code>\override</code> commands.
<h4 class="subheading">Grob sizing</h4>
<p><a name="index-grob-sizing-402"></a><a name="index-sizing-grobs-403"></a><a name="index-g_t_0040code_007bX_002doffset_007d-404"></a><a name="index-g_t_0040code_007bY_002doffset_007d-405"></a><a name="index-g_t_0040code_007bX_002dextent_007d-406"></a><a name="index-g_t_0040code_007bY_002dextent_007d-407"></a>
First we must learn how grobs are sized. All grobs have a
reference point defined within them which is used to position
them relative to their parent object. This point in the grob
is then positioned at a horizontal distance, <code>X-offset</code>,
and at a vertical distance, <code>Y-offset</code>, from its parent.
The horizontal extent of the object is given by a pair of
numbers, <code>X-extent</code>, which say where the left and right
edges are relative to the reference point. The vertical extent
is similarly defined by a pair of numbers, <code>Y-extent</code>.
These are properties of all grobs which support the
<code>grob-interface</code>.
<p><a name="index-g_t_0040code_007bextra_002dspacing_002dwidth_007d-408"></a>
By default, outside-staff objects are given a width of zero so
that they may overlap in the horizontal direction. This is done
by the trick of adding infinity to the leftmost extent and
minus infinity to the rightmost extent by setting the
<code>extra-spacing-width</code> to <code>'(+inf.0 . -inf.0)</code>. So
to ensure they do not overlap in the horizontal direction we
must override this value of <code>extra-spacing-width</code> to
<code>'(0 . 0)</code> so the true width shines through. This is
the command to do this for dynamic text:
<pre class="example">\override DynamicText #'extra-spacing-width = #'(0 . 0)
</pre>
<p class="noindent">Let's see if this works in our previous example:
<blockquote>
<pre class="verbatim">
\dynamicUp
\override DynamicText #'extra-spacing-width = #'(0 . 0)
a4\f b\mf c\mp b\p
</pre>
<p>
<a href="../54/lily-cf45e3d2.ly">
<img align="middle"
border="0" src="../54/lily-cf45e3d2.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p class="noindent">Well, it has certainly stopped the dynamic marks being
displaced, but two problems remain. The marks should be
spaced a little further apart and it would be better
if they were all the same distance from the staff.
We can solve the first problem easily. Instead of making
the <code>extra-spacing-width</code> zero we could add a little
more to it. The units are the space between two staff
lines, so moving the left edge half a unit to the left and the
right edge half a unit to the right should do it:
<blockquote>
<pre class="verbatim">
\dynamicUp
% Extend width by 1 staff space
\override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5)
a4\f b\mf c\mp b\p
</pre>
<p>
<a href="../b7/lily-18117edf.ly">
<img align="middle"
border="0" src="../b7/lily-18117edf.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p class="noindent">This looks better, but maybe we would prefer the dynamic marks
to be aligned along the same baseline rather than going up and
down with the notes. The property to do this is
<code>staff-padding</code> which is covered in the following section.
<!-- footer_tag --><br><hr>
<div class="node">
<p>
Previous: <a rel="previous" accesskey="p" href="Within_002dstaff-objects.html#Within_002dstaff-objects">Within-staff objects</a>,
Up: <a rel="up" accesskey="u" href="Placement-of-objects.html#Placement-of-objects">Placement of objects</a>
</div>
<div style="background-color: #e8ffe8; padding: 2; border: #c0ffc0 1px solid;">
<p>
<font size="-1">
This page is for LilyPond-2.11.57 (development-branch).
<br>
<address>
Report errors to <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>. </address>
<br>
Your <a href="http://lilypond.org/web/devel/participating/documentation-adding">suggestions for the documentation</a> are welcome.
</font>
</p>
</div>
<P>
Other languages: <a href="Outside-staff-objects.es.html">español</a>.
<BR>
</P>
</BODY></html>
