LilyPond Learning Manual: 4.3.1 Visibility and color of objects

### 4.3.1 Visibility and color of objects

In the educational use of music we might wish to print a score with certain elements omitted as an exercise for the student, who is required to supply them. As a simple example, let us suppose the exercise is to supply the missing bar lines in a piece of music. But the bar lines are normally inserted automatically. How do we prevent them printing?

Before we tackle this, let us remember that object properties are grouped in what are called interfaces – see Properties found in interfaces. This is simply to group together those properties that may be used together to tweak a graphical object – if one of them is allowed for an object, so are the others. Some objects then use the properties in some interfaces, others use them from other interfaces. The interfaces which contain the properties used by a particular grob are listed in the IR at the bottom of the page describing that grob, and those properties may be viewed by looking at those interfaces.

We explained how to find information about grobs in Properties of layout objects. Using the same approach, we go to the IR to find the layout object which prints bar lines. Going via Backend and All layout objects we find there is a layout object called `BarLine`. Its properties include two that control its visibility: `break-visibility` and `stencil`. Barline also supports a number of interfaces, including the `grob-interface`, where we find the `transparent` and the `color` properties. All of these can affect the visibility of bar lines (and, of course, by extension, many other layout objects too.) Let’s consider each of these in turn.

### stencil

This property controls the appearance of the bar lines by specifying the symbol (glyph) which should be printed. In common with many other properties, it can be set to print nothing by setting its value to `#f`. Let’s try it, as before, omitting the implied Context, `Voice`:

>     {
>       \time 12/16
>       \override BarLine #'stencil = ##f
>       c4 b8 c d16 c d8 |
>       g,8 a16 b8 c d4 e16 |
>       e8
>     }

The bar lines are still printed. What is wrong? Go back to the IR and look again at the page giving the properties of BarLine. At the top of the page it says “Barline objects are created by: Bar_engraver”. Go to the `Bar_engraver` page. At the bottom it gives a list of Contexts in which the bar engraver operates. All of them are of the type `Staff`, so the reason the `\override` command failed to work as expected is because `Barline` is not in the default `Voice` context. If the context is specified incorrectly, the command simply does not work. No error message is produced, and nothing is logged in the log file. Let’s try correcting it by adding the correct context:

>     {
>       \time 12/16
>       \override Staff.BarLine #'stencil = ##f
>       c4 b8 c d16 c d8 |
>       g,8 a16 b8 c d4 e16 |
>       e8
>     }

Now the bar lines have vanished.

Note, though, that setting the `stencil` property to `#f` will cause errors when the dimensions of the object are required for correct processing. For example, errors will be generated if the `stencil` property of the `NoteHead` object is set to `#f`. If this is the case, you can instead use the `point-stencil` function, which sets the stencil to a object with zero size:

>     {
>       c4 c
>       \once \override NoteHead #'stencil = #point-stencil
>       c4 c
>     }

### break-visibility

We see from the `BarLine` properties in the IR that the `break-visibility` property requires a vector of three booleans. These control respectively whether bar lines are printed at the end of a line, in the middle of lines, and at the beginning of lines. For our example we want all bar lines to be suppressed, so the value we need is `'#(#f #f #f)`. Let’s try that, remembering to include the `Staff` context. Note also that in writing this value we have `#'#` before the opening bracket. The `'#` is required as part of the value to introduce a vector, and the first `#` is required, as always, to precede the value itself in the `\override` command.

>     {
>       \time 12/16
>       \override Staff.BarLine #'break-visibility = #'#(#f #f #f)
>       c4 b8 c d16 c d8 |
>       g,8 a16 b8 c d4 e16 |
>       e8
>     }

And we see this too removes all the bar lines.

### transparent

We see from the properties specified in the `grob-interface` page in the IR that the `transparent` property is a boolean. This should be set to `#t` to make the grob transparent. In this next example let us make the time signature invisible rather than the bar lines. To do this we need to find the grob name for the time signature. Back to the ‘All layout objects’ page in the IR to find the properties of the `TimeSignature` layout object. This is produced by the `Time_signature_engraver` which you can check also lives in the `Staff` context and also supports the `grob-interface`. So the command to make the time signature transparent is:

