3.1.159 VerticalAxisGroup

An auxiliary grob to group everything contained in a context like Staff, Lyrics, Dynamics, etc. See also StaffGrouper and VerticalAlignment.

VerticalAxisGroup objects are created by the following engraver(s): Axis_group_engraver.

Standard settings:

axes (list):

List of axis numbers. In the case of alignment grobs, this should contain only one number.

default-staff-staff-spacing (list):
'((basic-distance . 9)
  (minimum-distance . 8)
  (padding . 1))

The settings to use for staff-staff-spacing when it is unset, for ungrouped staves and for grouped staves that do not have the relevant StaffGrouper property set (staff-staff-spacing or staffgroup-staff-spacing).

nonstaff-unrelatedstaff-spacing (alist, with symbols as keys):
'((padding . 0.5))

The spacing alist controlling the distance between the current non-staff line and the nearest staff in the opposite direction from staff-affinity, if there are no other non-staff lines between the two, and staff-affinity is either UP or DOWN. See staff-staff-spacing for a description of the alist structure.

outside-staff-placement-directive (symbol):


One of four directives telling how outside staff objects should be placed.

  • left-to-right-greedy – Place each successive grob from left to right.
  • left-to-right-polite – Place a grob from left to right only if it does not potentially overlap with another grob that has been placed on a pass through a grob array. If there is overlap, do another pass to determine placement.
  • right-to-left-greedy – Same as left-to-right-greedy, but from right to left.
  • right-to-left-polite – Same as left-to-right-polite, but from right to left.
show-vertical-skylines (boolean):


If true, print this grob’s vertical skylines. This is meant for debugging purposes.

skyline-horizontal-padding (number):


For determining the vertical distance between two staves, it is possible to have a configuration which would result in a tight interleaving of grobs from the top staff and the bottom staff. The larger this parameter is, the farther apart the staves are placed in such a configuration.

staff-staff-spacing (alist, with symbols as keys):

#<unpure-pure-container #<procedure ly:axis-group-interface::calc-staff-staff-spacing (_)> #<procedure ly:axis-group-interface::calc-pure-staff-staff-spacing (_ _ _)> >

When applied to a staff-group’s StaffGrouper grob, this spacing alist controls the distance between consecutive staves within the staff-group. When applied to a staff’s VerticalAxisGroup grob, it controls the distance between the staff and the nearest staff below it in the same system, replacing any settings inherited from the StaffGrouper grob of the containing staff-group, if there is one. This property remains in effect even when non-staff lines appear between staves. The alist can contain the following keys:

  • basic-distance – the vertical distance, measured in staff-spaces, between the reference points of the two items when no collisions would result, and no stretching or compressing is in effect.
  • minimum-distance – the smallest allowable vertical distance, measured in staff-spaces, between the reference points of the two items, when compressing is in effect.
  • padding – the minimum required amount of unobstructed vertical whitespace between the bounding boxes (or skylines) of the two items, measured in staff-spaces.
  • stretchability – a unitless measure of the dimension’s relative propensity to stretch. If zero, the distance will not stretch (unless collisions would result).
vertical-skylines (pair of skylines):


Two skylines, one above and one below this grob.

X-extent (pair of numbers):


Extent (size) in the X direction, measured in staff-space units, relative to object’s reference point.

Y-extent (pair of numbers):

#<unpure-pure-container #<procedure ly:hara-kiri-group-spanner::y-extent (_)> #<procedure ly:hara-kiri-group-spanner::pure-height (_ _ _)> >

Extent (size) in the Y direction, measured in staff-space units, relative to object’s reference point.

Y-offset (number):


The vertical amount that this object is moved relative to its Y-parent.

Note that many objects have special positioning considerations, which cause any setting of Y-offset to be ignored or modified, even though the object supports the self-alignment-interface.

This object supports the following interface(s): axis-group-interface, grob-interface, hara-kiri-group-spanner-interface, outside-staff-axis-group-interface and spanner-interface.

This object is of class Spanner (characterized by spanner-interface).

LilyPond Internals Reference v2.25.18 (development-branch).