[ << Spacing issues ] | [Top][Contents][Index] | [ Changing defaults >> ] |
[ < Flexible vertical spacing within systems ] | [ Up : Flexible vertical spacing within systems ] | [ Spacing of ungrouped staves > ] |
Within-system spacing properties
The within-system vertical spacing mechanisms are controlled by
two sets of grob properties. The first set is associated with the
VerticalAxisGroup
grob, which is created by all staves and
non-staff lines. The second set is associated with the
StaffGrouper
grob, which can be created by staff groups,
but only if explicitly called. These properties are described
individually at the end of this section.
The names of these properties (except for staff-affinity
)
follow the format item1-item2-spacing
, where
item1
and item2
are the items to be
spaced. Note that item2
is not necessarily below
item1
; for example,
nonstaff-relatedstaff-spacing
will measure upwards from the
non-staff line if staff-affinity
is UP
.
Each distance is measured between the reference
points9 of
the two items. The reference point for a staff is the vertical
center of its StaffSymbol
(i.e., the middle line if
line-count
is odd; the middle space if line-count
is
even). The reference points for individual non-staff lines are
given in the following table:
Non-staff line Reference point ChordNames
baseline NoteNames
baseline Lyrics
baseline Dynamics
mid-height of ‘m’ FiguredBass
baseline of topmost element FretBoards
top line
In the following image, horizontal lines indicate the positions of these reference points:
Each of the vertical spacing grob properties (except
staff-affinity
) uses the same alist structure as the
\paper
spacing variables discussed in
Flexible vertical spacing \paper
variables.
Specific methods
for modifying alists are discussed in Modifying alists.
Grob properties should be adjusted with an \override
inside
a \score
or \layout
block, and not inside a
\paper
block.
The following example demonstrates the two ways these alists can be modified. The first declaration updates one key value individually, and the second completely redefines the property:
\new Staff \with { \override VerticalAxisGroup .default-staff-staff-spacing.basic-distance = 10 } { … } \new Staff \with { \override VerticalAxisGroup.default-staff-staff-spacing = #'((basic-distance . 10) (minimum-distance . 9) (padding . 1) (stretchability . 10)) } { … }
To change any spacing settings globally, put them in the
\layout
block:
\layout { \context { \Staff \override VerticalAxisGroup .default-staff-staff-spacing .basic-distance = 10 } }
Standard settings for the vertical spacing grob properties are listed in VerticalAxisGroup and StaffGrouper. Default overrides for specific types of non-staff lines are listed in the relevant context descriptions in Contexts.
Properties of the VerticalAxisGroup
grob
VerticalAxisGroup
properties are typically adjusted with an
\override
at the Staff
level (or equivalent).
staff-staff-spacing
-
Used to determine the distance between the current staff and the staff just below it in the same system, even if one or more non-staff lines (such as
Lyrics
) are placed between the two staves. Does not apply to the bottom staff of a system.Initially, the
staff-staff-spacing
of aVerticalAxisGroup
is a Scheme function that applies the properties of theStaffGrouper
if the staff is part of a group, or thedefault-staff-staff-spacing
of the staff otherwise. This allows staves to be spaced differently when they are grouped. For uniform spacing regardless of grouping, this function may be replaced by a flexible-spacing alist, using the complete-redefinition form of override shown above. If only some values are specified in an override, missing values will be taken fromdefault-staff-staff-spacing
(if it has values for them). default-staff-staff-spacing
A flexible-spacing alist defining the
staff-staff-spacing
used for ungrouped staves, unlessstaff-staff-spacing
has been explicitly set with an\override
.staff-affinity
The direction of the staff to use for spacing the current non-staff line. Choices are
UP
,DOWN
, andCENTER
. IfCENTER
, the non-staff line will be placed equidistant between the two nearest staves on either side, unless collisions or other spacing constraints prevent this. Adjacent non-staff lines should have non-increasingstaff-affinity
from top to bottom, e.g., a non-staff line set toUP
should not immediately follow one that is set toDOWN
. Non-staff lines at the top of a system should useDOWN
; those at the bottom should useUP
. Settingstaff-affinity
for a staff causes it to be treated as a non-staff line. Settingstaff-affinity
to#f
causes a non-staff line to be treated as a staff. Settingstaff-affinity
toUP
,CENTER
, orDOWN
causes a staff to be spaced as a non-staff line.nonstaff-relatedstaff-spacing
The distance between the current non-staff line and the nearest staff in the direction of
staff-affinity
, if there are no non-staff lines between the two, andstaff-affinity
is eitherUP
orDOWN
. Ifstaff-affinity
isCENTER
, thennonstaff-relatedstaff-spacing
is used for the nearest staves on both sides, even if other non-staff lines appear between the current one and either of the staves. This means that the placement of a non-staff line depends on both the surrounding staves and the surrounding non-staff lines. Setting thestretchability
of one of these types of spacing to a small value will make that spacing dominate. Setting thestretchability
to a large value will make that spacing have little effect.nonstaff-nonstaff-spacing
The distance between the current non-staff line and the next non-staff line in the direction of
staff-affinity
, if both are on the same side of the related staff, andstaff-affinity
is eitherUP
orDOWN
.nonstaff-unrelatedstaff-spacing
The distance between the current non-staff line and the staff in the opposite direction from
staff-affinity
, if there are no other non-staff lines between the two, andstaff-affinity
is eitherUP
orDOWN
. This can be used, for example, to require a minimum amount of padding between aLyrics
line and the staff to which it does not belong.
Properties of the StaffGrouper
grob
StaffGrouper
properties are typically adjusted with an
\override
at the StaffGroup
level (or equivalent).
staff-staff-spacing
The distance between consecutive staves within the current staff group. The
staff-staff-spacing
property of an individual staff’sVerticalAxisGroup
grob can be overridden with different spacing settings for that staff.staffgroup-staff-spacing
The distance between the last staff of the current staff group and the staff just below it in the same system, even if one or more non-staff lines (such as
Lyrics
) exist between the two staves. Does not apply to the bottom staff of a system. Thestaff-staff-spacing
property of an individual staff’sVerticalAxisGroup
grob can be overridden with different spacing settings for that staff.
See also
Notation Reference:
Flexible vertical spacing \paper
variables,
Modifying alists.
Installed Files: ly/engraver-init.ly, scm/define-grobs.scm.
Internals Reference: Contexts, VerticalAxisGroup, StaffGrouper.
Footnotes
(9)
This is a sloppy formulation. For contexts, the
positions of grobs along the x-axis are computed by LilyPond’s
spacing algorithm (using PaperColumn
objects and the like
for alignment); this means that the only relevant information here
is the vertical position. In other words, a reference ‘point’
of a context is the y-coordinate position to which other grobs
are aligned to.
[ << Spacing issues ] | [Top][Contents][Index] | [ Changing defaults >> ] |
[ < Flexible vertical spacing within systems ] | [ Up : Flexible vertical spacing within systems ] | [ Spacing of ungrouped staves > ] |