Referència de la notació del GNU LilyPond: 5.3.6 L'ordre \offset

### 5.3.6 L’ordre `\offset`

Tot i que és possible fixar propietats de grob a valors nous amb les ordres `\override`, `\tweak` i `\overrideProperty`, moltes vegades convé més modificar aquestes propietats en una quantitat relativa al valor predeterminat. L’ordre `\offset` es troba disponible per fer això.

La sintaxi de `\offset` és

>     [-]\offset propietat increments element

L’ordre funciona afegint el contingut de increments a l’ajustament predeterminat de la propietat del grob indicat per element.

Depenent de la formulació de l’ordre, `\offset` pot actuar com un `\tweak` (ajustament) o com un `\override` (sobreescriptura). Les variaciones en el seu ús s’explicaran després d’haver exaaminat les propietats de grob que es poden usar amb `\offset`.

#### Propietats que admeten el desplaçament

Moltes, però no totes, les propietats del grob admeten l’aplicació d’un desplaçament. Si propietat no es pot desplaçar, l’objecte romandrà sense canvis i s’omet l’advertiment. En aquests casos s’han d’usar en el seu lloc `\override` o `\tweak` per modificar l’objecte.

Es pot treballar per prova i error i deixar que els advertiments ens serveixen de guia per saber el que pot i no pot ser desplaçat. És possible, no obstant, un enfocament més sistemàtic.

Els criteris següents determinen si una propietat es pot modificar amb `\offset`:

- La propietat té un ‘ajustament predeterminat’ en la descripció del grob. Aquestes propietats apareixen llistades per a cada grob a All layout objects (i també estan a ‘`scm/define-grobs.scm`’).
- La propietat admet un valor numèric. Entre els valors numèrics es troben `number`, una llista de `number`s, `number-pair`, i `number-pair-list`. Les pàgines de All layout objects contenen una llista dels tipus de dades característiques de cada propietat. No importa si l’ajustament predeterminat és una funció.
- La propietat no pot ser una ‘subpropietat’ (una propietat que resideix dins duna altra propietat).
- Les propietats establertes a valors infinits no es poden desplaçar. No hi ha cap forma sensata d’incrementar els valors infinits positius o negatius.

Els exemples següents presenten diverses propietats de grob en front als criteris que s’han exposat.

- Propietats que es poden desplaçar
  `Hairpin.height`

    Aquesta propietat no és una subpropietat, i està a la llista que apareix a Hairpin. En quan al seu valor, admet ‘dimension, in staff space’ (dimensió, en espais de pentagrama) que està establert a `0.6666` (que clarament és un `nombre` no infinit).

  `Arpeggio.positions`

    A la llista de la pagina que descriu Arpeggio apareix una propietat `positions` que admet una ‘parella de nombres’. El seu valor predeterminat és `ly:arpeggio::positions`, que é un ‘callback’ que s’avalua durant la fase de gravat per donar com a resultat una parella de nombres per qualsevol objecte `Arpeggio` donat.

- Propietats que no admeten desplaçament
  `Hairpin.color`

    No hi ha un llistat per `color` a Hairpin.

  `Hairpin.circled-tip`

    La llista de `Hairpin.circled-tip` a la pàgina de Hairpin mostra que admet un valor `boolean`. Els valors booleans no són numèrics.

  `Stem.details.lengths`

    Tot i que està llistat a Stem i el seu valor predeterminat és una llista de `number`s, és una ‘subpropietat’. De moment les ‘propietats niuades’ no tenen suport.

#### \offset como sobreescriptura

Si element és un nom de grob com `Arpeggio` o `Staff.OttavaBracket`, el resultat es un `\override` o sobreescriptura del tipus de grob especificat.

>     \offset propietat increment [context.]NomDeGrob

Observeu que el guió precedent mai no s’utilitza amb la forma ‘override’, d’igual manera que mai no s’usa amb la pròpia ordre `\override`.

