5.3.7 La commande \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 numbers, 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 numbers, 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 – see 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 numbers 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-lists, 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')
}