5.3.7 The \offset command

While it is possible to set grob properties to new values with the \override, \tweak, and \overrideProperty commands, it is often more convenient to modify such properties relative to a default value. The \offset command is available for this purpose.

The syntax for \offset is

[-]\offset property offsets item

The command works by adding the contents of offsets to the default setting of the property property of the grob indicated by item.

Depending on the formulation of the command, \offset may act as either a \tweak or \override. The variations in usage are discussed after consideration is given to grob properties that may be used with \offset.

Properties which may be offset

Many, but not all, grob properties may be offset. If property cannot be offset, the object will remain unchanged and a warning will be issued. In such cases, \override or \tweak should be used to modify the object instead.

One can work by trial and error and let the warnings be the guide to what may or may not be offset. A more systematic approach is possible, however.

The following criteria determine whether a property can be modified with \offset:

• The property has a ‘default setting’ in the grob’s description. Such properties are listed for each grob in All layout objects. (They are also found in scm/define-grobs.scm.)
• The property takes a numerical value. Numerical values include number, list of numbers, number-pair, and number-pair-list. The pages at All layout objects list the type of data characteristic to each property. It is immaterial whether the default setting is a function.
• The property cannot be a ‘subproperty’ – a property residing within another property.
• Properties set to infinite values cannot be offset. There is no sensible way to offset positive and negative infinity.

The following examples consider several grob properties against the criteria outlined above.

• Properties that may be offset

  Hairpin.height

  This property is not a subproperty, and it is listed at Hairpin. For a value, it takes ‘dimension, in staff space’ set to 0.6666 – clearly a non-infinite number.

  Arpeggio.positions

  The page Arpeggio lists a positions property which accepts a ‘pair of numbers’. It defaults to ly:arpeggio::positions – a callback which will be evaluated during the typesetting phase to yield a pair of numbers for any given Arpeggio object.

• Properties that may not be offset

  Hairpin.color

  There is no listing for color at Hairpin.

  Hairpin.circled-tip

  The listing for Hairpin.circled-tip at Hairpin shows that it takes a boolean value. Booleans are non-numerical.

  Stem.details.lengths

  Though listed at Stem and defaulting to a list of numbers, this is a ‘subproperty’. There is currently no support for ‘nested properties’.

\offset as an override

If item is a grob name like Arpeggio or Staff.OttavaBracket, the result is an \override of the specified grob type.

\offset property offsets [context.]GrobName

Note that the leading hyphen is never used with the ‘override’ form, just as it is never used with the \override command itself.

The following example uses the ‘override’ form to lengthen the default arpeggios shown in the first measure to cover the extent of the chords more fully. The arpeggios are stretched by a half staff space to top and bottom. Also shown is the same operation done on the first chord with an ordinary override of the positions property. This method is not at all expressive of the task of ‘stretching by a half staff space’, as the endpoints must be specified with absolute rather than relative coordinates. Furthermore, individual overrides would be needed for the other chords, as they vary in size and position.

arpeggioMusic = {
  <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
  <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
}

{
  \arpeggioMusic
  \bar "||"
  \offset positions #'(-0.5 . 0.5) Arpeggio
  \arpeggioMusic
  \bar "||"
  \once \override Arpeggio.positions = #'(-3.5 . -0.5)
  <c' e' g'>1\arpeggio
  \bar "||"
}

In its ‘override’ usage, \offset may be prefaced with \once or \temporary and reverted using \revert with property (see Intermediate substitution functions). This follows from the fact that \offset actually creates an \override of property.

music = { c'8\< d' e' f'\! }

{
  \music
  \offset height 1 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
  \once \offset height 1 Hairpin
  \music \music
  \bar "||"
  \override Hairpin.height = 0.2
  \music
  \temporary \offset height 2 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
}

Also like \override, the ‘override’ form of \offset may be used with \undo and \single.

longStem = \offset length 6 Stem

{
 \longStem c'4 c''' c' c''
 \bar "||"
 \undo \longStem c'4 c''' c' c''
 \bar "||"
 \single \longStem c'4 c''' c' c''
 \bar "||"
}

\offset as a tweak

If item is a music expression such as ( or \arpeggio, the result is the same music expression with a tweak applied.

[-]\offset [GrobName.]property offsets music-expression

The syntax of \offset in its ‘tweak’ form is analogous to the \tweak command itself, both in ordering and in the presence or absence of the leading hyphen.

The following example uses the ‘tweak’ form to adjust the vertical position of the BreathingSign object. Compare this with the ordinary \tweak command also demonstrated. The syntax is equivalent; however, the output of \tweak is less intuitive, since BreathingSign.Y-offset is calculated from the middle staff line. It is not necessary to know how Y-offset is calculated when using \offset.

{
  c''4
  \breathe
  c''4
  \offset Y-offset 2 \breathe
  c''2
  \tweak Y-offset 3 \breathe
}

In the previous example, the tweaked objects were created directly from the user input: the \breathe command was an explicit instruction to return a BreathingSign object. Since the focus of the command was unambiguous, there was no need to specify the object’s name. When an object is indirectly created, however, it is necessary to include the grob’s name. This is the same as for the \tweak command.

In the following example, the Beam object is lowered two staff spaces by applying \offset to the positions property.

The first application of \offset requires that the grob’s name be included, because nothing in the input explicitly creates the beam. In the second application, the beam is created manually with the music expression [; therefore, the grob’s name is not needed. (Also illustrated is a shorthand: a single number will be applied to both members of a number-pair.)

{
  c''8 g'' e'' d''
  \offset Beam.positions #'(-2 . -2)
  c''8 g'' e'' d''
  c''8 g'' e'' d''
  c''8-\offset positions -2 [ g'' e'' d'']
}

\offset with broken spanners

Independently modifying segments of a spanner extending over a line break or breaks is also possible. In this case, offsets takes a list of values of the property’s required data type.

The \offset command used in this manner is similar to the \alterBroken command. (See Modifying broken spanners.) In contrast with \alterBroken, however, the values given to \offset are relative, not absolute.

The following example displaces the ‘broken’ OttavaBracket object through its staff-padding property. Since the property takes a number, offsets is provided with a list of numbers to account for the two segments created by the line break. The bracket piece on the first line is effectively untouched since 0 is added to its default value of staff-padding. The segment on the second line is raised three staff spaces from its default height. The default height happens to be 2, though it is not necessary to know this to achieve the desired positioning.

{
  \offset staff-padding #'(0 3) Staff.OttavaBracket
  \ottava 1
  c'''2 c'''
  \break
  c'''2 c'''
}

The following example mimics the effect of the \shape command by offsetting the control-points property of the Slur object. Here, offsets is a list of number-pair-lists, one for each slur segment. This example achieves a result identical to the corresponding illustration at Modifying shapes.

{
  c'4-\offset control-points #'(
               ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
               ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
              ) ( f'4 g' c''
  \break
  d'4 c'' f' c')
}