GNU LilyPond – Manuel de notation: 5.3.6 La commande de décalage \offset

### 5.3.6 La commande de décalage `\offset`

Bien qu’il soit possible d’affecter de nouvelles valeurs aux propriétés d’un objet graphique à l’aide des commandes `\override`, `\tweak` ou `\overrideProperty`, il est souvent plus pratique de modifier de telles propriétés par rapport à une valeur par défaut. Ceci est la raison d’être de la commande `\offset`.

La commande `\offset` répond à la syntaxe suivante :

>     [-]\offset propriété décalages élément

La commande `\offset` agit par addition du contenu de décalages au réglage par défaut de la propriété propriété de l’objet graphique indiqué par élément.

Selon la manière dont la commande est formulée, `\offset` agira tantôt comme un `\tweak`, tantôt comme un `\override`. Les différences entre ces utilisations seront abordées après avoir recensé les propriétés qui peuvent être soumises à un `\offset`.

#### Propriétés acceptant des décalages

Bon nombre de propriétés d’objet graphique, mais pas toutes, peuvent faire l’objet d’un décalage. Si d’aventure propriété ne peut être affectée, l’objet restera inchangé et sera émis un message d’avertissement. En pareil cas, l’objet doit être modifié par un `\override` ou un `\tweak`.

Il est toujours possible de procéder à tâtons et laisser les avertissement indiquer si tel objet peut ou ne peut pas être soumis à `\offset`. Néanmoins, une approche plus systématique est possible.

Les critères énoncés ci-après déterminent l’égibilité d’une propriété à être modifiée par la commande `\offset`.

- La propriété possède un « réglage par défaut » au niveau de la définition de l’objet graphique. Les propriétés en question sont listées, pour chacun des grobs, dans Tous les objets de rendu – on les trouvera aussi dans le fichier ‘`scm/define-grobs.scm`’.
- La propriété prend une valeur numérique. Les valeurs numériques comprennent `number`, liste de `number`s, `number-pair` et `number-pair-list`. Les pages de Tous les objets de rendu répertorient le type de donnée propre à chaque propriété. Peu importe que le réglage par défaut soit une fonction.
- La propriété ne saurait constituer une « sous-propriété » – une propriété résidant au sein d’une autre propriété.
- Les propriétés réglées sur des valeurs infinies ne peuvent faire l’objet d’un décalage. Il n’y a aucun moyen d’influencer l’infini, qu’il soit positif ou négatif.

Les exemples qui suivent s’arrêtent sur plusieurs propriétés d’objet graphique au regard des critères énoncés ci-dessus.

- Propriétés qui peuvent être décalées
  `Hairpin.height`

    Cette propriété n’est pas une sous-propriété, et est référencée à Soufflet. En tant que valeur, elle prend une « dimension, exprimée en espace de portée » réglée à `0.6666` – clairement une valeur `number` non infini.

  `Arpeggio.positions`

    La page Arpeggio référence une propriété `positions` qui accepte une « paire de nombres ». Sa valeur par défaut est `ly:arpeggio::positions` – une fonction de rappel qui sera évaluée au cours de la phase de typographie pour donner une paire de nombres pour tout objet `Arpeggio`.

- Propriétés qui ne peuvent être décalées
  `Hairpin.color`

    Aucune référence à `color` n’est mentionnée dans Soufflet.

  `Hairpin.circled-tip`

    La référence à `Hairpin.circled-tip` dans Soufflet indique que cette propriété prend une valeur `boolean`. Les boléens ne sont pas des nombres.

  `Stem.details.lengths`

    Bien que mentionnée dans Hampe et ayant par défaut une liste de `number`s, il s’agit d’une « sous-propriété ». Il n’existe à ce jour aucune prise en charge des « propriétés imbriquées ».

#### `\offset` en tant que dérogation

Lorsque élément est un nom d’objet graphique comme `Arpeggio` ou `Staff.OttavaBracket`, le comportement de la commande `\offset` est assimilable à un `\override` sur le type d’objet spécifié.

>     \offset propriété décalages [contexte.]NomGrob

Notez bien qu’il n’y a jamais de tiret avant un comportement « dérogatoire », tout comme il n’y en a jamais avec la commande `\override` elle-même.

