LilyPond Notation Reference: 5.4.7 Visibility of objects

### 5.4.7 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

#### 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

#### 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

#### 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`
`KeySignature` | `Staff` | `begin-of-line-visible`
`OctavateEight` | `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
- OctavateEight – see below

#### 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 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

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

Jiné jazyky: deutsch, español, 日本語.

#### LilyPond — Notation Reference