LilyPond beginnershandleiding: 4.5.1 Moving objects

### 4.5.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 amount of space that should be inserted between that object and the staff. Note that `staff-padding` 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.

     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.

   - `force-hshift`

     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 `NoteColumn` is created to lay out the notes in that column.

     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 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. 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`

#### LilyPond – Beginnershandleiding v2.22.2 (stabiele tak).