L’exemple suivant utilise la forme « dérogation » pour allonger les arpeggios affichés dans la première mesure, jusqu’à couvrir l’accord dans son intégralité. Les arpeggios sont étirés d’un demi espace de portée à leur sommet ainsi qu’à leur base. Est aussi indiquée la même opération sur le premier accord à l’aide d’une simple dérogation appliquée à la propriété `positions`. Cette méthode n’est pas la plus illustrative pour « étirer d’un demi espace de portée » dans la mesure où les extrémités doivent être spécifiées en coordonnées absolues plutôt que relatives. De plus, des dérogations individuelles seraient nécessaires pour les autres accords en raison de leurs différentes amplitude et 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 "||"
>     }

Dans cette utilisation d’override, `\offset` peut se préfixer de `\once` ou `\temporary` et être annulé à l’aide d’un `\revert` suivi de propriété – voir Fonctions de substitution intermédiaires. Ceci tient au fait que `\offset` crée effectivement un `\override` de propriété.

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

Tout comme `\override`, la forme « dérogation » de `\offset` peut s’utiliser avec `\undo` et `\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` en tant qu’affinage

Lorsque élément est une expression musicale, comme `(` ou `\arpeggio`, le résultat sera la même expression musicale à laquelle aura été appliqué un affinage.

>     [-]\offset [NomGrob.]propriété décalages expression-musicale

La syntaxe de `\offset` dans sa forme « affinage » est en tout point analogue à la commande `\tweak`, autant dans l’ordre des arguments que dans la présence ou non du tiret l’introduisant.

L’exemple suivant utilise la forme « affinage » pour ajuster le positionnement vertical de l’objet `BreathingSign`. Les effets de la simple commande `\tweak` sont présent à titre de comparaison. Leur syntaxe est équivalente. Néanmoins, le résultat de `\tweak` est moins intuitif dans la mesure où `BreathingSign.Y-offset` est calculé en référence à la ligne médiane. Il n’est pas nécessaire de savoir comment se calcule `Y-offset` dans le cas d’un `\offset`.

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

Dans cet exemple, les objets affinés étaient créés directement à partir du code saisi : la commande `\breathe` était une instruction explicite pour renvoyer un objet `BreathingSign`. Puisque la cible de la commande était sans ambiguïté, point n’était besoin de spécifier le nom de l’objet. Cependant, lorsqu’un objet est créé indirectement, mention du nom de l’objet devient requise. Il en va de même pour la commende `\tweak`.

Dans l’exemple qui suit, l’objet `Beam` est abaissé de deux espaces de portée par application de `\offset` à la propriété `positions`.

La première application de `\offset` requiert mention du nom de l’objet puisque rien dans le code ne crée explicitement de ligature. Dans la seconde application, la ligature est explicitement créée par l’expression musicale `[`, ce qui dispense de mentionner le nom de l’objet. Cette deuxième application comporte par ailleurs un raccourci : un unique `number` s’appliquera aux deux membres d’un `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` et les bandeaux avec rupture

Il est aussi possible de modifier indépendamment les segments d’un objet étendu rencontrant des sauts de ligne. Dans ce cas, décalages est consitué d’une liste de valeurs pour le type de donnée requis par la propriété.

Utilisée de telle manière, la commande `\offset` est similaire à la commande `\alterBroken` – voir Modification de bandeaux avec rupture. Cependant, et contrairement à la commande `\alterBroken`, les valeurs fournies à `\offset` sont relatives.

Dans l’exemple suivant est déplacé l’objet « segmenté » `OttavaBracket` au travers de sa propriété `staff-padding`. Puisque cette propriété est affectée d’un `number`, décalages est alimenté d’une liste de `number`s afin de prendre en compte les deux segments créés par le saut de ligne. La portion de crochet de la première ligne n’est en fait pas touchée puisque `0` est ajouté à la valeur par défaut de `staff-padding`. Le segment de la deuxième ligne est haussé de trois espaces de portée par rapport à sa hauteur par défaut. La hauteur par défaut est de `2`, bien qu’il ne soit pas nécessaire de le savoir.

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

L’exemple ci-dessous reproduit les effets de la commande `\shape` en décalant la propriété `control-points` de l’objet `Slur`. Ici, décalages est constitué d’une liste de `number-pair-list`s, une pour chaque segment de la liaison. Cet exemple produit un résultat identique à ce qui est illustré dans Modification de l’allure des éléments.

>     {
>       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 — Manuel de notation v2.24.4 (branche stable).