>     {
>       \time 12/16
>       \override Staff.TimeSignature #'transparent = ##t
>       c4 b8 c d16 c d8 |
>       g,8 a16 b8 c d4 e16 |
>       e8
>     }

The time signature is gone, but this command leaves a gap where the time signature should be. Maybe this is what is wanted for an exercise for the student to fill it in, but in other circumstances a gap might be undesirable. To remove it, the stencil for the time signature should be set to `#f` instead:

>     {
>       \time 12/16
>       \override Staff.TimeSignature #'stencil = ##f
>       c4 b8 c d16 c d8 |
>       g,8 a16 b8 c d4 e16 |
>       e8
>     }

and the difference is obvious: setting the stencil to `#f` removes the object entirely; making the object `transparent` leaves it where it is, but makes it invisible.

### color

Finally let us try making the bar lines invisible by coloring them white. (There is a difficulty with this in that the white bar line may or may not blank out the staff lines where they cross. You may see in some of the examples below that this happens unpredictably. The details of why this is so and how to control it are covered in Painting objects white. But at the moment we are learning about color, so please just accept this limitation for now.)

The `grob-interface` specifies that the color property value is a list, but there is no explanation of what that list should be. The list it requires is actually a list of values in internal units, but, to avoid having to know what these are, several ways are provided to specify colors. The first way is to use one of the ‘normal’ colors listed in the first table in List of colors. To set the bar lines to white we write:

>     {
>       \time 12/16
>       \override Staff.BarLine #'color = #white
>       c4 b8 c d16 c d8 |
>       g,8 a16 b8 c d4 e16 |
>       e8
>     }

and again, we see the bar lines are not visible. Note that white is not preceded by an apostrophe – it is not a symbol, but a function. When called, it provides the list of internal values required to set the color to white. The other colors in the normal list are functions too. To convince yourself this is working you might like to change the color to one of the other functions in the list.

The second way of changing the color is to use the list of X11 color names in the second list in List of colors. However, these must be preceded by another function, which converts X11 color names into the list of internal values, `x11-color`, like this:

>     {
>       \time 12/16
>       \override Staff.BarLine #'color = #(x11-color 'white)
>       c4 b8 c d16 c d8 |
>       g,8 a16 b8 c d4 e16 |
>       e8
>     }

Note that in this case the function `x11-color` takes a symbol as an argument, so the symbol must be preceded by an apostrophe and the two enclosed in brackets.

There is yet a third function, one which converts RGB values into internal colors – the `rgb-color` function. This takes three arguments giving the intensities of the red, green and blue colors. These take values in the range 0 to 1. So to set the color to red the value should be `(rgb-color 1 0 0)` and to white it should be `(rgb-color 1 1 1)`:

>     {
>       \time 12/16
>       \override Staff.BarLine #'color = #(rgb-color 1 1 1)
>       c4 b8 c d16 c d8 |
>       g,8 a16 b8 c d4 e16 |
>       e8
>     }

Finally, there is also a grey scale available as part of the X11 set of colors. These range from black, `'grey0'`, to white, `'grey100`, in steps of 1. Let’s illustrate this by setting all the layout objects in our example to various shades of grey:

>     {
>       \time 12/16
>       \override Staff.StaffSymbol   #'color = #(x11-color 'grey30)
>       \override Staff.TimeSignature #'color = #(x11-color 'grey60)
>       \override Staff.Clef          #'color = #(x11-color 'grey60)
>       \override Voice.NoteHead      #'color = #(x11-color 'grey85)
>       \override Voice.Stem          #'color = #(x11-color 'grey85)
>       \override Staff.BarLine       #'color = #(x11-color 'grey10)
>       c4 b8 c d16 c d8 |
>       g,8 a16 b8 c d4 e16 |
>       e8
>     }

Note the contexts associated with each of the layout objects. It is important to get these right, or the commands will not work! Remember, the context is the one in which the appropriate engraver is placed. The default context for engravers can be found by starting from the layout object, going from there to the engraver which produces it, and on the engraver page in the IR it tells you in which context the engraver will normally be found.

其它语言：česky, deutsch, español, français, italiano, 日本語, nederlands。

#### LilyPond — Learning Manual