Documentation/fr/user/programming-interface.itely

   1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
   2 @c This file is part of lilypond.tely
   3 @ignore
   4     Translation of GIT committish: 76de7e168dbc9ffc7671d99663c5ce50dae42abb
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @c \version "2.11.65"
  11
  12 @c Translators: Valentin Villenave
  13 @c Translation checkers: Gilles Thibault
  14
  15
  16 @node Interfaces for programmers
  17 @chapter Interfaces for programmers
  18
  19 @untranslated
  20
  21
  22 @menu
  23 * Music functions::
  24 * Programmer interfaces::
  25 * Building complicated functions::
  26 * Markup programmer interface::
  27 * Contexts for programmers::
  28 * Scheme procedures as properties::
  29 @end menu
  30
  31 @node Music functions
  32 @section Music functions
  33
  34 @untranslated
  35
  36
  37 @menu
  38 * Overview of music functions::
  39 * Simple substitution functions::
  40 * Paired substitution functions::
  41 * Mathematics in functions::
  42 * Void functions::
  43 * Functions without arguments::
  44 * Overview of available music functions::
  45 @end menu
  46
  47 @node Overview of music functions
  48 @subsection Overview of music functions
  49
  50 @untranslated
  51
  52
  53 @node Simple substitution functions
  54 @subsection Simple substitution functions
  55
  56 @untranslated
  57
  58
  59 @node Paired substitution functions
  60 @subsection Paired substitution functions
  61
  62 @untranslated
  63
  64
  65 @node Mathematics in functions
  66 @subsection Mathematics in functions
  67
  68 @untranslated
  69
  70
  71 @node Void functions
  72 @subsection Void functions
  73
  74 @untranslated
  75
  76
  77 @node Functions without arguments
  78 @subsection Functions without arguments
  79
  80 @untranslated
  81
  82
  83 @node Overview of available music functions
  84 @subsection Overview of available music functions
  85
  86 @untranslated
  87
  88
  89 @include identifiers.tely
  90 @node Programmer interfaces
  91 @section Programmer interfaces
  92
  93 @untranslated
  94
  95
  96 @menu
  97 * Input variables and Scheme::
  98 * Internal music representation::
  99 @end menu
 100
 101 @node Input variables and Scheme
 102 @subsection Input variables and Scheme
 103
 104 @untranslated
 105
 106
 107 @node Internal music representation
 108 @subsection Internal music representation
 109
 110 @untranslated
 111
 112
 113 @node Building complicated functions
 114 @section Building complicated functions
 115
 116 @untranslated
 117
 118
 119 @menu
 120 * Displaying music expressions::
 121 * Music properties::
 122 * Doubling a note with slurs (example)::
 123 * Adding articulation to notes (example)::
 124 @end menu
 125
 126 @node Displaying music expressions
 127 @subsection Displaying music expressions
 128
 129 @untranslated
 130
 131
 132 @node Music properties
 133 @subsection Music properties
 134
 135 @untranslated
 136
 137
 138 @node Doubling a note with slurs (example)
 139 @subsection Doubling a note with slurs (example)
 140
 141 @untranslated
 142
 143
 144 @node Adding articulation to notes (example)
 145 @subsection Adding articulation to notes (example)
 146
 147 @untranslated
 148
 149
 150 @node Markup programmer interface
 151 @section Markup programmer interface
 152
 153 @untranslated
 154
 155
 156 @menu
 157 * Markup construction in Scheme::
 158 * How markups work internally::
 159 * New markup command definition::
 160 * New markup list command definition::
 161 @end menu
 162
 163 @node Markup construction in Scheme
 164 @subsection Markup construction in Scheme
 165
 166 @untranslated
 167
 168
 169 @node How markups work internally
 170 @subsection How markups work internally
 171
 172 @untranslated
 173
 174
 175 @node New markup command definition
 176 @subsection New markup command definition
 177
 178 @untranslated
 179
 180
 181 @node New markup list command definition
 182 @subsection New markup list command definition
 183
 184 @untranslated
 185
 186
 187 @node Contexts for programmers
 188 @section Contexts for programmers
 189
 190 @untranslated
 191
 192
 193 @menu
 194 * Context evaluation::
 195 * Running a function on all layout objects::
 196 @end menu
 197
 198 @node Context evaluation
 199 @subsection Context evaluation
 200
 201 @untranslated
 202
 203
 204 @node Running a function on all layout objects
 205 @subsection Running a function on all layout objects
 206
 207 @untranslated
 208
 209
 210 @node Scheme procedures as properties
 211 @section Scheme procedures as properties
 212
 213 @untranslated
 214
 215
 216 @menu
 217 * Using Scheme code instead of tweak::
 218 * Difficult tweaks::
 219 @end menu
 220
 221 @node Using Scheme code instead of tweak
 222 @section Using Scheme code instead of @code{\tweak}
 223
 224 L'inconvénient principal de la commande @code{\tweak} est la rigidité de sa
 225 syntaxe.  Par exemple, le code suivant produit une erreur.
 226
 227 @example
 228 F = \tweak #'font-size #-3 -\flageolet
 229
 230 \relative c'' @{
 231   c4^\F c4_\F
 232 @}
 233 @end example
 234
 235 @noindent
 236 En d'autres termes, @code{\tweak} ne se comporte pas comme une articulation :
 237 il ne peut notamment pas être accolé avec les symboles @samp{^} ou @samp{_}.
 238
 239 C'est en se servant du langage Scheme que l'on peut résoudre ce problème.
 240 Dans cet exemple, on a recours aux méthodes décrites dans @ref{Adding
 241 articulation to notes (example)}, en particulier quant à l'emploi de
 242 @code{\displayMusic}.
 243
 244 @example
 245 F = #(let ((m (make-music 'ArticulationEvent
 246                           'articulation-type "flageolet")))
 247        (set! (ly:music-property m 'tweaks)
 248              (acons 'font-size -3
 249                     (ly:music-property m 'tweaks)))
 250        m)
 251
 252 \relative c'' @{
 253   c4^\F c4_\F
 254 @}
 255 @end example
 256
 257 @noindent
 258 Ici les propriétés @code{tweak} de l'objet flageolet nommé
 259 @samp{m} (créé au moyen de @code{make-music}) sont extraites par
 260 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
 261 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
 262 @code{acons}), et le résultat de cette opération est renvoyé par @code{set!}.
 263 Le dernier élément, dans ce bloc @code{let}, est la valeur finale de
 264 @samp{m} lui-même.
 265
 266
 267 @node Difficult tweaks
 268 @section Difficult tweaks
 269
 270 Certains réglages sont plus délicats que d'autres.
 271
 272 @itemize @bullet
 273
 274
 275 @item
 276 L'un d'entre eux est l'apparence des objets dits @q{spanner}, qui s'étendent
 277 horizontalement, tels que les liaisons.  Si, en principe, un seul de ces objets
 278 est créé à la fois et peut donc être modifié de façon habituelle, lorsque ces
 279 objets doivent enjamber un changement de ligne, ils sont dupliqués au début
 280 du ou des systèmes suivants.  Comme ces objets sont des clones de l'objet d'origine,
 281 ils en héritent toutes les propriétés, y compris les éventuelles commandes @code{\override}.
 282
 283
 284 En d'autres termes, une commande @code{\override} affecte toujours les deux extrémités
 285 d'un objet @q{spanner}.  Pour ne modifier que la partie précédant ou suivant le changement
 286 de ligne, il faut intervenir directement dans le processus de mise en page.
 287 La fonction de rappel @code{after-line-breaking} contient toute l'opération Scheme
 288 effectuée lorsque les sauts de lignes ont été déterminés, et que des objets graphiques
 289 ont été divisés sur des systèmes différents.
 290
 291 Dans l'exemple suivant, on définit une nouvelle opération nommée
 292 @code{my-callback}.  Cette opération
 293
 294 @itemize @bullet
 295 @item
 296 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
 297 @item
 298 si oui, recherche les différents morceaux de l'objet
 299 @item
 300 vérifie si l'objet considéré est bien la deuxième moitié d'un objet divisé
 301 @item
 302 si oui, applique un espacement supplémentaire (@code{extra-offset}).
 303 @end itemize
 304
 305 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
 306 de façon à ce que le deuxième morceau d'une liaison divisée soit rehaussé.
 307
 308 @c KEEP LY
 309 @lilypond[quote,verbatim,ragged-right]
 310 #(define (my-callback grob)
 311   (let* (
 312          ; l'objet a-t-il été divisé ?
 313          (orig (ly:grob-original grob))
 314
 315          ; si oui, rechercher les morceaux frères (siblings)
 316          (siblings (if (ly:grob? orig)
 317                      (ly:spanner-broken-into orig) '() )))
 318
 319    (if (and (>= (length siblings) 2)
 320              (eq? (car (last-pair siblings)) grob))
 321      (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
 322
 323 \relative c'' {
 324   \override Tie #'after-line-breaking =
 325   #my-callback
 326   c1 ~ \break c2 ~ c
 327 }
 328 @end lilypond
 329
 330 @noindent
 331 Lorsque cette astuce va être appliquée, notre nouvelle fonction de rappel
 332 @code{after-line-breaking} devra également appeler celle d'origine
 333 (@code{after-line-breaking}), si elle existe.
 334 Ainsi, pour l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}),
 335 il faudra appeler également @code{ly:hairpin::after-line-breaking}.
 336
 337
 338 @item Pour des raisons d'ordre technique, certains objets ne peuvent être modifiés par
 339 @code{\override}.  Parmi ceux-là, les objets @code{NonMusicalPaperColumn}
 340 et @code{PaperColumn}.  La commande @code{\overrideProperty} sert à les modifier, de
 341 façon similaire à @code{\once \override}, mais avec une syntaxe différente :
 342
 343 @example
 344 \overrideProperty
 345 #"Score.NonMusicalPaperColumn"  % Nom de l'objet
 346 #'line-break-system-details     % Nom de la propriété
 347 #'((next-padding . 20))         % valeur
 348 @end example
 349
 350 Notez cependant que la commande @code{\override} peut tout de même être appliquée
 351 à @code{NoteMusicalPaperColumn} et @code{PaperColumn} dans un bloc @code{\context}.
 352
 353 @end itemize