[ << Useful concepts and properties ]	[Top][Contents][Index]	[ Markup commands >> ]
[ < Aligning objects ]	[ Up: Aligning objects ]	[ Using the side-position-interface > ]

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

f'-3
f'-\tweak X-offset 0
  -\tweak Y-offset 0
  -3
f'-\tweak X-offset -1
  -\tweak Y-offset 0.5
  -3

---

[ << Useful concepts and properties ]	[Top][Contents][Index]	[ Markup commands >> ]
[ < Setting X-offset and Y-offset directly ]	[ Up: Aligning objects ]	[ Using the self-alignment-interface > ]

36.9.2 Using the side-position-interface ¶

An object that 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 returns 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 returns the correct value of Y-offset to place the object to the top or bottom of the parent according to value of direction.

Instead of values 0 and 1 you might use the Scheme symbols X and Y for specifying a side axis. Similarly, you might use the symbols DOWN (LEFT) and UP (RIGHT) instead of values -1 and 1 for specifying a direction.

---

[ << Useful concepts and properties ]	[Top][Contents][Index]	[ Markup commands >> ]
[ < Using the side-position-interface ]	[ Up: Aligning objects ]	[ Using the break-alignable-interface > ]

36.9.3 Using the self-alignment-interface ¶

The self-alignment-interface defines objects’ alignment points. This interface applies to many graphical objects in LilyPond (see self-alignment-interface for a list).

The alignment interface is based on the dimension of the grob’s bounding box. The X (Y) coordinate of a grob’s alignment point is a multiple of half the width (height) of this bounding box. In other words, one unit is half the total X (Y) extent of the object.

An X (Y) coordinate of -1 represents the left (lower) edge of the bounding box. An X (Y) coordinate of 0 represents the center. An X (Y) coordinate of 1 represents the right (upper) edge.

A coordinate can be any real number, including values less than -1 or greater than 1.

The image below shows the general case, where both the parent and the ‘self’ grob have non-zero horizontal and vertical alignment parameters to position the alignment points A_P and A_S (these two points are chosen arbitrarily here for the sake of demonstrating the concept).

Self-aligning and parent-aligning objects horizontally ¶

The horizontal alignment of an object that 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. Negative values move the object to the right, positive to the left. A value of 0 centers the object (more specifically, its bounding box) on the alignment point of its parent, a value of -1 aligns the left edge of the object to the alignment point of its parent, and a value of 1 aligns the right edge of the object to the alignment point of its parent. The symbols LEFT, CENTER, and RIGHT may be used instead of the values -1, 0, and 1, respectively.

Value #f horizontally aligns the grob using its reference point. This value only works, however, if the grob has a parent; LilyPond returns an error if it has none.

If an object has a parent, its horizontal alignment is also similarly affected by the parent-alignment-X property.

The following image shows various self-alignment-X and parent-alignment-X value combinations for TextScript objects whose parents are their associated NoteColumn grobs. Here, the TextScript grobs are gray boxes having the horizontal extent '(-1 . 3) and the vertical extent '(-1 . 2); the reference point of the boxes is marked with a dot. The reference point of a NoteColumn grob is always (0,0); suspended NoteHead grobs (i.e., note heads in chords on the other, non-default side of the stem) stick out but are not taken into account. The horizontal position of the parent-alignment point is represented by a vertical line, and the alignment point of TextScript is marked with a cross.

Either \override or \tweak can be used to modify the value of self-alignment-X. To separately align several annotations on a single note, however, you must use \tweak.

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 farther to the right"

Self-aligning objects vertically ¶

Objects may be aligned vertically (using self-alignment-Y) 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 very large numbers may be required. A value of -1 aligns the lower edge of the object with the alignment point of the parent object, a value of 0 aligns the center of the object with the alignment point of the parent, and a value of 1 aligns the top edge of the object with the alignment point of the parent. The symbols DOWN, CENTER, and UP may be substituted for -1, 0, and 1, respectively.

Value #f vertically aligns the grob using its reference point. This value only works, however, if the grob has a parent; LilyPond returns an error if it has none.

Note that using parent-alignment-Y almost never works; there are too many other constraints that influence how an object is vertically positioned relative to its parent grob. Take the previous image as an example: the vertical value of the parent’s reference point (the NoteColumn grob) depends on the attached object (the TextScript grob) together with various padding property values – as can be seen, LilyPond tries to move the TextScript grobs as near as possible to the staff. Due to this interdependency between parent and object itself, accessing or modifying parent-alignment-Y usually fails and often produces warnings about ‘cyclic dependencies’.

The standard way to adjust vertical distances is to modify one of the various padding properties LilyPond offers, for example, outside-staff-padding.

Self-aligning objects in both directions ¶

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

The following example shows how to adjust the position of instrument names. The InstrumentName grob is an example of a grob that has no parent: self-alignment-X gives an alignment relative to the left margin and the start of the staff (i.e., the system’s indentation), and self-alignment-Y aligns the InstrumentName grob relative to the related staff’s middle line.

sn = #(define-music-function (name x y) (string? number? number?)
       #{
         \new RhythmicStaff \with {
           instrumentName = #name
           \override InstrumentName.self-alignment-X = #x
           \override InstrumentName.self-alignment-Y = #y
         } { f'1 }
       #})

<<
  \sn "AAA" #1 #3
  \sn "AAAAA" #1 #3
  \sn "BBB" #0.5 #1.5
  \sn "BBBBB" #0.5 #1.5
  \sn "CCC" #0 #0
  \sn "CCCCC" #0 #0
  \sn "DDD" #-0.5 #-1.5
  \sn "DDDDD" #-0.5 #-1.5
  \sn "EEE" #-1 #-3
  \sn "EEEEE" #-1 #-3
>>

\layout {
  indent = 5\cm

  \context {
    \RhythmicStaff
    \override VerticalAxisGroup.staff-staff-spacing =
      #'((minimum-distance . 0)
         (basic-distance . 0)
         (padding . 2.5))
  }
}

---

[ << Useful concepts and properties ]	[Top][Contents][Index]	[ Markup commands >> ]
[ < Using the self-alignment-interface ]	[ Up: Aligning objects ]	[ Modifying stencils > ]

36.9.4 Using the break-alignable-interface ¶

Rehearsal marks, text marks, bar numbers, and more generally all objects that support the 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 that supports the 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
% Align text mark to the right edge of the clef.
\override Score.TextMark.break-align-symbols = #'(clef)
\clef treble
\key a \major
\textMark "↓"
e'1

% Align text mark to the left edge of the time signature.
\override Score.TextMark.break-align-symbols = #'(time-signature)
\key a \major
\time 3/4
\textMark "↓"
e'2.

% Center text mark above the breathing mark.
\override Score.TextMark.break-align-symbols = #'(breathing-sign)
\key a \major
\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
% Align text mark 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

% Align text mark 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

% Center text mark 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
% Align text mark 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

% Center text mark above the key signature
\once \override
  Score.KeySignature.break-align-anchor-alignment = #CENTER
\textMark "↓"
\key a \major
e'1

% Align text mark 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
% Align text mark with the left edge of the key signature,
% 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

% Align text mark with the left edge of the key signature,
% then shifted left by 2 staff spaces.
\once \override Score.KeySignature.break-align-anchor = -2
\key a \major
\textMark "↓"
e'1

See also ¶