5.4.6 Visibility of objects

There are four main ways in which the visibility of layout objects can be controlled: their stencil can be removed, they can be made transparent, they can be colored white, or their break-visibility property can be overridden. The first three apply to all layout objects; the last to just a few – the breakable objects. The Learning Manual introduces these four techniques, see Visibility and color of objects.

There are also a few other techniques which are specific to certain layout objects. These are covered under Special considerations.


Removing the stencil

Every layout object has a stencil property. By default this is set to the specific function which draws that object. If this property is overridden to #f no function will be called and the object will not be drawn. The default action can be recovered with \revert.

a1 a
\override Score.BarLine #'stencil = ##f
a a
\revert Score.BarLine #'stencil
a a a

[image of music]


Making objects transparent

Every layout object has a transparent property which by default is set to #f. If set to #t the object still occupies space but is made invisible.

a4 a
\once \override NoteHead #'transparent = ##t
a a

[image of music]


Painting objects white

Every layout object has a color property which by default is set to black. If this is overridden to white the object will be indistinguishable from the white background. However, if the object crosses other objects the color of the crossing points will be determined by the order in which they are drawn, and this may leave a ghostly image of the white object, as shown here:

\override Staff.Clef #'color = #white
a1

[image of music]

This may be avoided by changing the order of printing the objects. All layout objects have a layer property which should be set to an integer. Objects with the lowest value of layer are drawn first, then objects with progressively higher values are drawn, so objects with higher values overwrite objects with lower values. By default most objects are assigned a layer value of 1, although a few objects, including StaffSymbol and BarLine, are assigned a value of 0. The order of printing objects with the same value of layer is indeterminate.

In the example above the white clef, with a default layer value of 1, is drawn after the staff lines (default layer value 0), so overwriting them. To change this, the Clef object must be given in a lower value of layer, say -1, so that it is drawn earlier:

\override Staff.Clef #'color = #white
\override Staff.Clef #'layer = #-1
a1

[image of music]


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 behaviour 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 pre-defined 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
DoublePercentRepeatVoicebegin-of-line-invisible
KeySignatureStaffbegin-of-line-visible
OctavateEightStaffbegin-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:

f4 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:


Special considerations

Visibility following explicit changes

The break-visibility property controls the visibility of key signatures and changes of clef only at the start of lines, i.e. after a break. It has no effect on the visibility of the key signature or clef following an explicit key change or an explicit clef change within or at the end of a line. In the following example the key signature following the explicit change to B-flat major is still visible, even though all-invisible is set.

\key g \major
f4 g a b
% Try to remove all key signatures
\override Staff.KeySignature #'break-visibility = #all-invisible
\key bes \major
f4 g a b
\break
f4 g a b
f4 g a b

[image of music]

The visibility of such explicit key signature and clef changes is controlled by the explicitKeySignatureVisibility and explicitClefVisibility properties. These are the equivalent of the break-visibility property and both take a vector of three booleans or the predefined functions listed above, exactly like break-visibility. Both are properties of the Staff context, not the layout objects themselves, and so they are set using the \set command. Both are set by default to all-visible. These properties control only the visibility of key signatures and clefs resulting from explicit changes and do not affect key signatures and clefs at the beginning of lines; break-visibility must still be overridden in the appropriate object to remove these.

\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Staff.KeySignature #'break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b

[image of music]

Visibility of cautionary accidentals

To remove the cautionary accidentals printed at an explicit key change, set the Staff context property printKeyCancellation to #f:

\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.printKeyCancellation = ##f
\override Staff.KeySignature #'break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b

[image of music]

With these overrides only the accidentals before the notes remain to indicate the change of key.

Automatic bars

As a special case, the printing of bar lines can also be turned off by setting the automaticBars property in the Score context. If set to #f, bar lines will not be printed automatically; they must be explicitly created with a \bar command. Unlike the \cadenzaOn predefined command, measures are still counted. Bar generation will resume according to that count if this property is later set to #t. When set to #f, line breaks can occur only at explicit \bar commands.

Octavated clefs

The small octavation symbol on octavated clefs is produced by the OctavateEight layout object. Its visibility is automatically inherited from the Clef object, so it is not necessary to apply any required break-visibility overrides to the OctavateEight layout objects to suppress octavation symbols for invisible clefs.

For explicit clef changes, the explicitClefVisibility property controls both the clef symbol and any octavation symbol associated with it.

See also

Learning Manual: Visibility and color of objects.


Other languages: deutsch, español, français, italiano, 日本語.
About automatic language selection.

LilyPond — Notation Reference