[ << Changing defaults ]	[Top][Contents][Index]	[ Notation manual tables >> ]
[ < Rotating markup ]	[ Up : Useful concepts and properties ]	[ Setting X-offset and Y-offset directly > ]

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

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
Using the side-position-interface
Using the self-alignment-interface
Using the break-alignable-interface

---

[ << Changing defaults ]	[Top][Contents][Index]	[ Notation manual tables >> ]
[ < Aligning objects ]	[ Up : Aligning objects ]	[ Using the side-position-interface > ]

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

---

[ << Changing defaults ]	[Top][Contents][Index]	[ Notation manual tables >> ]
[ < Setting X-offset and Y-offset directly ]	[ Up : Aligning objects ]	[ Using the self-alignment-interface > ]

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 property	direction 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.

---

[ << Changing defaults ]	[Top][Contents][Index]	[ Notation manual tables >> ]
[ < Using the side-position-interface ]	[ Up : Aligning objects ]	[ Using the break-alignable-interface > ]

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

---

[ << Changing defaults ]	[Top][Contents][Index]	[ Notation manual tables >> ]
[ < Using the self-alignment-interface ]	[ Up : Aligning objects ]	[ Modifying stencils > ]

Using the break-alignable-interface

Rehearsal marks, text marks, bar numbers, and more generally all objects with break-alignable-interface, collectively referred to as “break-alignable objects”, may be aligned with notation objects such as bar lines, key signatures, time signatures, and generally any object with break-aligned-interface. To be more precise, break-aligned items have a break-align-symbol property, providing symbols that can be used as ‘anchor points’ for other objects via the break-align-symbols property. See break-alignment-interface, for a complete list of available symbols.

Each type of object has its own default reference point, to which break-alignable items are aligned:

\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% to the right edge of the clef
\override Score.TextMark.break-align-symbols =
            #'(clef)
\key a \major
\clef treble
\textMark "↓"
e'1
% The text mark will be aligned
% to the left edge of the time signature
\override Score.TextMark.break-align-symbols =
            #'(time-signature)
\key a \major
\clef treble
\time 3/4
\textMark "↓"
e'2.
% The text mark will be centered
% above the breathing mark
\override Score.TextMark.break-align-symbols =
            #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
e'1
\breathe
\textEndMark "↓"

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.

\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% to the right edge of the key signature
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef treble
\textMark "↓"
e'1
% The text mark will be aligned
% to the right edge of the clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef bass
\textMark "↓"
gis,1
% The text mark will be centered
% above the bar line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef treble
\textMark "↓"
e'1

The alignment of the break-alignable item 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.

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

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

\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% with the left edge of the key signature
% and then shifted right by 3.5 staff spaces
\override Score.TextMark.break-align-symbols =
            #'(key-signature)
\once \override Score.KeySignature.break-align-anchor = #3.5
\key a \major
\textMark "↓"
e'1
% The text mark 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
\textMark "↓"
e'1

---

[ << Changing defaults ]	[Top][Contents][Index]	[ Notation manual tables >> ]
[ < Using the self-alignment-interface ]	[ Up : Aligning objects ]	[ Modifying stencils > ]

<< Back to Documentation Index

LilyPond — Notation Reference v2.24.4 (stable-branch).