LilyPond Notation Reference: 5.4.6 Visibility of objects

[ << Changing defaults ]	[Top][Contents][Index][ ? ]			[ Notation manual tables >> ]
[ < Using the line-spanner-interface ]		[ Up : Useful concepts and properties ]	[ Removing the stencil > ]

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.

[ << Changing defaults ]	[Top][Contents][Index][ ? ]			[ Notation manual tables >> ]
[ < Visibility of objects ]		[ Up : Visibility of objects ]	[ Making objects transparent > ]

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

This rather common operation has a shortcut \omit:

a1 a
\omit Score.BarLine
a a
\undo \omit Score.BarLine
a a a

[ << Changing defaults ]	[Top][Contents][Index][ ? ]			[ Notation manual tables >> ]
[ < Removing the stencil ]		[ Up : Visibility of objects ]	[ Painting objects white > ]

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

This rather common operation has a shortcut \hide:

a4 a
\once \hide NoteHead
a a

[ << Changing defaults ]	[Top][Contents][Index][ ? ]			[ Notation manual tables >> ]
[ < Making objects transparent ]		[ Up : Visibility of objects ]	[ Using break-visibility > ]

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

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

[ << Changing defaults ]	[Top][Contents][Index][ ? ]			[ Notation manual tables >> ]
[ < Painting objects white ]		[ Up : Visibility of objects ]	[ Special considerations > ]

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:

Function	Vector	Before	At no	After
form	form	break	break	break
`all-visible`	`'#(#t #t #t)`	yes	yes	yes
`begin-of-line-visible`	`'#(#f #f #t)`	no	no	yes
`center-visible`	`'#(#f #t #f)`	no	yes	no
`end-of-line-visible`	`'#(#t #f #f)`	yes	no	no
`begin-of-line-invisible`	`'#(#t #t #f)`	yes	yes	no
`center-invisible`	`'#(#t #f #t)`	yes	no	yes
`end-of-line-invisible`	`'#(#f #t #t)`	no	yes	yes
`all-invisible`	`'#(#f #f #f)`	no	no	no

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 object	Usual context	Default setting
`BarLine`	`Score`	calculated
`BarNumber`	`Score`	`begin-of-line-visible`
`BreathingSign`	`Voice`	`begin-of-line-invisible`
`Clef`	`Staff`	`begin-of-line-visible`
`Custos`	`Staff`	`end-of-line-visible`
`DoublePercentRepeat`	`Voice`	`begin-of-line-invisible`
`KeyCancellation`	`Staff`	`begin-of-line-invisible`
`KeySignature`	`Staff`	`begin-of-line-visible`
`ClefModifier`	`Staff`	`begin-of-line-visible`
`RehearsalMark`	`Score`	`end-of-line-invisible`
`TimeSignature`	`Staff`	`all-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

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:

Bar lines cannot be printed at start of line.
A bar number cannot be printed at the start of the first line unless it is set to be different from 1.
Clef – see below
Double percent repeats are either all printed or all suppressed. Use begin-of line-invisible to print and all-invisible to suppress.
Key signature – see below
ClefModifier – see below

[ << Changing defaults ]	[Top][Contents][Index][ ? ]			[ Notation manual tables >> ]
[ < Using break-visibility ]		[ Up : Visibility of objects ]	[ Line styles > ]

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

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

Visibility of cancelling accidentals

To remove the cancelling 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

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

Note that when changing the key to C major or A minor the cancelling accidentals would be the only indication of the key change. In this case setting printKeyCancellation to #f has no effect:

\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.printKeyCancellation = ##f
\key c \major
f4 g a b \break
f4 g a b
f4 g a b

To suppress the cancelling accidentals even when the key is changed to C major or A minor, override the visibility of the KeyCancellation grob instead:

\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Staff.KeyCancellation.break-visibility = #all-invisible
\key c \major
f4 g a b \break
f4 g a b
f4 g a b

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.

Transposed clefs

The small transposition symbol on transposed clefs is produced by the ClefModifier 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 ClefModifier layout objects to suppress transposition symbols for invisible clefs.

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