| [ << Changing defaults ] | [Top][Contents][Index] | [ Notation manual tables >> ] |
| [ < set versus override ] | [ Up : Modifying properties ] | [ Modifying alists > ] |
5.3.6 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 ofnumbers,number-pair, andnumber-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-infinitenumber. -
Arpeggio.positions -
The page Arpeggio lists a
positionsproperty which accepts a ‘pair of numbers’. It defaults toly:arpeggio::positions—a callback which will be evaluated during the typesetting phase to yield a pair of numbers for any givenArpeggioobject.
-
- Properties that may not be offset
-
Hairpin.color -
There is no listing for
colorat Hairpin. -
Hairpin.circled-tip -
The listing for
Hairpin.circled-tipat Hairpin shows that it takes abooleanvalue. 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
functions
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')
}
| [ << Changing defaults ] | [Top][Contents][Index] | [ Notation manual tables >> ] |
| [ < set versus override ] | [ Up : Modifying properties ] | [ Modifying alists > ] |