Referencia de la notación de GNU LilyPond: 5.3.6 La instrucción \offset

### 5.3.6 La instrucción `\offset`

Aunque es posible fijar propiedades de grob a valores nuevos con las instrucciones `\override`, `\tweak` y `\overrideProperty`, muchas veces conviene más modificar dichas propiedades en una cantidad relativa al valor predeterminado. La instrucción `\offset` se encuentra disponible para este fin.

La sintaxis de `\offset` es

>     [-]\offset propiedad incrementos elemento

La instrucción funciona añadiendo el contenido de incrementos al ajuste predeterminado de la propiedad del grob indicado por elemento.

Dependiendo de la formulación de la instrucción, `\offset` puede actuar como un `\tweak` (trucaje) o como un `\override` (sobreescritura). Las variaciones en su uso se explicarán después de haber examinado las propiedades de grob que se pueden usar con `\offset`.

#### Propiedades que admiten el desplazamiento

Muchas, pero no todas, las propiedades de grob admiten la aplicación de un desplazamiento. Si propiedad no se puede desplazar, el objeto permanece sin cambios y se emite una advertencia. En estos casos se deben usar en su lugar `\override` o `\tweak` para modificar el objeto.

Se puede trabajar por ensayo y error y dejar que las advertencias nos sirvan de guía para saber lo que puede o no puede ser desplazado. Sin embargo, es posible un enfoque más sistemático.

Los criterios siguientes determinan si una propiedad se puede modificar con `\offset`:

- La propiedad tiene un ‘ajuste predeterminado’ en la descripción del grob. Tales propiedades aparecen listadas para cada grob en All layout objects (y también están en ‘`scm/define-grobs.scm`’).
- La propiedad admite un valor numérico. Entre los valores numéricos se encuentran `number`, una lista de `number`s, `number-pair`, y `number-pair-list`. Las páginas de All layout objects contienen una lista de los tipos de datos característicos de cada propiedad. No importa si el ajuste predeterminado es una función.
- La propiedad no puede ser una ‘subpropiedad’ (una propiedad que reside dentro de otra propiedad).
- Las propiedades establecidas a valores infinitos no se pueden desplazar. No hay ninguna forma sensata de incrementar los valores infinitos positivos o negativos.

Los ejemplos siguientes tratan diversas propiedades de grob frente a los criterios que se han expuesto.

- Propiedades que se pueden desplazar
  `Hairpin.height`

    Esta propiedad no es una subpropiedad, y está en la lista que aparece en Hairpin. En cuanto a su valor, admite ‘dimension, in staff space’ (dimensión, en espacios de pentagrama) fijado a `0.6666` (que claramente es un `number` no infinito).

  `Arpeggio.positions`

    En la lista de la página que describe Arpeggio aparece una propiedad `positions` que admite una ‘pareja de números’. Su valor predeterminado es `ly:arpeggio::positions`, que es un ‘callback’ que se evalúa durante la fase de tipografiado para dar como resultado una pareja de números para cualguier objeto `Arpeggio` dado.

- Propiedades que no admiten el desplazamiento
  `Hairpin.color`

    No hay un listado para `color` en Hairpin.

  `Hairpin.circled-tip`

    La lista de `Hairpin.circled-tip` en la página de Hairpin muestra que admite un valor `boolean`. Los valores booleanos so no numéricos.

  `Stem.details.lengths`

    Aunque está listado en Stem y su valor por omisión es una lista de `number`s, es una ‘subpropiedad’. Por el momento no se contemplan las ‘propiedades anidadas’.

#### offset como sobreescritura

Si elemento es un nombre de grob como `Arpeggio` o `Staff.OttavaBracket`, el resultado es un `\override` o sobreescritura de el tipo de grob especificado.

>     \offset propiedad incremento [contexto.]NombreDeGrob

Observe que el guión precedente nunca se utiliza con la forma ‘override’, de igual manera que nunca se usa con la propia instrucción `\override`.

