[ << Tweaking output ]	[Top][Contents][Index]	[ Templates >> ]
[ < Collisions of objects ]	[ Up : Collisions of objects ]	[ Fixing overlapping notation > ]

---

5.7.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 earlier 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) that 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 that 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 grob 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 grob 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 that supports the side-position-interface and the nearest other object (generally the note or the staff lines); staff-padding applies only to those objects that 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

     Use this property 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 that 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 that support the item-interface. It takes two numbers, the first is added to the left edge of the extent and the second is added to the right edge. 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

     This property is part of the staff-symbol-referencer-interface, which is supported by objects that 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 occurring at the same musical moment are grouped into a note column, and a NoteColumn grob 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 progressively offset to avoid collisions of the note heads. 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 part of NoteColumn grobs (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 everything 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. However, 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 as follows.
   • extra-offset

     This property applies to any layout object supporting the grob-interface. It takes a pair of numbers that 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, e.g., ‘->’	Script
beams	Beam
dynamics (vertically)	DynamicLineSpanner
dynamics (horizontally)	DynamicText
fingerings	Fingering
rehearsal marks	RehearsalMark
text marks	TextMark
slurs	Slur
text, e.g., ‘^"text"’	TextScript
ties	Tie
tuplets	TupletBracket