<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<html lang="en">
<head>
<title>Moving 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="Collisions-of-objects.html#Collisions-of-objects" title="Collisions of objects">
<link rel="next" href="Fixing-overlapping-notation.html#Fixing-overlapping-notation" title="Fixing overlapping notation">
<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="Moving-objects"></a>
Next: <a rel="next" accesskey="n" href="Fixing-overlapping-notation.html#Fixing-overlapping-notation">Fixing overlapping notation</a>,
Up: <a rel="up" accesskey="u" href="Collisions-of-objects.html#Collisions-of-objects">Collisions of objects</a>
<hr>
</div>
<h4 class="subsection">4.5.1 Moving objects</h4>
<p>This may come as a surprise, but LilyPond is not perfect. Some
notation elements can overlap. This is unfortunate, but in fact
rather rare. Usually the need to move objects is for clarity or
aesthetic reasons – they would look better with a little more
or a little less space around them.
<p>There are three main approaches to resolving overlapping
notation. They should be considered in the following order:
<ol type=1 start=1>
<li>The <strong>direction</strong> of one of the overlapping objects may
be changed using the predefined commands listed above for
within-staff objects (see <a href="Within_002dstaff-objects.html#Within_002dstaff-objects">Within-staff objects</a>).
Stems, slurs, beams, ties, dynamics, text and tuplets may be
repositioned easily in this way. The limitation is that you
have a choice of only two positions, and neither may be
suitable.
<li>The <strong>object properties</strong>, which LilyPond uses
when positioning layout objects, may be modified using
<code>\override</code>. The advantages
of making changes to this type of property are (a) that some
other objects will be moved automatically if necessary to make
room and (b) the single override can apply to all instances of
the same type of object. Such properties include:
<ul>
<li><code>direction</code>
<p>This has already been covered in some detail – see
<a href="Within_002dstaff-objects.html#Within_002dstaff-objects">Within-staff objects</a>.
<li><code>padding</code>, <code>left-padding</code>,
<code>right-padding</code>, <code>staff-padding</code>
<p><a name="index-left_002dpadding-property-409"></a><a name="index-padding-property-410"></a><a name="index-right_002dpadding-property-411"></a><a name="index-staff_002dpadding-property-412"></a>As an object is being positioned the value of its <code>padding</code>
property specifies the gap that must be left between itself and
the nearest edge of the object against which it is being
positioned. Note that it is the <code>padding</code> value of the object
<strong>being placed</strong> that is used;
the <code>padding</code> value of the object which is already placed is
ignored. Gaps specified by <code>padding</code> can be applied
to all objects which support the <code>side-position-interface</code>.
<p>Instead of <code>padding</code>, the placement of groups of accidentals
is controlled by <code>left-padding</code> and <code>right-padding</code>.
These properties are to be found in the <code>AccidentalPlacement</code>
object which, note, lives in the <strong>staff</strong> context. In the
type-setting process the note heads are type-set first and then
the accidentals, if any, are added to the left of the note heads
using the <code>right-padding</code> property to determine the separation
from the note heads. So only the <code>right-padding</code> property of the
<code>AccidentalPlacement</code> object has any effect on the placement
of the accidentals.
<p>The <code>staff-padding</code> property is closely related to the
<code>padding</code> property: <code>padding</code>
controls the minimum amount of space between any object which
supports the <code>side-position-interface</code> and the nearest
other object (generally the note or the staff lines);
<code>staff-padding</code> applies only to those objects which are always
set outside the staff – it controls the minimum amount of space
that should be inserted between that object and the staff. Note
that <code>staff-padding</code> has no effect on objects which are
positioned relative to the note rather than the staff, even though
it may be overridden without error for such objects – it is simply
ignored.
<p>To discover which padding property is required for the object
you wish to reposition, you
need to return to the IR and look up the object's properties.
Be aware that the padding properties might not be located in the
obvious object, so look in objects that appear to be related.
<p>All padding values are measured in staff spaces. For most
objects, this value is set by default to be around 1.0 or less
(it varies with each object). It may be overridden if a larger
(or smaller) gap is required.
<li><code>self-alignment-X</code>
<p><a name="index-self_002dalignment_002dX-property-413"></a>This property can be used to align the object to the left, to
the right, or to center it with respect to the parent object's
reference point. It may be used with all objects which support
the <code>self-alignment-interface</code>. In general these are objects
that contain text. The values are <code>LEFT</code>, <code>RIGHT</code>
or <code>CENTER</code>. Alternatively, a numerical value between
<code>-1</code> and <code>+1</code> may be specified, where <code>-1</code> is
left-aligned, <code>+1</code> is right-aligned, and numbers in between
move the text progressively from left-aligned to right-aligned.
Numerical values greater than <code>1</code> may be specified to move
the text even further to the left, or less than <code>-1</code> to
move the text even further to the right. A change of <code>1</code>
in the value corresponds to a movement of half the text's length.
<li><code>extra-spacing-width</code>
<p><a name="index-extra_002dspacing_002dwidth-property-414"></a>This property is available for all objects which support the
<code>item-interface</code>. It takes two numbers, the first is added
to the leftmost extent and the second is added to the rightmost
extent. Negative numbers move the edge to the left, positive to
the right, so to widen an object the first number must be negative,
the second positive. Note that not all objects honor both
numbers. For example, the <code>Accidental</code> object only takes
notice of the first (left edge) number.
<li><code>staff-position</code>
<p><a name="index-staff_002dposition-property-415"></a><code>staff-position</code> is a property of the
<code>staff-symbol-referencer-interface</code>, which is supported by
objects which are positioned relative to the staff. It specifies
the vertical position of the object relative to the center line
of the staff in half staff-spaces. It is useful in resolving
collisions between layout objects like multi-measure rests, ties
and notes in different voices.
<li><code>force-hshift</code>
<p><a name="index-force_002dhshift-property-416"></a>
Closely spaced notes in a chord, or notes occurring at the same
time in different voices, are arranged in two, occasionally more,
columns to prevent the note heads overlapping. These are called
note columns, and an object called <code>NoteColumn</code> is created
to lay out the notes in that column.
<p>The <code>force-hshift</code>
property is a property of a <code>NoteColumn</code> (actually of the
<code>note-column-interface</code>). Changing it permits a note column
to be moved in units appropriate to a note column, viz. the note
head width of the first voice note. It should be used in
complex situations where the normal <code>\shiftOn</code> commands (see
<a href="Explicitly-instantiating-voices.html#Explicitly-instantiating-voices">Explicitly instantiating voices</a>) do
not resolve the note conflict. It is preferable to the
<code>extra-offset</code> property for this purpose as there is no need
to work out the distance in staff-spaces, and moving the notes
into or out of a <code>NoteColumn</code> affects other actions such as
merging note heads.
</ul>
<li>Finally, when all else fails, objects may be manually repositioned
relative to the staff center line vertically, or by
displacing them by any distance to a new position. The
disadvantages are that the correct values for the repositioning
have to be worked out, often by trial and error, for every object
individually, and, because the movement is done after LilyPond has
placed all other objects, the user is responsible for avoiding any
collisions that might ensue. But the main difficulty with this
approach is that the repositioning values may need to be reworked
if the music is later modified. The properties that can be used
for this type of manual repositioning are:
<dl>
<dt><code>extra-offset</code><dd><a name="index-extra_002doffset-property-417"></a>This property applies to any layout object
supporting the <code>grob-interface</code>. It takes a pair of
numbers which specify the extra displacement in the horizontal and
vertical directions. Negative numbers move the object to
the left or down. The units are staff-spaces. The extra
displacement is made after the typesetting of objects is
finished, so an object may be repositioned anywhere without
affecting anything else.
<br><dt><code>positions</code><dd><a name="index-positions-property-418"></a>This is most useful for manually adjusting the slope and height
of beams, slurs, and tuplets. It takes a pair of numbers
giving the position of the left and right ends of the beam, slur,
etc. relative to the center line of the staff. Units are
staff-spaces. Note, though, that slurs and phrasing slurs cannot
be repositioned by arbitrarily large amounts. LilyPond first
generates a list of possible positions for the slur and by default
finds the slur that “looks best”. If the <code>positions</code>
property has been overridden the slur that is closest to the
requested positions is selected from the list.
</dl>
</ol>
<p>A particular object may not have all of these properties.
It is necessary to go to the IR to look up which properties
are available for the object in question.
<p>Here is a list of the objects which are most likely to be
involved in collisions, together with the name of the object which
should be looked up in the IR in order to discover which properties
should be used to move them.
<p><table summary=""><tr align="left"><th valign="top" width="50%">Object type </th><th valign="top" width="50%">Object name
<br></th></tr><tr align="left"><td valign="top" width="50%">Articulations </td><td valign="top" width="50%"><code>Script</code>
<br></td></tr><tr align="left"><td valign="top" width="50%">Beams </td><td valign="top" width="50%"><code>Beam</code>
<br></td></tr><tr align="left"><td valign="top" width="50%">Dynamics (vertically) </td><td valign="top" width="50%"><code>DynamicLineSpanner</code>
<br></td></tr><tr align="left"><td valign="top" width="50%">Dynamics (horizontally) </td><td valign="top" width="50%"><code>DynamicText</code>
<br></td></tr><tr align="left"><td valign="top" width="50%">Fingerings </td><td valign="top" width="50%"><code>Fingering</code>
<br></td></tr><tr align="left"><td valign="top" width="50%">Rehearsal / Text marks </td><td valign="top" width="50%"><code>RehearsalMark</code>
<br></td></tr><tr align="left"><td valign="top" width="50%">Slurs </td><td valign="top" width="50%"><code>Slur</code>
<br></td></tr><tr align="left"><td valign="top" width="50%">Text e.g. <code>^"text"</code> </td><td valign="top" width="50%"><code>TextScript</code>
<br></td></tr><tr align="left"><td valign="top" width="50%">Ties </td><td valign="top" width="50%"><code>Tie</code>
<br></td></tr><tr align="left"><td valign="top" width="50%">Tuplets </td><td valign="top" width="50%"><code>TupletBracket</code>
<br></td></tr></table>
<!-- footer_tag --><br><hr>
<div class="node">
<p>
Next: <a rel="next" accesskey="n" href="Fixing-overlapping-notation.html#Fixing-overlapping-notation">Fixing overlapping notation</a>,
Up: <a rel="up" accesskey="u" href="Collisions-of-objects.html#Collisions-of-objects">Collisions 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="Moving-objects.fr.html">français</a>, <a href="Moving-objects.es.html">español</a>, <a href="Moving-objects.de.html">deutsch</a>.
<BR>
</P>
</BODY></html>
