Using break-visibility

Most layout objects are printed only once, but some like bar lines, clefs, time signatures and key signatures, may need to be printed twice when a line break occurs – once at the end of the line and again at the start of the next line. Such objects are called breakable, and have a property, the break-visibility property to control their visibility at the three positions in which they may appear – at the start of a line, within a line if they are changed, and at the end of a line if a change takes place there.

For example, the time signature by default will be printed at the start of the first line, but nowhere else unless it changes, when it will be printed at the point at which the change occurs. If this change occurs at the end of a line the new time signature will be printed at the start of the next line and a cautionary time signature will be printed at the end of the previous line as well.

This behavior is controlled by the break-visibility property, which is explained in Visibility and color of objects. This property takes a vector of three Booleans which, in order, determine whether the object is printed at the end of, within the body of, or at the beginning of a line. Or to be more precise, before a line break, where there is no line break, or after a line break.

Alternatively, these eight combinations may be specified by predefined functions, defined in scm/output-lib.scm, where the last three columns indicate whether the layout objects will be visible in the positions shown at the head of the columns:

FunctionVectorBeforeAt noAfter
formformbreakbreakbreak
all-visible#(#t #t #t)yesyesyes
begin-of-line-visible#(#f #f #t)nonoyes
center-visible#(#f #t #f)noyesno
end-of-line-visible#(#t #f #f)yesnono
begin-of-line-invisible#(#t #t #f)yesyesno
center-invisible#(#t #f #t)yesnoyes
end-of-line-invisible#(#f #t #t)noyesyes
all-invisible#(#f #f #f)nonono

The default settings of break-visibility depend on the layout object. The following table shows all the layout objects of interest which are affected by break-visibility and the default setting of this property:

Layout objectUsual contextDefault setting
BarLineScorecalculated
BarNumberScorebegin-of-line-visible
BreathingSignVoicebegin-of-line-invisible
ClefStaffbegin-of-line-visible
CustosStaffend-of-line-visible
DivisioStaffbegin-of-line-invisible
DoublePercentRepeatVoicebegin-of-line-invisible
KeyCancellationStaffbegin-of-line-invisible
KeySignatureStaffbegin-of-line-visible
ClefModifierStaffbegin-of-line-visible
RehearsalMarkScoreend-of-line-invisible
TimeSignatureStaffall-visible

The example below shows the use of the vector form to control the visibility of bar lines:

\relative {
  f'4 g a b
  f4 g a b
  % Remove bar line at the end of the current line
  \once \override Score.BarLine.break-visibility = ##(#f #t #t)
  \break
  f4 g a b
  f4 g a b
}

[image of music]

Although all three components of the vector used to override break-visibility must be present, not all of them are effective with every layout object, and some combinations may even give errors. The following limitations apply:


LilyPond Notation Reference v2.25.17 (development-branch).