The outside-staff-priority property (LilyPond Learning Manual)

[ << Tweaking output ]	[Top][Contents][Index]	[ Templates >> ]
[ < Outside-staff objects ]	[ Up : Outside-staff objects ]	[ The `\textLengthOn` command > ]

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. See Default values for outside-staff-priority for an exhaustive table.

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.

Here is an example showing the default placement of some of these.

% set details for later TextSpanner
\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
c''4\pp\<
c''4
% add text script
c''4^Text |
c''4 c''
% add dynamic text and terminate hairpin
c''4\ff c'' \stopTextSpan |
% stop ottava bracket
\ottava 0
c'4 c' c' c' |

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 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 table at Default values for outside-staff-priority or in the IR, 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
c''4\pp
% add dynamic line spanner
c''4\<
% add text script
c''4^Text |
c''4 c''
% add dynamic text
c''4\ff c'' \stopTextSpan |
% stop ottava bracket
\ottava 0
c'4 c' c' c' |

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 overridden.

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:

\relative c'' {
  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 |
}

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 section 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:

c''2^"Text1"
c''2^"Text2" |
\once \override TextScript.outside-staff-priority = 500
c''2^"Text3"
c''2^"Text4" |

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.

[ << Tweaking output ]	[Top][Contents][Index]	[ Templates >> ]
[ < Outside-staff objects ]	[ Up : Outside-staff objects ]	[ The `\textLengthOn` command > ]

The outside-staff-priority property

LilyPond Learning Manual v2.25.15 (development-branch).

The `outside-staff-priority` property