]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/extending/programming-interface.itely
programming-interface.itely: Improve `\applyOutput' documentation.
[lilypond.git] / Documentation / extending / programming-interface.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2
3 @ignore
4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5
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..
9 @end ignore
10
11 @c \version "2.12.0"
12
13 @node Interfaces for programmers
14 @chapter Interfaces for programmers
15
16 Advanced tweaks may be performed by using Scheme.  If you are
17 not familiar with Scheme, you may wish to read our
18 @ref{Scheme tutorial}.
19
20 @menu
21 * Music functions::
22 * Markup functions::
23 * Contexts for programmers::
24 * Callback functions::
25 * Inline Scheme code::
26 * Difficult tweaks::
27 @end menu
28
29
30 @node Music functions
31 @section Music functions
32
33 @emph{Music functions} are scheme procedures that can create music
34 expressions automatically, and can be used to greatly simplify the
35 input file.
36
37 @menu
38 * Music function syntax::
39 * Simple substitution functions::
40 * Intermediate substitution functions::
41 * Mathematics in functions::
42 * Functions without arguments::
43 * Void functions::
44 @end menu
45
46
47 @node Music function syntax
48 @subsection Music function syntax
49
50 The general form for music functions is:
51
52 @example
53 function =
54 #(define-music-function
55      (parser location @var{arg1} @var{arg2} @dots{})
56      (@var{type1?} @var{type2?} @dots{})
57    @var{music})
58 @end example
59
60 @noindent
61 where
62
63 @multitable @columnfractions .33 .66
64 @item @code{@var{argN}}
65 @tab @var{n}th argument
66
67 @item @code{@var{typeN?}}
68 @tab a scheme @emph{type predicate} for which @code{@var{argN}}
69 must return @code{#t}.
70
71 @item @code{@var{music}}
72 @tab A music expression, optionally written in scheme, with any
73 LilyPond code enclosed in hashed braces
74 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}).  Within LilyPond code
75 blocks, use @code{$} to reference function arguments (eg.,
76 @samp{$arg1}) or to start an inline scheme expression containing
77 function arguments (eg., @w{@samp{$(cons arg1 arg2)}}).
78
79 @end multitable
80
81 @noindent
82 For a list of available type predicates, see
83 @ruser{Predefined type predicates}.  User-defined type predicates
84 are also allowed.
85
86
87 @seealso
88
89 Notation Reference:
90 @ruser{Predefined type predicates}.
91
92 Installed Files:
93 @file{lily/music-scheme.cc},
94 @file{scm/c++.scm},
95 @file{scm/lily.scm}.
96
97
98 @node Simple substitution functions
99 @subsection Simple substitution functions
100
101 Simple substitution functions are music functions whose output
102 music expression is written in LilyPond format and contains
103 function arguments in the output expression.  They are described
104 in @ruser{Substitution function examples}.
105
106
107 @node Intermediate substitution functions
108 @subsection Intermediate substitution functions
109
110 Intermediate substitution functions involve a mix of Scheme code
111 and LilyPond code in the music expression to be returned.
112
113 Some @code{\override} commands require an argument consisting of
114 a pair of numbers (called a @code{cons cell} in Scheme).
115
116 The pair can be directly passed into the music function,
117 using a @code{pair?} variable:
118
119 @example
120 manualBeam =
121 #(define-music-function
122      (parser location beg-end)
123      (pair?)
124    #@{
125      \once \override Beam #'positions = $beg-end
126    #@})
127
128 \relative c' @{
129   \manualBeam #'(3 . 6) c8 d e f
130 @}
131 @end example
132
133 Alternatively, the numbers making up the pair can be
134 passed as separate arguments, and the Scheme code
135 used to create the pair can be included in the
136 music expression:
137
138 @lilypond[quote,verbatim,ragged-right]
139 manualBeam =
140 #(define-music-function
141      (parser location beg end)
142      (number? number?)
143    #{
144      \once \override Beam #'positions = $(cons beg end)
145    #})
146
147 \relative c' {
148   \manualBeam #3 #6 c8 d e f
149 }
150 @end lilypond
151
152
153 @node Mathematics in functions
154 @subsection Mathematics in functions
155
156 Music functions can involve Scheme programming in
157 addition to simple substitution,
158
159 @lilypond[quote,verbatim,ragged-right]
160 AltOn =
161 #(define-music-function
162      (parser location mag)
163      (number?)
164    #{
165      \override Stem #'length = $(* 7.0 mag)
166      \override NoteHead #'font-size =
167        $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
168    #})
169
170 AltOff = {
171   \revert Stem #'length
172   \revert NoteHead #'font-size
173 }
174
175 \relative c' {
176   c2 \AltOn #0.5 c4 c
177   \AltOn #1.5 c c \AltOff c2
178 }
179 @end lilypond
180
181 @noindent
182 This example may be rewritten to pass in music expressions,
183
184 @lilypond[quote,verbatim,ragged-right]
185 withAlt =
186 #(define-music-function
187      (parser location mag music)
188      (number? ly:music?)
189    #{
190      \override Stem #'length = $(* 7.0 mag)
191      \override NoteHead #'font-size =
192        $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
193      $music
194      \revert Stem #'length
195      \revert NoteHead #'font-size
196    #})
197
198 \relative c' {
199   c2 \withAlt #0.5 { c4 c }
200   \withAlt #1.5 { c c } c2
201 }
202 @end lilypond
203
204
205 @node Functions without arguments
206 @subsection Functions without arguments
207
208 In most cases a function without arguments should be written
209 with a variable,
210
211 @example
212 dolce = \markup@{ \italic \bold dolce @}
213 @end example
214
215 However, in rare cases it may be useful to create a music function
216 without arguments,
217
218 @example
219 displayBarNum =
220 #(define-music-function
221      (parser location)
222      ()
223    (if (eq? #t (ly:get-option 'display-bar-numbers))
224        #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
225        #@{#@}))
226 @end example
227
228 To actually display bar numbers where this function is called,
229 invoke @command{lilypond} with
230
231 @example
232 lilypond -d display-bar-numbers FILENAME.ly
233 @end example
234
235
236 @node Void functions
237 @subsection Void functions
238
239 A music function must return a music expression, but sometimes we
240 may want to have a function that does not involve music (such as
241 turning off Point and Click).  To do this, we return a @code{void}
242 music expression.
243
244 That is why the form that is returned is the
245 @w{@code{(make-music @dots{})}}.  With the @code{'void} property
246 set to @code{#t}, the parser is told to actually disregard this
247 returned music expression.  Thus the important part of the void
248 music function is the processing done by the function, not the
249 music expression that is returned.
250
251 @example
252 noPointAndClick =
253 #(define-music-function
254      (parser location)
255      ()
256    (ly:set-option 'point-and-click #f)
257    (make-music 'SequentialMusic 'void #t))
258 ...
259 \noPointAndClick   % disable point and click
260 @end example
261
262
263 @node Markup functions
264 @section Markup functions
265
266 Markups are implemented as special Scheme functions which produce a
267 @code{Stencil} object given a number of arguments.
268
269 @menu
270 * Markup construction in Scheme::
271 * How markups work internally::
272 * New markup command definition::
273 * New markup list command definition::
274 @end menu
275
276
277 @node Markup construction in Scheme
278 @subsection Markup construction in Scheme
279
280 @cindex defining markup commands
281
282 The @code{markup} macro builds markup expressions in Scheme while
283 providing a LilyPond-like syntax.  For example,
284 @example
285 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
286                   #:larger #:line ("foo" "bar" "baz")))
287 @end example
288
289 @noindent
290 is equivalent to:
291 @example
292 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
293                   \larger \line @{ foo bar baz @} @}
294 @end example
295
296 @noindent
297 This example demonstrates the main translation rules between regular
298 LilyPond markup syntax and Scheme markup syntax.
299
300 @quotation
301 @multitable @columnfractions .3 .3
302 @item @b{LilyPond} @tab @b{Scheme}
303 @item @code{\markup markup1} @tab @code{(markup markup1)}
304 @item @code{\markup @{ markup1 markup2 ... @}} @tab
305         @code{(markup markup1 markup2 ... )}
306 @item @code{\markup-command} @tab @code{#:markup-command}
307 @item @code{\variable} @tab @code{variable}
308 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
309 @item @code{string} @tab @code{"string"}
310 @item @code{#scheme-arg} @tab @code{scheme-arg}
311 @end multitable
312 @end quotation
313
314 The whole Scheme language is accessible inside the
315 @code{markup} macro.  For example, You may use function calls inside
316 @code{markup} in order to manipulate character strings.  This is
317 useful when defining new markup commands (see
318 @ref{New markup command definition}).
319
320
321 @knownissues
322
323 The markup-list argument of commands such as @code{#:line},
324 @code{#:center}, and @code{#:column} cannot be a variable or
325 the result of a function call.
326
327 @lisp
328 (markup #:line (function-that-returns-markups))
329 @end lisp
330
331 @noindent
332 is invalid.  One should use the @code{make-line-markup},
333 @code{make-center-markup}, or @code{make-column-markup} functions
334 instead,
335
336 @lisp
337 (markup (make-line-markup (function-that-returns-markups)))
338 @end lisp
339
340
341 @node How markups work internally
342 @subsection How markups work internally
343
344 In a markup like
345
346 @example
347 \raise #0.5 "text example"
348 @end example
349
350 @noindent
351 @code{\raise} is actually represented by the @code{raise-markup}
352 function.  The markup expression is stored as
353
354 @example
355 (list raise-markup 0.5 (list simple-markup "text example"))
356 @end example
357
358 When the markup is converted to printable objects (Stencils), the
359 @code{raise-markup} function is called as
360
361 @example
362 (apply raise-markup
363        @var{\layout object}
364        @var{list of property alists}
365        0.5
366        @var{the "text example" markup})
367 @end example
368
369 The @code{raise-markup} function first creates the stencil for the
370 @code{text example} string, and then it raises that Stencil by 0.5
371 staff space.  This is a rather simple example; more complex examples
372 are in the rest
373 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
374
375
376 @node New markup command definition
377 @subsection New markup command definition
378
379 This section discusses the definition of new markup commands.
380
381 @menu
382 * Markup command definition syntax::
383 * On properties::
384 * A complete example::
385 * Adapting builtin commands::
386 @end menu
387
388 @node Markup command definition syntax
389 @unnumberedsubsubsec Markup command definition syntax
390
391 New markup commands can be defined using the
392 @code{define-markup-command} Scheme macro, at top-level.
393
394 @lisp
395 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
396     (@var{arg1-type?} @var{arg2-type?} ...)
397     [ #:properties ((@var{property1} @var{default-value1})
398                     ...) ]
399   ..command body..)
400 @end lisp
401
402 The arguments are
403
404 @table @var
405 @item command-name
406 the markup command name
407 @item layout
408 the @q{layout} definition.
409 @item props
410 a list of associative lists, containing all active properties.
411 @item argi
412 @var{i}th command argument
413 @item argi-type?
414 a type predicate for the i@var{th} argument
415 @end table
416
417 If the command uses properties from the @var{props} arguments, the
418 @code{#:properties} keyword can be used to specify which properties are
419 used along with their default values.
420
421 Arguments are distinguished according to their type:
422 @itemize
423 @item a markup, corresponding to type predicate @code{markup?};
424 @item a list of markups, corresponding to type predicate
425 @code{markup-list?};
426 @item any other scheme object, corresponding to type predicates such as
427 @code{list?}, @code{number?}, @code{boolean?}, etc.
428 @end itemize
429
430 There is no limitation on the order of arguments (after the standard
431 @var{layout} and @var{props} arguments).  However, markup functions
432 taking a markup as their last argument are somewhat special as you can
433 apply them to a markup list, and the result is a markup list where the
434 markup function (with the specified leading arguments) has been applied
435 to every element of the original markup list.
436
437 Since replicating the leading arguments for applying a markup function
438 to a markup list is cheap mostly for Scheme arguments, you avoid
439 performance pitfalls by just using Scheme arguments for the leading
440 arguments of markup functions that take a markup as their last argument.
441
442 @node On properties
443 @unnumberedsubsubsec On properties
444
445 The @code{layout} and @code{props} arguments of markup commands bring a
446 context for the markup interpretation: font size, line width, etc.
447
448 The @code{layout} argument allows access to properties defined in
449 @code{paper} blocks, using the @code{ly:output-def-lookup} function.
450 For instance, the line width (the same as the one used in scores) is
451 read using:
452
453 @example
454 (ly:output-def-lookup layout 'line-width)
455 @end example
456
457 The @code{props} argument makes some properties accessible to markup
458 commands.  For instance, when a book title markup is interpreted, all
459 the variables defined in the @code{\header} block are automatically
460 added to @code{props}, so that the book title markup can access the book
461 title, composer, etc.  It is also a way to configure the behaviour of a
462 markup command: for example, when a command uses font size during
463 processing, the font size is read from @code{props} rather than having a
464 @code{font-size} argument.  The caller of a markup command may change
465 the value of the font size property in order to change the behaviour.
466 Use the @code{#:properties} keyword of @code{define-markup-command} to
467 specify which properties shall be read from the @code{props} arguments.
468
469 The example in next section illustrates how to access and override
470 properties in a markup command.
471
472 @node A complete example
473 @unnumberedsubsubsec A complete example
474
475 The following example defines a markup command to draw a double box
476 around a piece of text.
477
478 Firstly, we need to build an approximative result using markups.
479 Consulting the @ruser{Text markup commands} shows us the @code{\box}
480 command is useful:
481
482 @lilypond[quote,verbatim,ragged-right]
483 \markup \box \box HELLO
484 @end lilypond
485
486 Now, we consider that more padding between the text and the boxes is
487 preferable.  According to the @code{\box} documentation, this command
488 uses a @code{box-padding} property, which defaults to 0.2.  The
489 documentation also mentions how to override it:
490
491 @lilypond[quote,verbatim,ragged-right]
492 \markup \box \override #'(box-padding . 0.6) \box A
493 @end lilypond
494
495 Then, the padding between the two boxes is considered too small, so we
496 override it too:
497
498 @lilypond[quote,verbatim,ragged-right]
499 \markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
500 @end lilypond
501
502 Repeating this lengthy markup would be painful.  This is where a markup
503 command is needed.  Thus, we write a @code{double-box} markup command,
504 taking one argument (the text).  This draws the two boxes, with some
505 padding.
506
507 @lisp
508 #(define-markup-command (double-box layout props text) (markup?)
509   "Draw a double box around text."
510   (interpret-markup layout props
511     (markup #:override '(box-padding . 0.4) #:box
512             #:override '(box-padding . 0.6) #:box text)))
513 @end lisp
514
515 @code{text} is the name of the command argument, and @code{markup?} its
516 type: it identifies it as a markup.  The @code{interpret-markup}
517 function is used in most of markup commands: it builds a stencil, using
518 @code{layout}, @code{props}, and a markup.  Here, this markup is built
519 using the @code{markup} scheme macro, see @ref{Markup construction in Scheme}.
520 The transformation from @code{\markup} expression to scheme
521 markup expression is straight-forward.
522
523 The new command can be used as follow:
524
525 @example
526 \markup \double-box A
527 @end example
528
529 It would be nice to make the @code{double-box} command customizable:
530 here, the @code{box-padding} values are hard coded, and cannot be
531 changed by the user.  Also, it would be better to distinguish the
532 padding between the two boxes, from the padding between the inner box
533 and the text.  So we will introduce a new property,
534 @code{inter-box-padding}, for the padding between the two boxes.  The
535 @code{box-padding} will be used for the inner padding.  The new code is
536 now as follows:
537
538 @lisp
539 #(define-markup-command (double-box layout props text) (markup?)
540   #:properties ((inter-box-padding 0.4)
541                 (box-padding 0.6))
542   "Draw a double box around text."
543   (interpret-markup layout props
544     (markup #:override `(box-padding . ,inter-box-padding) #:box
545             #:override `(box-padding . ,box-padding) #:box text)))
546 @end lisp
547
548 Here, the @code{#:properties} keyword is used so that the
549 @code{inter-box-padding} and @code{box-padding} properties are read from
550 the @code{props} argument, and default values are given to them if the
551 properties are not defined.
552
553 Then, these values are used to override the @code{box-padding}
554 properties used by the two @code{\box} commands.  Note the backquote and
555 the comma in the @code{\override} argument: they allow you to introduce
556 a variable value into a literal expression.
557
558 Now, the command can be used in a markup, and the boxes padding be
559 customized:
560
561 @lilypond[quote,verbatim,ragged-right]
562 #(define-markup-command (double-box layout props text) (markup?)
563   #:properties ((inter-box-padding 0.4)
564                 (box-padding 0.6))
565   "Draw a double box around text."
566   (interpret-markup layout props
567     (markup #:override `(box-padding . ,inter-box-padding) #:box
568             #:override `(box-padding . ,box-padding) #:box text)))
569
570 \markup \double-box A
571 \markup \override #'(inter-box-padding . 0.8) \double-box A
572 \markup \override #'(box-padding . 1.0) \double-box A
573 @end lilypond
574
575 @node Adapting builtin commands
576 @unnumberedsubsubsec Adapting builtin commands
577
578 A good way to start writing a new markup command, is to take example on
579 a builtin one.  Most of the markup commands provided with LilyPond can be
580 found in file @file{scm/@/define@/-markup@/-commands@/.scm}.
581
582 For instance, we would like to adapt the @code{\draw-line} command, to
583 draw a double line instead.  The @code{\draw-line} command is defined as
584 follow (documentation stripped):
585
586 @lisp
587 (define-markup-command (draw-line layout props dest)
588   (number-pair?)
589   #:category graphic
590   #:properties ((thickness 1))
591   "..documentation.."
592   (let ((th (* (ly:output-def-lookup layout 'line-thickness)
593                thickness))
594         (x (car dest))
595         (y (cdr dest)))
596     (make-line-stencil th 0 0 x y)))
597 @end lisp
598
599 To define a new command based on an existing one, copy the definition,
600 and change the command name.  The @code{#:category} keyword can be
601 safely removed, as it is only used for generating LilyPond
602 documentation, and is of no use for user-defined markup commands.
603
604 @lisp
605 (define-markup-command (draw-double-line layout props dest)
606   (number-pair?)
607   #:properties ((thickness 1))
608   "..documentation.."
609   (let ((th (* (ly:output-def-lookup layout 'line-thickness)
610                thickness))
611         (x (car dest))
612         (y (cdr dest)))
613     (make-line-stencil th 0 0 x y)))
614 @end lisp
615
616 Then, a property for setting the gap between two lines is added, called
617 @code{line-gap}, defaulting e.g. to 0.6:
618
619 @lisp
620 (define-markup-command (draw-double-line layout props dest)
621   (number-pair?)
622   #:properties ((thickness 1)
623                 (line-gap 0.6))
624   "..documentation.."
625   ...
626 @end lisp
627
628 Finally, the code for drawing two lines is added.  Two calls to
629 @code{make-line-stencil} are used to draw the lines, and the resulting
630 stencils are combined using @code{ly:stencil-add}:
631
632 @lilypond[quote,verbatim,ragged-right]
633 #(define-markup-command (my-draw-line layout props dest)
634   (number-pair?)
635   #:properties ((thickness 1)
636                 (line-gap 0.6))
637   "..documentation.."
638   (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
639                 thickness))
640          (dx (car dest))
641          (dy (cdr dest))
642          (w (/ line-gap 2.0))
643          (x (cond ((= dx 0) w)
644                   ((= dy 0) 0)
645                   (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
646          (y (* (if (< (* dx dy) 0) 1 -1)
647                (cond ((= dy 0) w)
648                      ((= dx 0) 0)
649                      (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
650      (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
651                      (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
652
653 \markup \my-draw-line #'(4 . 3)
654 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
655 @end lilypond
656
657
658 @node New markup list command definition
659 @subsection New markup list command definition
660 Markup list commands are defined with the
661 @code{define-markup-list-command} Scheme macro, which is similar to the
662 @code{define-markup-command} macro described in
663 @ref{New markup command definition}, except that where the latter returns
664 a single stencil, the former returns a list of stencils.
665
666 In the following example, a @code{\paragraph} markup list command is
667 defined, which returns a list of justified lines, the first one being
668 indented.  The indent width is taken from the @code{props} argument.
669 @example
670 #(define-markup-list-command (paragraph layout props args) (markup-list?)
671    #:properties ((par-indent 2))
672    (interpret-markup-list layout props
673      (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
674                                              args))))
675 @end example
676
677 Besides the usual @code{layout} and @code{props} arguments, the
678 @code{paragraph} markup list command takes a markup list argument, named
679 @code{args}.  The predicate for markup lists is @code{markup-list?}.
680
681 First, the function gets the indent width, a property here named
682 @code{par-indent}, from the property list @code{props}.  If the
683 property is not found, the default value is @code{2}.  Then, a
684 list of justified lines is made using the
685 @code{make-justified-lines-markup-list} function, which is related
686 to the @code{\justified-lines} built-in markup list command.  A
687 horizontal space is added at the beginning using the
688 @code{make-hspace-markup} function.  Finally, the markup list is
689 interpreted using the @code{interpret-markup-list} function.
690
691 This new markup list command can be used as follows:
692 @example
693 \markuplines @{
694   \paragraph @{
695     The art of music typography is called \italic @{(plate) engraving.@}
696     The term derives from the traditional process of music printing.
697     Just a few decades ago, sheet music was made by cutting and stamping
698     the music into a zinc or pewter plate in mirror image.
699   @}
700   \override-lines #'(par-indent . 4) \paragraph @{
701     The plate would be inked, the depressions caused by the cutting
702     and stamping would hold ink.  An image was formed by pressing paper
703     to the plate.  The stamping and cutting was completely done by
704     hand.
705   @}
706 @}
707 @end example
708
709 @node Contexts for programmers
710 @section Contexts for programmers
711
712 @menu
713 * Context evaluation::
714 * Running a function on all layout objects::
715 @end menu
716
717 @node Context evaluation
718 @subsection Context evaluation
719
720 @cindex calling code during interpreting
721 @funindex \applyContext
722
723 Contexts can be modified during interpretation with Scheme code.  The
724 syntax for this is
725 @example
726 \applyContext @var{function}
727 @end example
728
729 @var{function} should be a Scheme function that takes a single
730 argument: the context in which the @code{\applyContext} command is
731 being called.  The following code will print the current bar
732 number on the standard output during the compile:
733
734 @example
735 \applyContext
736   #(lambda (x)
737     (format #t "\nWe were called in barnumber ~a.\n"
738      (ly:context-property x 'currentBarNumber)))
739 @end example
740
741
742
743 @node Running a function on all layout objects
744 @subsection Running a function on all layout objects
745
746
747 @cindex calling code on layout objects
748 @funindex \applyOutput
749
750
751 The most versatile way of tuning an object is @code{\applyOutput} which
752 works by inserting an event into the specified context
753 (@rinternals{ApplyOutputEvent}).  Its syntax is
754 @example
755 \applyOutput @var{context} @var{proc}
756 @end example
757
758 @noindent
759 where @var{proc} is a Scheme function, taking three arguments.
760
761 When interpreted, the function @var{proc} is called for every layout
762 object found in the context @var{context} at the current time step, with
763 the following arguments:
764 @itemize
765 @item the layout object itself,
766 @item the context where the layout object was created, and
767 @item the context where @code{\applyOutput} is processed.
768 @end itemize
769
770
771 In addition, the cause of the layout object, i.e., the music
772 expression or object that was responsible for creating it, is in the
773 object property @code{cause}.  For example, for a note head, this is a
774 @rinternals{NoteHead} event, and for a stem object,
775 this is a @rinternals{Stem} object.
776
777 Here is a function to use for @code{\applyOutput}; it blanks
778 note-heads on the center-line and next to it:
779
780 @lilypond[quote,verbatim,ragged-right]
781 #(define (blanker grob grob-origin context)
782    (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
783             (< (abs (ly:grob-property grob 'staff-position)) 2))
784        (set! (ly:grob-property grob 'transparent) #t)))
785
786 \relative c' {
787   a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
788 }
789 @end lilypond
790
791
792 @node Callback functions
793 @section Callback functions
794
795 Properties (like @code{thickness}, @code{direction}, etc.) can be
796 set at fixed values with @code{\override}, e.g.
797
798 @example
799 \override Stem #'thickness = #2.0
800 @end example
801
802 Properties can also be set to a Scheme procedure,
803
804 @lilypond[fragment,verbatim,quote,relative=2]
805 \override Stem #'thickness = #(lambda (grob)
806     (if (= UP (ly:grob-property grob 'direction))
807         2.0
808         7.0))
809 c b a g b a g b
810 @end lilypond
811
812 @noindent
813 In this case, the procedure is executed as soon as the value of the
814 property is requested during the formatting process.
815
816 Most of the typesetting engine is driven by such callbacks.
817 Properties that typically use callbacks include
818
819 @table @code
820 @item stencil
821   The printing routine, that constructs a drawing for the symbol
822 @item X-offset
823   The routine that sets the horizontal position
824 @item X-extent
825   The routine that computes the width of an object
826 @end table
827
828 The procedure always takes a single argument, being the grob.
829
830 If routines with multiple arguments must be called, the current grob
831 can be inserted with a grob closure.  Here is a setting from
832 @code{AccidentalSuggestion},
833
834 @example
835 `(X-offset .
836   ,(ly:make-simple-closure
837     `(,+
838         ,(ly:make-simple-closure
839            (list ly:self-alignment-interface::centered-on-x-parent))
840       ,(ly:make-simple-closure
841            (list ly:self-alignment-interface::x-aligned-on-self)))))
842 @end example
843
844 @noindent
845 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
846 @code{ly:self-alignment-interface::centered-on-x-parent} are called
847 with the grob as argument.  The results are added with the @code{+}
848 function.  To ensure that this addition is properly executed, the whole
849 thing is enclosed in @code{ly:make-simple-closure}.
850
851 In fact, using a single procedure as property value is equivalent to
852
853 @example
854 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
855 @end example
856
857 @noindent
858 The inner @code{ly:make-simple-closure} supplies the grob as argument
859 to @var{proc}, the outer ensures that result of the function is
860 returned, rather than the @code{simple-closure} object.
861
862 From within a callback, the easiest method for evaluating a markup is
863 to use grob-interpret-markup.  For example:
864
865 @example
866 my-callback = #(lambda (grob)
867                  (grob-interpret-markup grob (markup "foo")))
868 @end example
869
870 @node Inline Scheme code
871 @section Inline Scheme code
872
873 The main disadvantage of @code{\tweak} is its syntactical
874 inflexibility.  For example, the following produces a syntax error.
875
876 @example
877 F = \tweak #'font-size #-3 -\flageolet
878
879 \relative c'' @{
880   c4^\F c4_\F
881 @}
882 @end example
883
884 @noindent
885 In other words, @code{\tweak} doesn't behave like an articulation
886 regarding the syntax; in particular, it can't be attached with
887 @code{^} and @code{_}.
888
889 Using Scheme, this problem can be avoided.  The route to the
890 result is given in @ref{Adding articulation to notes (example)},
891 especially how to use @code{\displayMusic} as a helping guide.
892
893 @example
894 F = #(let ((m (make-music 'ArticulationEvent
895                           'articulation-type "flageolet")))
896        (set! (ly:music-property m 'tweaks)
897              (acons 'font-size -3
898                     (ly:music-property m 'tweaks)))
899        m)
900
901 \relative c'' @{
902   c4^\F c4_\F
903 @}
904 @end example
905
906 @noindent
907 Here, the @code{tweaks} properties of the flageolet object
908 @code{m} (created with @code{make-music}) are extracted with
909 @code{ly:music-property}, a new key-value pair to change the
910 font size is prepended to the property list with the
911 @code{acons} Scheme function, and the result is finally
912 written back with @code{set!}.  The last element of the
913 @code{let} block is the return value, @code{m} itself.
914
915
916
917 @node Difficult tweaks
918 @section Difficult tweaks
919
920 There are a few classes of difficult adjustments.
921
922 @itemize
923
924
925 @item
926 One type of difficult adjustment involves the appearance of
927 spanner objects, such as slurs and ties.  Usually, only one
928 spanner object is created at a time, and it can be adjusted with
929 the normal mechanism.  However, occasionally a spanner crosses a
930 line break.  When this happens, the object is cloned.  A separate
931 object is created for every system in which the spanner appears.
932 The new objects are clones of the original object and inherit all
933 properties, including @code{\override}s.
934
935
936 In other words, an @code{\override} always affects all pieces of a
937 broken spanner.  To change only one part of a spanner at a line break,
938 it is necessary to hook into the formatting process.  The
939 @code{after-line-breaking} callback contains the Scheme procedure that
940 is called after the line breaks have been determined and layout
941 objects have been split over different systems.
942
943 In the following example, we define a procedure
944 @code{my-callback}.  This procedure
945
946 @itemize
947 @item
948 determines if the spanner has been split across line breaks
949 @item
950 if yes, retrieves all the split objects
951 @item
952 checks if this grob is the last of the split objects
953 @item
954 if yes, it sets @code{extra-offset}.
955 @end itemize
956
957 This procedure is installed into @rinternals{Tie}, so the last part
958 of the broken tie is repositioned.
959
960 @lilypond[quote,verbatim,ragged-right]
961 #(define (my-callback grob)
962    (let* (
963           ;; have we been split?
964           (orig (ly:grob-original grob))
965
966           ;; if yes, get the split pieces (our siblings)
967           (siblings (if (ly:grob? orig)
968                         (ly:spanner-broken-into orig)
969                         '())))
970
971      (if (and (>= (length siblings) 2)
972               (eq? (car (last-pair siblings)) grob))
973          (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
974
975 \relative c'' {
976   \override Tie #'after-line-breaking =
977   #my-callback
978   c1 ~ \break
979   c2 ~ c
980 }
981 @end lilypond
982
983 @noindent
984 When applying this trick, the new @code{after-line-breaking} callback
985 should also call the old one, if such a default exists.  For example,
986 if using this with @code{Hairpin}, @code{ly:spanner::kill-zero-spanned-time}
987 should also be called.
988
989
990 @item
991 Some objects cannot be changed with @code{\override} for
992 technical reasons.  Examples of those are @code{NonMusicalPaperColumn}
993 and @code{PaperColumn}.  They can be changed with the
994 @code{\overrideProperty} function, which works similar to @code{\once
995 \override}, but uses a different syntax.
996
997 @example
998 \overrideProperty
999 #"Score.NonMusicalPaperColumn"  % Grob name
1000 #'line-break-system-details     % Property name
1001 #'((next-padding . 20))         % Value
1002 @end example
1003
1004 Note, however, that @code{\override}, applied to
1005 @code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
1006 expected within @code{\context} blocks.
1007
1008 @end itemize
1009
1010 @node LilyPond Scheme interfaces
1011 @chapter LilyPond Scheme interfaces
1012
1013 This chapter covers the various tools provided by LilyPond to help
1014 Scheme programmers get information into and out of the music streams.
1015
1016 TODO -- figure out what goes in here and how to organize it
1017