lilypond-learning: Properties of layout objects
4.2.1 Properties of layout objects
----------------------------------
Suppose you have a slur in a score which, to your mind, appears too thin
and you’d like to draw it a little heavier. How do you go about doing
this? You know from the statements earlier about the flexibility of
LilyPond that such a thing should be possible, and you would probably
guess that an ‘\override’ command would be needed. But is there a
heaviness property for a slur, and if there is, how might it be
modified? This is where the Internals Reference manual comes in. It
contains all the information you might need to construct this and all
other ‘\override’ commands.
Before we look at the Internals Reference a word of warning. This is
a *reference* document, which means there is little or no explanation
contained within it: its purpose is to present information precisely and
concisely. This means it might look daunting at first sight. Don’t
worry! The guidance and explanation presented here will enable you to
extract the information from the Internals Reference for yourself with
just a little practice.
Let’s use a concrete example with a simple fragment of real music:
{
\key es \major
\time 6/8
{
r4 bes8 bes[( g]) g |
g8[( es]) es d[( f]) as |
as8 g
}
\addlyrics {
The man who | feels love's sweet e -- | mo -- tion
}
}
[image src="" alt="[image of music]" text="image of music" ]
Suppose now that we decide we would like the slurs to be a little
heavier. Is this possible? The slur is certainly a layout object, so
the question is, ‘Is there a property belonging to a slur which controls
the heaviness?’ To answer this we must look in the Internals Reference,
or IR for short.
The IR for the version of LilyPond you are using may be found on the
LilyPond website at <http://lilypond.org>. Go to the documentation page
and click on the Internals Reference link. For learning purposes you
should use the standard HTML version, not the ‘one big page’ or the PDF.
For the next few paragraphs to make sense you will need to actually do
this as you read.
Under the heading *Top* you will see five links. Select the link to
the _Backend_, which is where information about layout objects is to be
found. There, under the heading *Backend*, select the link to _All
layout objects_. The page that appears lists all the layout objects
used in your version of LilyPond, in alphabetic order. Select the link
to Slur, and the properties of Slurs are listed.
An alternative way of finding this page is from the Notation
Reference. On one of the pages that deals with slurs you may find a
link to the Internals Reference. This link will take you directly to
this page, but if you have an idea about the name of the layout object
to be tweaked, it is easier to go straight to the IR and search there.
This Slur page in the IR tells us first that Slur objects are created
by the Slur_engraver. Then it lists the standard settings. Browse
through them looking for a property that might control the heaviness of
slurs, and you should find
thickness (number)
1.2
Line thickness, generally measured in line-thickness
This looks a good bet to change the heaviness. It tells us that the
value of ‘thickness’ is a simple _number_, that the default value is
1.2, and that the units are in another property called ‘line-thickness’.
As we said earlier, there are few to no explanations in the IR, but
we already have enough information to try changing the slur thickness.
We see that the name of the layout object is ‘Slur’, that the name of
the property to change is ‘thickness’ and that the new value should be a
number somewhat larger than 1.2 if we are to make slurs thicker.
We can now construct the ‘\override’ command by simply substituting
the values we have found for the names, omitting the context. Let’s use
a very large value for the thickness at first, so we can be sure the
command is working. We get:
\override Slur.thickness = #5.0
Don’t forget the ‘#’ preceding the new value!
The final question is, ‘Where should this command be placed?’ While
you are unsure and learning, the best answer is, ‘Within the music,
before the first slur and close to it.’ Let’s do that:
{
\key es \major
\time 6/8
{
% Increase thickness of all following slurs from 1.2 to 5.0
\override Slur.thickness = #5.0
r4 bes8 bes[( g]) g |
g8[( es]) es d[( f]) as |
as8 g
}
\addlyrics {
The man who | feels love's sweet e -- | mo -- tion
}
}
[image src="" alt="[image of music]" text="image of music" ]
and we see that the slur is indeed heavier.
So this is the basic way of constructing ‘\override’ commands. There
are a few more complications that we shall meet in later sections, but
you now know all the essentials required to make up your own – but you
will still need some practice. This is provided in the examples which
follow.
Finding the context
...................
But first, what if we had needed to specify the Context? What should it
be? We could guess that slurs are in the Voice context, as they are
clearly closely associated with individual lines of music, but can we be
sure? To find out, go back to the top of the IR page describing the
Slur, where it says ‘Slur objects are created by: Slur engraver’. So
slurs will be created in whichever context the ‘Slur_engraver’ is in.
Follow the link to the ‘Slur_engraver’ page. At the very bottom it
tells us that ‘Slur_engraver’ is part of seven Voice contexts, including
the standard voice context, ‘Voice’, so our guess was correct. And
because ‘Voice’ is one of the lowest level contexts which is implied
unambiguously by the fact that we are entering notes, we can omit it in
this location.
Overriding once only
....................
As you can see, _all_ the slurs are thicker in the final example above.
But what if we wanted just the first slur to be thicker? This is
achieved with the ‘\once’ command. Placed immediately before the
‘\override’ command it causes it to change only the slur which begins on
the *immediately following* note. If the immediately following note
does not begin a slur the command has no effect at all – it is not
remembered until a slur is encountered, it is simply discarded. So the
command with ‘\once’ must be repositioned as follows:
{
\key es \major
\time 6/8
{
r4 bes8
% Increase thickness of immediately following slur only
\once \override Slur.thickness = #5.0
bes8[( g]) g |
g8[( es]) es d[( f]) as |
as8 g
}
\addlyrics {
The man who | feels love's sweet e -- | mo -- tion
}
}
[image src="" alt="[image of music]" text="image of music" ]
Now only the first slur is made heavier.
The ‘\once’ command can also be used before the ‘\set’ command.
Reverting
.........
Finally, what if we wanted just the first two slurs to be heavier?
Well, we could use two commands, each preceded by ‘\once’ placed
immediately before each of the notes where the slurs begin:
{
\key es \major
\time 6/8
{
r4 bes8
% Increase thickness of immediately following slur only
\once \override Slur.thickness = #5.0
bes[( g]) g |
% Increase thickness of immediately following slur only
\once \override Slur.thickness = #5.0
g8[( es]) es d[( f]) as |
as8 g
}
\addlyrics {
The man who | feels love's sweet e -- | mo -- tion
}
}
[image src="" alt="[image of music]" text="image of music" ]
or we could omit the ‘\once’ command and use the ‘\revert’ command to
return the ‘thickness’ property to its default value after the second
slur:
{
\key es \major
\time 6/8
{
r4 bes8
% Increase thickness of all following slurs from 1.2 to 5.0
\override Slur.thickness = #5.0
bes[( g]) g |
g8[( es]) es
% Revert thickness of all following slurs to default of 1.2
\revert Slur.thickness
d8[( f]) as |
as8 g
}
\addlyrics {
The man who | feels love's sweet e -- | mo -- tion
}
}
[image src="" alt="[image of music]" text="image of music" ]
The ‘\revert’ command can be used to return any property changed with
‘\override’ back to its default value. You may use whichever method
best suits what you want to do.
That concludes our introduction to the IR, and the basic method of
tweaking. Several examples follow in the later sections of this
Chapter, partly to introduce you to some of the additional features of
the IR, and partly to give you more practice in extracting information
from it. These examples will contain progressively fewer words of
guidance and explanation.