El ejemplo siguiente usa la forma ‘override’, de sobreescritura, para alargar los arpegios predeterminados que aparecen en el primer compás para que cubran todo el tamaño de los acordes. Los arpegios se amplían en medio espacio de pentagrama hacia arriba y hacia abajo. También se muestra la misma operación efectuada sobre el primer acorde con una sobreescritura normal de la propiedad the `positions`. Este método no es en absoluto expresivo de la acción de ‘ampliar en medio espacio de pentagrama’, porque los extremos se tienen que especificar mediante coordenadas absolutas, no relativas. Además, se necesitarían sobreescrituras individuales para los otros acordes, ya que varían en tamaño y posición.

>     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 "||"
>     }

En su uso como ‘override’, `\offset` se puede hacer preceder por `\once` o por `\temporary` y revertirse mediante `\revert` con la propiedad. (véase Funciones de sustitución intermedias). Esto se sigue a partir del hecho de que `\offset` en realidad crea un `\override` para la propiedad.

>     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 "||"
>     }

Así como `\override`, la forma ‘override’ de `\offset` se puede usar con `\undo` y con `\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 como trucaje

Si elemento es una expresión musical como `(` o `\arpeggio`, el resultado es la misma expresión musical con un trucaje aplicado.

>     [-]\offset [NombreDeGrob.]propiedad incrementos expresión-musical

La sintaxis de `\offset` en forma de ‘tweak’ es análoga a la propia instrucción `\tweak`, tanto en orden como en cuanto a la presencia o ausencia del guión inicial.

El ejemplo siguiente usa la forma ‘tweak’ para ajustar la posición vertical del objeto `BreathingSign`. Compárelo con la instrucción `\tweak` normal que también aparece. La sintaxis es equivalente; sin embargo, la salida de `\tweak` es menos intuitiva, ya que `BreathingSign.Y-offset` se calcula a partir de la tercera línea del pentagrama. No es necesario saber cómo se calcula `Y-offset`, al usar `\offset`.

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

En el ejemplo anterior, los objetos trucados se crearon directamente a partir de la entrada del usuario: la instrucción `\breathe` era una instrucción explícita para devolver un objeto `BreathingSign`. Dado que el objeto de la instrucción no es ambiguo, no había necesidad de especificar el nombre del objeto. Sin embargo, cuando un objeto se crea indirectamente, es necesario incluir el nombre del grob. Es lo mismo que para la instrucción `\tweak`.

En el ejemplo siguiente, el objeto `Beam` se baja en dos espacios de pentagrama aplicando `\offset` a la propiedad `positions`.

La primera aplicación de `\offset` exige que se incluya el nombre del grob, porque nada en el código de entrada crea explícitamente la barra. En la segunda aplicación, la barra se crea manualmente con la expresión musical `[`; por tanto, el nombre del grob no es necesario (también aparece en la ilustración una abreviatura: un solo número se aplica a los dos miembros de una pareja).

>     {
>       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 con objetos extensos divididos

También es posible modificar segmentos de un objeto que se extiende sobre un salto o saltos de línea. En este caso, offsets admite una lista de valores del tipo de datos requerido por la propiedad.

La instrucción `\offset` usada de esta forma es similar a la instrucción `\alterBroken` (véase Modificación de objetos de extensión divididos). Sin embargo, a diferencia de `\alterBroken`, los valores que se le dan a `\offset` son relativos, no absolutos.

El ejemplo siguiente desplaza el objeto ‘dividido’ `OttavaBracket` a través de su propiedad `staff-padding`. Dado que la propiedad toma un `number`, se le proporciona a incrementos una lista de números para aplicarlos a los dos segmentos creados por el salto de línea. La parte de corchete de la primera línea queda, en realidad, inalterada, ya que se añade `0` a su valor por omisión de `staff-padding`. El segmento que está en la segunda línea se eleva tres espacios de pentagrama a partir de su altura por omisión. La altura predeterminada resulta ser `2`, aunque no es necesario saberlo para conseguir la posición deseada.

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

El ejemplo siguiente copia el efecto de la instrucción `\shape` mediante el incremento de la propiedad `control-points` del objeto `Slur`. Aquí, incrementos es una lista de parejas de números, una por cada segmento de la ligadura. Este ejemplo produce un resultado idéntico a la ilustración correspondiente que aparece en Modificación de las formas.

>     {
>       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')
>     }

#### LilyPond — Referencia de la notación v2.24.4 (rama estable).