LilyPond Notation Reference: 5.5.1 Aligning objects

### 5.5.1 Aligning objects

Graphical objects which support the `self-alignment-interface` and/or the `side-position-interface` can be aligned to a previously placed object in a variety of ways. For a list of these objects, see self-alignment-interface and side-position-interface.

All graphical objects have a reference point, a horizontal extent and a vertical extent. The horizontal extent is a pair of numbers giving the displacements from the reference point of the left and right edges, displacements to the left being negative. The vertical extent is a pair of numbers giving the displacement from the reference point to the bottom and top edges, displacements down being negative.

An object’s position on a staff is given by the values of the `X-offset` and `Y-offset` properties. The value of `X-offset` gives the displacement from the X coordinate of the reference point of the parent object, and the value of `Y-offset` gives the displacement from the center line of the staff. The values of `X-offset` and `Y-offset` may be set directly or may be set to be calculated by procedures in order to achieve alignment with the parent object.

Note: Many objects have special positioning considerations which cause any setting of `X-offset` or `Y-offset` to be ignored or modified, even though the object supports the `self-alignment-interface`. Overriding the `X-offset` or `Y-offset` properties to a fixed value causes the respective `self-alignment` property to be disregarded.

For example, an accidental can be repositioned vertically by setting `Y-offset` but any changes to `X-offset` have no effect.

Rehearsal marks may be aligned with breakable objects such as bar lines, clef symbols, time signature symbols and key signatures. There are special properties to be found in the `break-aligned-interface` for positioning rehearsal marks on such objects.

#### See also

Notation Reference: Using the `break-alignable-interface`.

Extending LilyPond: Callback functions.

#### Setting `X-offset` and `Y-offset` directly

Numerical values may be given to the `X-offset` and `Y-offset` properties of many objects. The following example shows three notes with the default fingering position and the positions with `X-offset` and `Y-offset` modified.

>     a'-3
>     a'
>     -\tweak X-offset #0
>     -\tweak Y-offset #0
>     -3
>     a'
>     -\tweak X-offset #-1
>     -\tweak Y-offset #1
>     -3

#### Using the `side-position-interface`

An object which supports the `side-position-interface` can be placed next to its parent object so that the specified edges of the two objects touch. The object may be placed above, below, to the right or to the left of the parent. The parent cannot be specified; it is determined by the order of elements in the input stream. Most objects have the associated note head as their parent.

The values of the `side-axis` and `direction` properties determine where the object is to be placed, as follows:

`side-axis` | `direction` |
--- | --- | ---
property | property | Placement
`0` | `-1` | left
`0` | `1` | right
`1` | `-1` | below
`1` | `1` | above

When `side-axis` is `0`, `X-offset` should be set to the procedure `ly:side-position-interface::x-aligned-side`. This procedure will return the correct value of `X-offset` to place the object to the left or right side of the parent according to value of `direction`.

When `side-axis` is `1`, `Y-offset` should be set to the procedure `ly:side-position-interface::y-aligned-side`. This procedure will return the correct value of `Y-offset` to place the object to the top or bottom of the parent according to value of `direction`.

#### Using the `self-alignment-interface`

#### Self-aligning objects horizontally

The horizontal alignment of an object which supports the `self-alignment-interface` is controlled by the value of the `self-alignment-X` property, provided the object’s `X-offset` property is set to `ly:self-alignment-interface::x-aligned-on-self`. `self-alignment-X` may be given any real value, in units of half the total X extent of the object. Negative values move the object to the right, positive to the left. A value of `0` centers the object on the reference point of its parent, a value of `-1` aligns the left edge of the object on the reference point of its parent, and a value of `1` aligns the right edge of the object on the reference point of its parent. The symbols `LEFT`, `CENTER`, and `RIGHT` may be used instead of the values `-1`, `0`, and `1`, respectively.

Normally the `\override` command would be used to modify the value of `self-alignment-X`, but the `\tweak` command can be used to separately align several annotations on a single note:

>     a'
>     -\tweak self-alignment-X #-1
>     ^"left-aligned"
>     -\tweak self-alignment-X #0
>     ^"center-aligned"
>     -\tweak self-alignment-X #RIGHT
>     ^"right-aligned"
>     -\tweak self-alignment-X #-2.5
>     ^"aligned further to the right"

#### Self-aligning objects vertically

Objects may be aligned vertically in an analogous way to aligning them horizontally if the `Y-offset` property is set to `ly:self-alignment-interface::y-aligned-on-self`. However, other mechanisms are often involved in vertical alignment: the value of `Y-offset` is just one variable taken into account. This may make adjusting the value of some objects tricky. The units are just half the vertical extent of the object, which is usually quite small, so quite large numbers may be required. A value of `-1` aligns the lower edge of the object with the reference point of the parent object, a value of `0` aligns the center of the object with the reference point of the parent, and a value of `1` aligns the top edge of the object with the reference point of the parent. The symbols `DOWN`, `CENTER`, and `UP` may be substituted for `-1`, `0`, and `1`, respectively.