L’exemple següent usa la forma ‘override’, de sobreescriptura, per allargar els arpegis predeterminats que apareixen al primer compàs perquè cobreixin tota la mida dels acords. Els arpegis s’amplien en mig espai de pentagrama cap amunt i cap avall. També es mostra la mateixa operació efectuada sobre el primer acord amb una sobreescriptura normal de la propietat `positions`. Aquest mètode és en absolut expressiu de l’acció de ‘ampliar en mig espai de pentagrama’ perquè els extrems s’han d’especificar mitjançant coordenades absolutes, no relatives. A més, caldrien sobreescriptures individuals per als altres acords, atès que varien en mida i posició.

>     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 el seu ús com ‘override’, `\offset` es pot fer precedir per `\once` o per `\temporary` i revertir-se mitjançant `\revert` amb la propietat. Això és perquè `\offset` en realitat crea un `\override` per la propietat.

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

Així com `\override`, la forma ‘override’ de `\offset` es pot usar amb `\undo` i amb `\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 com ajustament

Si element és una expressió musical com `\arpeggio`, el resultat és la mateixa expressió musical amb l’ajustament aplicat.

>     [-]\offset [NomDeGrob.]propietat increments expressió-musical

La sintaxi de `\offset` en forma de ‘tweak’ és anàloga a la pròpia ordre `\tweak`, tant en ordre com en quant a la presència o absència del guió inicial.

L’exemple següent usa la forma ‘tweak’ per ajustar la posició vertical de l’objecte `BreathingSign`. Compareu-lo amb l’ordre `\tweak` normal que també apareix. La sintaxi és equivalent; malgrat això, la sortida de `\tweak` és menys intuïtiva, ja que `BreathingSign.Y-offset` es calcula a partir de la tercera línia del pentagrama. No cal saber com es calcula `Y-offset`, en usar `\offset`.

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

A l’exemple anterior, els objectes ajustats s’han creat directament a partir de l’entrada de l’usuari: l’ordre `\breathe` era una ordre explícita per retornar un objecte `BreathingSign`. Atès que l’objecte de l’ordre no és ambigu, no hi havia necessitat d’especificar el nom de l’objecte. Malgrat això, quan un objecte es crea indirectament, cal incloure el nom del grob. És el mateix que per a l’ordre `\tweak`.

A l’exemple següent, l’objecte `Beam` es baixa en dos espais de pentagrama aplicant `\offset` a la propietat `positions`.

La primera aplicació de `\offset` exigeix que s’inclogui el nom del grob, perquè no hi ha res al codi d’entrada que creï explícitament la barra. A la segona aplicació, la barra es crea manualment amb l’expressió musical `[`; per tant, el nom del grob no cal (també apareix a la il·lustració una abreviatura: un sol nombre s’aplica als dos membres d’una parella).

>     {
>       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 amb objectes extensos dividits

També es poden modificar segments d’un objecte que s’estén sobre un salt o salts de línia. En aquest cas, offsets admet una llista de valors del tipus de dades requerit per la propietat.

L’ordre `\offset` usada d’aquesta forma és semblant a l’ordre `\alterBroken` (vegeu Modificació d’objectes d’extensió dividits). No obstant això, a diferència de `\alterBroken`, els valors que se li donen a `\offset` són relatius, no absoluts.

A l’exemple següent desplaça l’objecte ‘dividit’ `OttavaBracket` a través de la seva propietat `staff-padding`. Atès que la propietat agafa un `number`, se li proporciona a increments una llista de nombres per aplicar-los als dos segments creats pel salt de línia. La part de clau de la primera línia queda, en realitat, inalterada, ja que s’afageix `0` al seu valor per defecte de `staff-padding`. El segment que està a la segona línia s’eleva tres espais de pentagrama a partir de la seva alçada per defecte. L’alçada predeterminada resulta ser `2`, tot i que no cal saber-lo per aconseguir la posició desitjada.

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

L’exemple següent copia l’efecte de l’ordre `\shape` mitjançant l’increment de la propietat `control-points` de l’objecte `Slur`. Aquí, increments és una llista de parelles de nombres, una per cada segment de la lligadura. Aquest exemple produeix un resultat idèntic a la il·lustració corresponent que apareix a Modificació de les formes.

>     {
>       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 — Referència de la notació v2.22.2 (branca estable).