1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 3c62ac104645533873bba800f7b0f371089f535a
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @c Translators: Valentin Villenave, Jean-Charles Malahieude
14 @c Translation checkers: Gilles Thibault
16 @node Interfaces pour programmeurs
17 @chapter Interfaces pour programmeurs
18 @translationof Interfaces for programmers
20 Advanced tweaks may be performed by using Scheme. If you are
21 not familiar with Scheme, you may wish to read our
22 @ref{Tutoriel Scheme}.
25 * Blocs de code Lilypond::
27 * Fonctions musicales::
28 * Fonctions événementielles::
29 * Fonctions pour markups::
30 * Contextes pour programmeurs::
31 * Fonctions de rappel::
32 * Code Scheme intégré::
33 * Retouches complexes::
36 @node Blocs de code Lilypond
37 @section Blocs de code Lilypond
38 @translationof Lilypond code blocks
43 @node Fonctions Scheme
44 @section Fonctions Scheme
45 @translationof Scheme functions
47 @cindex Scheme, fonctions (syntaxe LilyPond)
53 * Définition de fonctions Scheme::
54 * Utilisation de fonctions Scheme::
55 * Fonctions Scheme fantômes::
58 @node Définition de fonctions Scheme
59 @subsection Définition de fonctions Scheme
60 @translationof Scheme function definitions
62 @funindex define-scheme-function
67 @node Utilisation de fonctions Scheme
68 @subsection Utilisation de fonctions Scheme
69 @translationof Scheme function usage
74 @node Fonctions Scheme fantômes
75 @subsection Fonctions Scheme fantômes
76 @translationof Void scheme functions
77 @funindex define-void-function
83 @node Fonctions musicales
84 @section Fonctions musicales
85 @translationof Music functions
87 @cindex musicale, fonction
92 * Définition de fonctions musicales::
93 * Utilisation de fonctions musicales::
94 * Fonctions de substitution simple::
95 * Fonctions de substitution intermédiaires::
96 * De l'usage des mathématiques dans les fonctions::
97 * Fonctions dépourvues d'argument::
98 * Fonctions musicales fantômes::
102 @node Définition de fonctions musicales
103 @subsection Définition de fonctions musicales
104 @translationof Music function definitions
106 @cindex defining music functions
107 @funindex define-music-function
112 @node Utilisation de fonctions musicales
113 @subsection Utilisation de fonctions musicales
114 @translationof Music function usage
119 @node Fonctions de substitution simple
120 @subsection Fonctions de substitution simple
121 @translationof Simple substitution functions
126 @node Fonctions de substitution intermédiaires
127 @subsection Fonctions de substitution intermédiaires
128 @translationof Intermediate substitution functions
133 @node De l'usage des mathématiques dans les fonctions
134 @subsection De l'usage des mathématiques dans les fonctions
135 @translationof Mathematics in functions
140 @node Fonctions dépourvues d'argument
141 @subsection Fonctions dépourvues d'argument
142 @translationof Functions without arguments
147 @node Fonctions musicales fantômes
148 @subsection Fonctions musicales fantômes
149 @translationof Void music functions
154 @node Fonctions événementielles
155 @section Fonctions événementielles
156 @translationof Event functions
158 @funindex define-event-function
159 @cindex event functions
164 @node Fonctions pour markups
165 @section Fonctions pour @emph{markups}
166 @translationof Markup functions
171 * Construction d'un markup en Scheme::
172 * Fonctionnement interne des markups::
173 * Définition d'une nouvelle commande de markup::
174 * Définition d'une nouvelle commande de liste de markups::
178 @node Construction d'un markup en Scheme
179 @subsection Construction d'un @emph{markup} en Scheme
180 @translationof Markup construction in Scheme
182 @cindex defining markup commands
187 @node Fonctionnement interne des markups
188 @subsection Fonctionnement interne des @emph{markups}
189 @translationof How markups work internally
194 @node Définition d'une nouvelle commande de markup
195 @subsection Définition d'une nouvelle commande de @emph{markup}
196 @translationof New markup command definition
201 * Syntaxe d'une commande markup::
202 * Attribution de propriétés::
204 * Adaptation d'une commande incorporée::
208 @node Syntaxe d'une commande markup
209 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
210 @translationof Markup command definition syntax
215 @node Attribution de propriétés
216 @unnumberedsubsubsec Attribution de propriétés
217 @translationof On properties
222 @node Exemple commenté
223 @unnumberedsubsubsec Exemple commenté
224 @translationof A complete example
229 @node Adaptation d'une commande incorporée
230 @unnumberedsubsubsec Adaptation d'une commande incorporée
231 @translationof Adapting builtin commands
236 @node Définition d'une nouvelle commande de liste de markups
237 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
238 @translationof New markup list command definition
243 @node Contextes pour programmeurs
244 @section Contextes pour programmeurs
245 @translationof Contexts for programmers
249 * Évaluation d'un contexte::
250 * Application d'une fonction à tous les objets de mise en forme::
254 @node Évaluation d'un contexte
255 @subsection Évaluation d'un contexte
256 @translationof Context evaluation
258 @cindex calling code during interpreting
259 @funindex \applyContext
264 @node Application d'une fonction à tous les objets de mise en forme
265 @subsection Application d'une fonction à tous les objets de mise en forme
266 @translationof Running a function on all layout objects
269 @cindex calling code on layout objects
270 @funindex \applyOutput
275 @node Fonctions de rappel
276 @section Fonctions de rappel
277 @translationof Callback functions
282 @node Code Scheme intégré
283 @section Code Scheme intégré
284 @translationof Inline Scheme code
286 TODO: the example for this section is ill-chosen since
288 F = -\tweak #'font-size #-3 -\flageolet
290 (note the @samp{-} marking it as a post event) will actually work fine
291 for the stated purpose. Until this section gets a rewrite, let's
292 pretend we don't know.
294 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
295 sa syntaxe. Par exemple, le code suivant produit une erreur.
298 F = \tweak #'font-size #-3 -\flageolet
306 En d'autres termes, @code{\tweak} ne se comporte pas comme une
307 articulation@tie{}: il ne peut notamment pas être accolé avec les
308 symboles @samp{^} ou @samp{_}.
310 C'est en se servant du langage Scheme que l'on peut résoudre ce
311 problème. Dans cet exemple, on a recours aux méthodes décrites dans
312 @ref{Ajout d'articulation à des notes (exemple)}, en
313 particulier quant à l'emploi de @code{\displayMusic}.
316 F = #(let ((m (make-music 'ArticulationEvent
317 'articulation-type "flageolet")))
318 (set! (ly:music-property m 'tweaks)
320 (ly:music-property m 'tweaks)))
329 Ici les propriétés @code{tweak} de l'objet flageolet nommé
330 @samp{m} (créé au moyen de @code{make-music}) sont extraites par
331 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
332 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
333 @code{acons}), et le résultat de cette opération est renvoyé par
334 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
335 finale de @samp{m} lui-même.
338 @node Retouches complexes
339 @section Retouches complexes
340 @translationof Difficult tweaks
342 Certains réglages sont plus délicats que d'autres.
346 L'un d'entre eux est l'apparence des objets dits @qq{extenseurs}
347 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
348 Si, en principe, un seul de ces objets est créé à la fois et peut donc
349 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
350 changement de ligne, ils sont dupliqués au début du ou des systèmes
351 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
352 héritent toutes les propriétés, y compris les éventuelles commandes
355 En d'autres termes, une commande @code{\override} affecte toujours les
356 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
357 partie précédant ou suivant le changement de ligne, il faut intervenir
358 directement dans le processus de mise en page.
359 La fonction de rappel @code{after-line-breaking} contient toute
360 l'opération Scheme effectuée lorsque les sauts de lignes ont été
361 déterminés, et que des objets graphiques ont été divisés sur des
364 Dans l'exemple suivant, on définit une nouvelle opération nommée
365 @code{my-callback}. Cette opération
369 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
371 dans l'affirmative, recherche les différents morceaux de l'objet
373 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
376 dans l'affirmative, applique un espacement supplémentaire
377 (@code{extra-offset}).
380 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
381 de façon à ce que le deuxième morceau d'une liaison divisée soit
385 @lilypond[quote,verbatim,ragged-right]
386 #(define (my-callback grob)
388 ;; l'objet a-t-il été divisé ?
389 (orig (ly:grob-original grob))
391 ;; si oui, rechercher les morceaux frères (siblings)
392 (siblings (if (ly:grob? orig)
393 (ly:spanner-broken-into orig)
396 (if (and (>= (length siblings) 2)
397 (eq? (car (last-pair siblings)) grob))
398 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
401 \override Tie #'after-line-breaking =
409 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
410 rappel @code{after-line-breaking} devra également appeler celle
411 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
412 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
413 également appeler @code{ly:spanner::kill-zero-spanned-time}.
417 Pour des raisons d'ordre technique, certains objets ne peuvent être
418 modifiés par @code{\override}. Parmi ceux-là, les objets
419 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
420 @code{\overrideProperty} sert à les modifier, de façon similaire à
421 @code{\once \override} mais avec une syntaxe différente@tie{}:
425 #"Score.NonMusicalPaperColumn" % Nom de l'objet
426 #'line-break-system-details % Nom de la propriété
427 #'((next-padding . 20)) % Valeur
430 Notez toutefois que la commande @code{\override} peut tout de même être
431 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
432 bloc @code{\context}.
437 @node Interfaces LilyPond Scheme
438 @chapter Interfaces LilyPond Scheme
439 @translationof LilyPond Scheme interfaces