#### Self-aligning objects in both directions

By setting both `X-offset` and `Y-offset`, an object may be aligned in both directions simultaneously.

The following example shows how to adjust a fingering mark so that it nestles close to the note head.

>     a'
>     -\tweak self-alignment-X #0.5  % move horizontally left
>     -\tweak Y-offset #ly:self-alignment-interface::y-aligned-on-self
>     -\tweak self-alignment-Y #-1  % move vertically up
>     -3  % third finger

#### Using the `break-alignable-interface`

Rehearsal marks and bar numbers may be aligned with notation objects other than bar lines. These objects include `ambitus`, `breathing-sign`, `clef`, `custos`, `staff-bar`, `left-edge`, `key-cancellation`, `key-signature`, and `time-signature`.

Each type of object has its own default reference point, to which rehearsal marks are aligned:

>     % The rehearsal mark will be aligned
>     % to the right edge of the Clef
>     \override Score.RehearsalMark.break-align-symbols =
>                 #'(clef)
>     \key a \major
>     \clef treble
>     \mark "↓"
>     e'1
>     % The rehearsal mark will be aligned
>     % to the left edge of the Time Signature
>     \override Score.RehearsalMark.break-align-symbols =
>                 #'(time-signature)
>     \key a \major
>     \clef treble
>     \time 3/4
>     \mark "↓"
>     e'2.
>     % The rehearsal mark will be centered
>     % above the Breath Mark
>     \override Score.RehearsalMark.break-align-symbols =
>                 #'(breathing-sign)
>     \key a \major
>     \clef treble
>     \time 4/4
>     e'1
>     \breathe
>     \mark "↓"

A list of possible target alignment objects may be specified. If some of the objects are invisible at that point due to the setting of `break-visibility` or the explicit visibility settings for keys and clefs, the rehearsal mark or bar number is aligned to the first object in the list which is visible. If no objects in the list are visible the object is aligned to the bar line. If the bar line is invisible the object is aligned to the place where the bar line would be.

>     % The rehearsal mark will be aligned
>     % to the right edge of the Key Signature
>     \override Score.RehearsalMark.break-align-symbols =
>                 #'(key-signature clef)
>     \key a \major
>     \clef treble
>     \mark "↓"
>     e'1
>     % The rehearsal mark will be aligned
>     % to the right edge of the Clef
>     \set Staff.explicitKeySignatureVisibility = #all-invisible
>     \override Score.RehearsalMark.break-align-symbols =
>                 #'(key-signature clef)
>     \key a \major
>     \clef bass
>     \mark "↓"
>     gis,1
>     % The rehearsal mark will be centered
>     % above the Bar Line
>     \set Staff.explicitKeySignatureVisibility = #all-invisible
>     \set Staff.explicitClefVisibility = #all-invisible
>     \override Score.RehearsalMark.break-align-symbols =
>                 #'(key-signature clef)
>     \key a \major
>     \clef treble
>     \mark "↓"
>     e'1

The alignment of the rehearsal mark relative to the notation object can be changed, as shown in the following example. In a score with multiple staves, this setting should be done for all the staves.

>     % The RehearsalMark will be aligned
>     % with the right edge of the Key Signature
>     \override Score.RehearsalMark.break-align-symbols =
>                 #'(key-signature)
>     \key a \major
>     \clef treble
>     \time 4/4
>     \mark "↓"
>     e'1
>     % The RehearsalMark will be centered
>     % above the Key Signature
>     \once \override Score.KeySignature.break-align-anchor-alignment =
>                       #CENTER
>     \mark "↓"
>     \key a \major
>     e'1
>     % The RehearsalMark will be aligned
>     % with the left edge of the Key Signature
>     \once \override Score.KeySignature.break-align-anchor-alignment =
>                       #LEFT
>     \key a \major
>     \mark "↓"
>     e'1

The rehearsal mark can also be offset to the right or left of the left edge by an arbitrary amount. The units are staff-spaces:

>     % The RehearsalMark will be aligned
>     % with the left edge of the Key Signature
>     % and then shifted right by 3.5 staff-spaces
>     \override Score.RehearsalMark.break-align-symbols =
>                 #'(key-signature)
>     \once \override Score.KeySignature.break-align-anchor = #3.5
>     \key a \major
>     \mark "↓"
>     e'1
>     % The RehearsalMark will be aligned
>     % with the left edge of the Key Signature
>     % and then shifted left by 2 staff-spaces
>     \once \override Score.KeySignature.break-align-anchor = #-2
>     \key a \major
>     \mark "↓"
>     e'1

#### LilyPond — Notation Reference v2.22.2 (stable-branch).