LilyPond Notation Reference: 4.2.1 The \layout block

[ << Spacing issues ]	[Top][Contents][Index]	[ Changing defaults >> ]
[ < Score layout ]	[ Up : Score layout ]	[ Setting the staff size > ]

4.2.1 The `\layout` block

While the \paper block contains settings that relate to the page formatting of the whole document, the \layout block contains settings for score-specific layout. To set score layout options globally, enter them in a toplevel \layout block. To set layout options for an individual score, enter them in a \layout block inside the \score block, after the music. Settings that can appear in a \layout block include:

the layout-set-staff-size scheme function,
context modifications in \context blocks, and
\paper variables that affect score layout.

The layout-set-staff-size function is discussed in the next section, Setting the staff size. Context modifications are discussed in a separate chapter; see Modifying context plug-ins and Changing context default settings.

The \paper variables that can appear in a \layout block, with default values taken from the \paper block are:

line-width, ragged-right and ragged-last (see \paper variables for widths and margins)
indent and short-indent (see \paper variables for shifts and indents)
system-count (see \paper variables for line breaking)

Here is an example \layout block:

\layout {
  indent = 2\cm
  \context {
    \StaffGroup
    \override StaffGrouper.staff-staff-spacing.basic-distance = #8
  }
  \context {
    \Voice
    \override TextScript.padding = #1
    \override Glissando.thickness = #3
  }
}

Multiple \layout blocks can be entered as toplevel expressions. This can, for example, be useful if different settings are stored in separate files and included optionally. Internally, when a \layout block is evaluated, a copy of the current \layout configuration is made, then any changes defined within the block are applied and the result is saved as the new current configuration. From the user’s perspective the \layout blocks are combined, but in conflicting situations (when the same property is changed in different blocks) the later definitions take precedence.

For example, if this block:

\layout {
  \context {
    \Voice
    \override TextScript.color = #magenta
    \override Glissando.thickness = #1.5
  }
}

is placed after the one from the preceding example the padding and color overrides for TextScript are combined, but the later thickness override for Glissando replaces (or hides) the earlier one.

\layout blocks may be assigned to variables for reuse later, but the way this works is slightly but significantly different from writing them literally.

If a variable is defined like this:

layoutVariable = \layout {
  \context {
    \Voice
    \override NoteHead.font-size = #4
  }
}

it will hold the current \layout configuration with the NoteHead.font-size override added, but this combination is not saved as the new current configuration. Be aware that the ‘current configuration’ is read when the variable is defined and not when it is used, so the content of the variable is dependent on its position in the source.

The variable can then be used inside another \layout block, for example:

\layout {
  \layoutVariable
  \context {
    \Voice
    \override NoteHead.color = #red
  }
}

A \layout block containing a variable, as in the example above, does not copy the current configuration but instead uses the content of \layoutVariable as the base configuration for the further additions. This means that any changes defined between the definition and the use of the variable are lost.

If layoutVariable is defined (or \included) immediately before being used, its content is just the current configuration plus the overrides defined within it. So in the example above showing the use of \layoutVariable the final \layout block would consist of:

  TextScript.padding = #1
  TextScript.color = #magenta
  Glissando.thickness = #1.5
  NoteHead.font-size = #4
  NoteHead.color = #red

plus the indent and the StaffGrouper overrides.

But if the variable had already been defined before the first \layout block the current configuration would now contain only

  NoteHead.font-size = #4 % (written in the variable definition)
  NoteHead.color = #red % (added after the use of the variable)

If carefully planned, \layout variables can be a valuable tool to structure the layout design of sources, and also to reset the \layout configuration to a known state.

4.2.1 The `\layout` block

See also

LilyPond — Notation Reference v2.23.82 (development-branch).