4.3.4 Modifying context properties (LilyPond Learning Manual)

#### 4.3.4 Modifying context properties

Contexts are responsible for holding the values of a number of context properties. Many of them can be changed to influence the interpretation of the input and so change the appearance of the output. They are changed by the `\set` command. This takes the form

    \set ContextName.propertyName = value

where ContextName is usually `Score`, `Staff`, or `Voice`. It may be omitted, in which case `Voice` is assumed.

The names of context properties consist of words joined together with no hyphens or underscores, all except the first having a capital letter. Here are a few examples of some commonly used ones. There are many more.

> Property Name | Type | Function | Example Value
> --- | --- | --- | ---
> `extraNatural` | Boolean | If true, set extra natural signs before accidentals | `##t`, `##f`
> `currentBarNumber` | integer | Set the current bar number | `50`
> `doubleSlurs` | Boolean | If true, print slurs both above and below notes | `##t`, `##f`
> `instrumentName` | text | Set the name to be placed at the start of the staff | `\markup { ... }`
> `fontSize` | real | Increase or decrease the font size | `2.4`
> `stanza` | text | Set the text to print before the start of a verse | `"2"`

In the above table, a Boolean is either `#t` (true) or `#f` (false), an integer is a whole number (usually positive), a real is a positive or negative decimal number, and text is string enclosed in doublequote characters. Note the use of an additional hash sign (‘`#`’), which must always be used if a Scheme expression follows.

Before we can set any of these properties we need to know in which context they operate. Sometimes this is obvious, but occasionally it can be tricky. If the wrong context is specified, no error message is produced, but the expected action will not take place. For example, the `clefGlyph` clearly lives in the `Staff` context, since it is the staff’s clef glyph that is to be changed. In this example the first staff’s clef is printed correctly, but not the second – which prints the default treble clef instead of the expected bass (or F) clef – because we omitted the context name.

>     <<
>       \new Staff \relative {
>         \set Staff.clefGlyph = "clefs.C"
>         c''2 c
>       }
>       \new Staff \relative {
>         \set clefGlyph = "clefs.F"  % Wrong!
>         d'2 d
>       }
>     >>

The second `\set` command effectively sets `Voice.clefGlyph` to `clefs.F`, but as LilyPond does not rely on `clefGlyph` in the `Voice` context, setting it there has no impact. This is not an error, and no error message is emitted.

The `clefGlyph` property will take effect only if it is set in the `Staff` context, but some properties can be set in more than one context. For example, the property `extraNatural` is by default set to `#t` (true) for all staves. If it is set to `#f` (false) in one particular `Staff` context, it applies just to the accidentals on that staff. If it is set to false in the `Score` context, it applies to all `Staff` contexts where it is not otherwise set.

So this turns off extra naturals in one staff:

>     <<
>       \new Staff \relative {
>         aeses'2 aes
>       }
>       \new Staff \relative {
>         \set Staff.extraNatural = ##f
>         aeses'2 aes
>       }
>     >>

and this turns them off in all staves:

>     <<
>       \new Staff \relative {
>         aeses'2 aes
>       }
>       \new Staff \relative {
>         \set Score.extraNatural = ##f
>         aeses'2 aes
>       }
>     >>

As another example, if `clefTransposition` is set in the `Score` context, it changes the transposition for current and future `Staff` contexts where it is not otherwise set.

The opposite command, `\unset`, removes the property from the context. Often, another `\set` command can achieve the same observable result as an `\unset`. The main consideration is whether the value from the enclosing context should show through. `\set` masks it and `\unset` makes it visible.

The `\set` and `\unset` commands can appear anywhere in the input file and will take effect from the time they are encountered until the end of the score or until the property is `\set` or `\unset` again. Let’s try changing the font size, which affects the size of the note heads (among other things) several times. The value is set relative to the default font size, not to the most recently set value.

>     \relative {
>       c'4 d
>       % make note heads smaller
>       \set fontSize = -4
>       e4 f |
>       % make note heads larger
>       \set fontSize = 2.5
>       g4 a
>       % return to default size
>       \unset fontSize
>       b4 c |
>     }

We have now seen how to set the values of several different types of properties. Note that Scheme expressions are introduced with a hash sign, ‘`#`’, so the ‘true’ and ‘false’ values are specified by `##t` and `##f`, respectively, with two hash signs. A text property should be enclosed in double quotation signs, as above, although we shall see later that text can actually be specified in a much more general way by using the very powerful `\markup` command.

