lilypond-learning: The outside-staff-priority property
The ‘outside-staff-priority’ property
.....................................
Objects with the lower value of the ‘outside-staff-priority’ property
are placed nearer to the staff, and other outside-staff objects are then
raised as far as necessary to avoid collisions. The
‘outside-staff-priority’ is defined in the ‘grob-interface’ and so is a
property of all layout objects. By default it is set to ‘#f’ for all
within-staff objects, and to a numerical value appropriate to each
outside-staff object when the object is created. The following table
shows the default numerical values for some of the commonest
outside-staff objects.
Note the unusual names for some of the objects: spanner objects are
automatically created to control the vertical positioning of grobs which
(might) start and end at different musical moments, so changing the
‘outside-staff-priority’ of the underlying grob will have no effect.
For example, changing ‘outside-staff-priority’ of the ‘Hairpin’ object
will have no effect on the vertical positioning of hairpins – you must
change ‘outside-staff-priority’ of the associated ‘DynamicLineSpanner’
object instead. This override must be placed at the start of the
spanner, which might include several linked hairpins and dynamics.
Layout Object Priority Controls position
of:
---------------------------------------------------------------------
‘RehearsalMark’ ‘1500’ Rehearsal marks
‘MetronomeMark’ ‘1000’ Metronome marks
‘VoltaBracketSpanner’ ‘600’ Volta brackets
‘TextScript’ ‘450’ Markup text
‘MultiMeasureRestText’ ‘450’ Markup text over
full-bar rests
‘OttavaBracket’ ‘400’ Ottava brackets
‘TextSpanner’ ‘350’ Text spanners
‘DynamicLineSpanner’ ‘250’ All dynamic markings
‘BarNumber’ ‘ 100’ Bar numbers
‘TrillSpanner’ ‘50’ Spanning trills
Here is an example showing the default placement of some of these.
% Set details for later Text Spanner
\override TextSpanner.bound-details.left.text
= \markup { \small \bold Slower }
% Place dynamics above staff
\dynamicUp
% Start Ottava Bracket
\ottava #1
c'4 \startTextSpan
% Add Dynamic Text and hairpin
c4\pp\<
c4
% Add Text Script
c4^Text |
c4 c
% Add Dynamic Text and terminate hairpin
c4\ff c \stopTextSpan |
% Stop Ottava Bracket
\ottava #0
c,4 c c c |
[image src="" alt="[image of music]" text="image of music" ]
This example also shows how to create Text Spanners – text with
extender lines above a section of music. The spanner extends from the
‘\startTextSpan’ command to the ‘\stopTextSpan’ command, and the format
of the text is defined by the ‘\override TextSpanner’ command. For more
details see 
(lilypond-notation)Text spanners.
It also shows how ottava brackets are created.
If the default values of ‘outside-staff-priority’ do not give you the
placing you want, the priority of any of the objects may be overridden.
Suppose we would like the ottava bracket to be placed below the text
spanner in the example above. All we need to do is to look up the
priority of ‘OttavaBracket’ in the IR or in the tables above, and reduce
it to a value lower than that of a ‘TextSpanner’, remembering that
‘OttavaBracket’ is created in the ‘Staff’ context:
% Set details for later Text Spanner
\override TextSpanner.bound-details.left.text
= \markup { \small \bold Slower }
% Place dynamics above staff
\dynamicUp
% Place following Ottava Bracket below Text Spanners
\once \override Staff.OttavaBracket.outside-staff-priority = #340
% Start Ottava Bracket
\ottava #1
c'4 \startTextSpan
% Add Dynamic Text
c4\pp
% Add Dynamic Line Spanner
c4\<
% Add Text Script
c4^Text |
c4 c
% Add Dynamic Text
c4\ff c \stopTextSpan |
% Stop Ottava Bracket
\ottava #0
c,4 c c c |
[image src="" alt="[image of music]" text="image of music" ]
Note that some of these objects, in particular bar numbers, metronome
marks and rehearsal marks, live by default in the ‘Score’ context, so be
sure to use the correct context when these are being overriden.
Slurs by default are classed as within-staff objects, but they often
appear above the staff if the notes to which they are attached are high
on the staff. This can push outside-staff objects such as articulations
too high, as the slur will be placed first. The ‘avoid-slur’ property
of the articulation can be set to ‘'inside’ to bring the articulation
inside the slur, but the ‘avoid-slur’ property is effective only if the
‘outside-staff-priority’ is also set to ‘#f’. Alternatively, the
‘outside-staff-priority’ of the slur can be set to a numerical value to
cause it to be placed along with other outside-staff objects according
to that value. Here’s an example showing the effect of the two methods:
c4( c^\markup { \tiny \sharp } d4.) c8 |
c4(
\once \override TextScript.avoid-slur = #'inside
\once \override TextScript.outside-staff-priority = ##f
c4^\markup { \tiny \sharp } d4.) c8 |
\once \override Slur.outside-staff-priority = #500
c4( c^\markup { \tiny \sharp } d4.) c8 |
[image src="" alt="[image of music]" text="image of music" ]
Changing the ‘outside-staff-priority’ can also be used to control the
vertical placement of individual objects, although the results may not
always be desirable. Suppose we would like “Text3” to be placed above
“Text4” in the example under Automatic behavior, above (see
Automatic behavior). All we need to do is to look up the priority of
‘TextScript’ in the IR or in the tables above, and increase the priority
of “Text3” to a higher value:
c2^"Text1"
c2^"Text2" |
\once \override TextScript.outside-staff-priority = #500
c2^"Text3"
c2^"Text4" |
[image src="" alt="[image of music]" text="image of music" ]
This certainly lifts “Text3” above “Text4” but it also lifts it above
“Text2”, and “Text4” now drops down. Perhaps this is not so good. What
we would really like to do is to position all the annotation at the same
distance above the staff. To do this, we clearly will need to space the
notes out horizontally to make more room for the text. This is done
using the ‘textLengthOn’ command.
Info Catalog
lilypond-learning: Outside-staff objects
lilypond-learning: The textLengthOn command