lilypond-learning: Moving objects
4.6.1 Moving objects
--------------------
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.
There are three main approaches to resolving overlapping notation.
They should be considered in the following order:
1. The *direction* of one of the overlapping objects may be changed
using the predefined commands listed above for within-staff objects
(see 
Within-staff objects). 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.
2. The *object properties*, which LilyPond uses when positioning
layout objects, may be modified using ‘\override’. 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:
• ‘direction’
This has already been covered in some detail – see
Within-staff objects.
• ‘padding’, ‘right-padding’, ‘staff-padding’
As an object is being positioned the value of its ‘padding’
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 ‘padding’ value of the object
*being placed* that is used; the ‘padding’ value of the object
which is already placed is ignored. Gaps specified by
‘padding’ can be applied to all objects which support the
‘side-position-interface’.
Instead of ‘padding’, the placement of groups of accidentals
is controlled by ‘right-padding’. This property is to be
found in the ‘AccidentalPlacement’ object which, note, lives
in the *Staff* context. In the typesetting process the note
heads are typeset first and then the accidentals, if any, are
added to the left of the note heads using the ‘right-padding’
property to determine the separation from the note heads and
between individual accidentals. So only the ‘right-padding’
property of the ‘AccidentalPlacement’ object has any effect on
the placement of the accidentals.
The ‘staff-padding’ property is closely related to the
‘padding’ property: ‘padding’ controls the minimum amount of
space between any object which supports the
‘side-position-interface’ and the nearest other object
(generally the note or the staff lines); ‘staff-padding’
applies only to those objects which are always set outside the
staff – it controls the minimum distance from the staff to the
outside-staff object. Note that ‘staff-padding’ has no effect
on objects that 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.
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.
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.
• ‘self-alignment-X’
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 ‘self-alignment-interface’. In general these are
objects that contain text. The values are ‘LEFT’, ‘RIGHT’ or
‘CENTER’. Alternatively, a numerical value between ‘-1’ and
‘+1’ may be specified, where ‘-1’ is left-aligned, ‘+1’ is
right-aligned, and numbers in between move the text
progressively from left-aligned to right-aligned. Numerical
values greater than ‘1’ may be specified to move the text even
further to the left, or less than ‘-1’ to move the text even
further to the right. A change of ‘1’ in the value
corresponds to a movement of half the text’s length.
• ‘extra-spacing-width’
This property is available for all objects which support the
‘item-interface’. 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 ‘Accidental’ object only
takes notice of the first (left edge) number.
• ‘staff-position’
‘staff-position’ is a property of the
‘staff-symbol-referencer-interface’, 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.
• ‘horizontal-shift’
Within a voice, all the notes occuring at the same musical
moment are grouped into a note column, and a ‘NoteColumn’
object is created to control the horizontal positioning of
that group of notes (see “Note columns” in Explicitly
instantiating voices). If _and only if_ two or more note
columns within a single Staff context, both with stems in the
same direction, occur at the same musical moment, the values
of their ‘horizontal-shift’ properties are used to rank them
and the columns in the higher ranks are progessively offset to
avoid collisions of the noteheads. This property is set by
the ‘\voiceXXX’ commands and may be overridden directly with
an ‘\override’ command or, more usually, by the ‘\shiftOn’
commands. Note that this property is used to _rank_ the note
columns for off-setting - it does not specify the magnitude of
the offset, which is progressively increased in steps based on
the note head’s width for each rank. The steps are usually of
half a note head’s width, but may be a full note head’s width
when a closely spaced group of notes is involved.
• ‘force-hshift’
The ‘force-hshift’ property is a property of a ‘NoteColumn’
(actually of the ‘note-column-interface’). Changing it
permits a note column to be moved in situations where the note
columns overlap. Note that it has no effect on note columns
that do not overlap. It is specified 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 ‘\shiftOn’ commands (see Explicitly instantiating
voices) do not resolve the note conflict satisfactorily. It
is preferable to the ‘extra-offset’ 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 ‘NoteColumn’ affects
other actions such as merging note heads.
3. 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:
‘extra-offset’
This property applies to any layout object supporting the
‘grob-interface’. 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.
‘positions’
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
‘positions’ property has been overridden the slur that is
closest to the requested positions is selected from the list.
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.
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.
Object type Object name
--------------------------------------------------------------------------
Articulations ‘Script’
Beams ‘Beam’
Dynamics (vertically) ‘DynamicLineSpanner’
Dynamics (horizontally) ‘DynamicText’
Fingerings ‘Fingering’
Rehearsal / Text marks ‘RehearsalMark’
Slurs ‘Slur’
Text e.g. ‘^"text"’ ‘TextScript’
Ties ‘Tie’
Tuplets ‘TupletBracket’
Info Catalog
lilypond-learning: Collisions of objects
lilypond-learning: Fixing overlapping notation