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.

The stencil property

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:

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:

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 an object
with zero size:

The break-visibility property

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) (also available
under the name all-invisible). Let’s try that, remembering to include
the Staff context. Note also that in writing this value we
have ## before the opening parenthesis. One # is required
as part of vector constant syntax, and the first # is
required, as always, to precede the value itself in the
\override command.

The transparent property

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:

In either case, 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:

and the difference is obvious: setting the stencil to #f
(possibly via \omit)
removes the object entirely; making the object transparent
(which can be done using \hide)
leaves it where it is, but makes it invisible.

The color property

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:

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 variable. When evaluated, it provides
the list of internal values required to set the color to
white. The other colors in the normal list are variables
too. To convince yourself this is working you might like
to change the color to one of the other variables 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 are mapped to the actual values by the function
x11-color which
converts X11 color symbols into the list of internal values like this:

Note that in this case the function x11-color takes
a symbol as an argument, so the symbol must be preceded by
an apostrophe to keep it from being evaluated as a variable, and
the whole function call has to be enclosed in parentheses.

There is another 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):

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:

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.