#### Setting context properties with `\with`

The value of context properties may be set at the time a context is created. When a context is created with a `\new` command, it may be followed immediately by a `\with { … }` block in which the initial property values are set. For example, if we wished to suppress the printing of extra naturals, we would write

    \new Staff \with { extraNatural = ##f }

like this:

>     <<
>       \new Staff {
>         \relative {
>           gisis'4 gis aeses aes
>         }
>       }
>       \new Staff \with { extraNatural = ##f } {
>         \relative {
>           gisis'4 gis aeses aes
>         }
>       }
>     >>

`\with` can be a clear way to set values that are intended to remain fixed for the duration of the context; however, it does nothing to enforce this. Properties initialized this way can still be changed dynamically using `\set` and `\unset`.

#### Setting context properties with `\context`

The values of context properties may be set in all contexts of a particular type, such as all `Staff` contexts, with a single command. The context type is identified by using its type name, like `Staff`, prefixed by a back-slash: `\Staff`. The statement which sets the property value is the same as that in a `\with` block, introduced above. It is placed in a `\context` block within a `\layout` block. Each `\context` block will affect all contexts of the type specified throughout the `\score` or `\book` block in which the `\layout` block appears. Here is an example to show the format:

>     \score {
>       \new Staff {
>         \relative {
>           cisis''4 e d cis
>         }
>       }
>       \layout {
>         \context {
>           \Staff
>           extraNatural = ##t
>         }
>       }
>     }

If the property override is to be applied to all staves within the score:

>     \score {
>       <<
>         \new Staff {
>           \relative {
>             gisis'4 gis aeses aes
>           }
>         }
>         \new Staff {
>           \relative {
>             gisis'4 gis aeses aes
>           }
>         }
>       >>
>       \layout {
>         \context {
>           \Score
>           extraNatural = ##f
>         }
>       }
>     }

Context properties set in this way may be overridden for particular instances of contexts by statements in a `\with` block, and by `\set` commands embedded in music statements.

#### See also

Notation Reference: Changing context default settings, Set and unset.

Internals Reference: Contexts, Tunable context properties.

#### LilyPond Learning Manual v2.26.0 (stable-branch).

- 1 Installing
  - 1.1 Graphical setup
  - 1.2 Command line setup
- 2 Tutorial
  - 2.1 Compiling a file
  - 2.2 How to write input files
    - 2.2.1 Input characters
    - 2.2.2 Simple notation
      - Pitches
      - Durations (rhythms)
      - Rests
      - Time signature
      - Tempo marks
      - Clef
      - All together
    - 2.2.3 Working on input files
  - 2.3 Dealing with errors
  - 2.4 How to read the manuals
    - 2.4.1 Omitted material
    - 2.4.2 Clickable examples
    - 2.4.3 Overview of manuals
- 3 Common notation
  - 3.1 Single-staff notation
    - 3.1.1 Bar lines and bar checks
      - Bar lines
      - Bar checks
    - 3.1.2 Pitches and key signatures
      - Pitch alterations
      - Key signatures
      - Warning: key signatures and pitches
    - 3.1.3 Ties and slurs
      - Ties
      - Slurs
      - Phrasing slurs
      - Warnings: slurs vs. ties
    - 3.1.4 Articulations and dynamics
      - Articulations
      - Fingerings
      - Dynamics
    - 3.1.5 Adding text
    - 3.1.6 Automatic and manual beams
    - 3.1.7 Advanced rhythmic commands
      - Partial measure
      - Tuplets
      - Grace notes
  - 3.2 Multiple notes at once
    - 3.2.1 Music expressions explained
      - Analogy: mathematical expressions
      - Simultaneous music expressions: multiple staves
      - Simultaneous music expressions: single-staff
    - 3.2.2 Multiple staves
    - 3.2.3 Staff groups
    - 3.2.4 Combining notes into chords
    - 3.2.5 Single-staff polyphony
  - 3.3 Songs
    - 3.3.1 Setting simple songs
    - 3.3.2 Aligning lyrics to a melody
    - 3.3.3 Lyrics to multiple staves
  - 3.4 Final touches
    - 3.4.1 Organizing pieces with variables
    - 3.4.2 Adding titles
    - 3.4.3 Absolute note names
    - 3.4.4 After the tutorial
- 4 Fundamental concepts
  - 4.1 How LilyPond input files work
    - 4.1.1 Introduction to the LilyPond file structure
    - 4.1.2 A score is a (single) compound musical expression
    - 4.1.3 Nesting music expressions
    - 4.1.4 Structure of a note entry
    - 4.1.5 On the un-nestedness of brackets and ties
  - 4.2 Voices contain music
    - 4.2.1 I’m hearing voices
    - 4.2.2 Explicitly instantiating voices
    - 4.2.3 Voices and vocals
  - 4.3 Contexts and engravers
    - 4.3.1 Contexts explained
    - 4.3.2 Creating contexts
    - 4.3.3 Engravers explained
    - 4.3.4 Modifying context properties
    - 4.3.5 Adding and removing engravers
  - 4.4 Extending the templates
    - 4.4.1 Soprano and cello
    - 4.4.2 Four-part SATB vocal score
    - 4.4.3 Building a score from scratch
    - 4.4.4 Saving typing with variables and functions
    - 4.4.5 Scores and parts
- 5 Tweaking output
  - 5.1 Tweaking basics
    - 5.1.1 Objects and interfaces
    - 5.1.2 Naming conventions of objects and properties
    - 5.1.3 Tweaking methods
      - The `\override` command
      - The `\revert` command
      - The `\once` prefix
      - The `\tweak` and `\offset` commands
      - The `\single` prefix
  - 5.2 The Internals Reference manual
    - 5.2.1 Properties of layout objects
    - 5.2.2 Properties found in interfaces
    - 5.2.3 Types of properties
  - 5.3 Appearance of objects
    - 5.3.1 Visibility and color of objects
      - The `stencil` property
      - The `break-visibility` property
      - The `transparent` property
      - The `color` property
    - 5.3.2 Size of objects
    - 5.3.3 Length and thickness of objects
  - 5.4 Offsets and alignments
  - 5.5 Placement of objects
    - 5.5.1 Automatic behavior
    - 5.5.2 Within-staff objects
      - The `direction` property
      - Fingering
    - 5.5.3 Outside-staff objects
      - The `outside-staff-priority` property
      - The `\textLengthOn` command
      - Dynamics placement
      - Grob sizing
  - 5.6 Vertical spacing
  - 5.7 Collisions of objects
    - 5.7.1 Moving objects
    - 5.7.2 Fixing overlapping notation
      - The `padding` property
      - The `right-padding` property
      - The `staff-padding` property
      - The `self-alignment-X` property
      - The `staff-position` property
      - The `extra-offset` property
      - The `positions` property
      - The `force-hshift` property
    - 5.7.3 Real music example
  - 5.8 Further tweaking
    - 5.8.1 Other uses for tweaks
      - Tying notes across voices
      - Simulating a fermata in MIDI
    - 5.8.2 Using variables for layout adjustments
    - 5.8.3 Style sheets
    - 5.8.4 Other sources of information
    - 5.8.5 Advanced tweaks with Scheme
- Appendix A Templates
  - A.1 Built-in templates
    - A.1.1 SATB template
    - A.1.2 SSAATTBB template
  - A.2 Single staff templates
    - A.2.1 Notes only
    - A.2.2 Notes and lyrics
    - A.2.3 Notes and chords
    - A.2.4 Notes, lyrics, and chords
  - A.3 Piano templates
    - A.3.1 Solo piano
    - A.3.2 Piano and melody with lyrics
    - A.3.3 Piano-centered lyrics
  - A.4 String quartet templates
    - A.4.1 String quartet
    - A.4.2 String quartet parts
  - A.5 Vocal ensembles templates
    - A.5.1 SATB vocal score
    - A.5.2 SATB vocal score and automatic piano reduction
    - A.5.3 SATB with aligned contexts
    - A.5.4 SATB on four staves
    - A.5.5 Solo verse and two-part refrain
    - A.5.6 Hymn tunes
    - A.5.7 Psalms
  - A.6 Orchestral templates
    - A.6.1 Orchestra, choir and piano
  - A.7 Ancient notation templates
    - A.7.1 Transcription of mensural music
    - A.7.2 Gregorian transcription template
  - A.8 Other templates
    - A.8.1 Jazz combo
- Appendix B GNU Free Documentation License
- Appendix C Index