1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
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 @node Interfaces for programmers
14 @chapter Interfaces for programmers
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}.
23 * Contexts for programmers::
24 * Callback functions::
25 * Inline Scheme code::
31 @section Music functions
33 Music functions are scheme functions that are used to
34 automatically create music expressions. They can be used to
35 greatly simplify the input file.
38 * Music function syntax::
39 * Simple substitution functions::
40 * Intermediate substitution functions::
41 * Mathematics in functions::
43 * Functions without arguments::
46 @node Music function syntax
47 @subsection Music function syntax
49 The general syntax of a music function is:
53 #(define-music-function (parser location @var{var_1} @var{var_2}...@var{var_n})
54 (@var{var_1-type?} @var{var_2-type?}...@var{var_n-type?})
55 @var{...valid music expression...})
61 @multitable @columnfractions .33 .66
62 @item @var{var_i} @tab @var{i}th variable
63 @item @var{var_i-type?} @tab type of @var{i}th variable
64 @item @var{...valid music expression...} @tab expression that returns
65 valid music, generally in the form of a Scheme expression. There is
66 also special syntax that allows LilyPond input code in this music
70 The variable type checkers are scheme procedures that will return
71 @code{#t} if a variable is of a given type. Some common types
72 are shown in the table below. Other types can be found in the files
73 @file{lily/music-scheme.cc} and @file{scm/c++.scm}.
75 @multitable @columnfractions .33 .66
76 @headitem Input type @tab @var{vari-type?} notation
77 @item Integer @tab @code{integer?}
78 @item Float (decimal number) @tab @code{number?}
79 @item Text string @tab @code{string?}
80 @item Markup @tab @code{markup?}
81 @item Music expression @tab @code{ly:music?}
82 @item A pair of variables @tab @code{pair?}
85 The @code{parser} and @code{location} arguments are mandatory.
86 The @code{parser} argument is used in the body of the function
87 to gain access to the value of another LilyPond variable.
88 The @code{location} argument is used to set the @q{origin}
89 of the music expression that is built by the music function,
90 so that in case of a syntax error LilyPond
91 can tell the user an appropriate place to look in the input file.
93 @node Simple substitution functions
94 @subsection Simple substitution functions
96 A simple substitution function is a music function whose output music
97 expression is written in LilyPond code, but with an input variable
98 substituted into the LilyPond code. The general form of these functions is
102 #(define-music-function (parser location @var{var1})
105 @emph{... LilyPond input code with} @code{#$var1} @emph{for substition ...}
109 Note that the special characters @code{#@{} and @code{#@}} surround the
112 @multitable @columnfractions .33 .66
113 @item @var{vari} @tab @var{i}th variable
114 @item @var{vari-type?} @tab type of @var{i}th variable
115 @item @var{...music...} @tab normal LilyPond input, using
116 variables as @code{#$var1}, etc.
119 For example, a function can be defined that simplifies
120 setting the padding of a TextScript:
122 @lilypond[quote,verbatim,ragged-right]
123 padText = #(define-music-function (parser location padding) (number?)
125 \once \override TextScript #'padding = #$padding
133 c4^"piu mosso" fis a g
137 In addition to numbers, we can use music expressions such
138 as notes for arguments to music functions:
140 @lilypond[quote,verbatim,ragged-right]
141 custosNote = #(define-music-function (parser location note)
144 \once \override Voice.NoteHead #'stencil =
145 #ly:text-interface::print
146 \once \override Voice.NoteHead #'text =
147 \markup \musicglyph #"custodes.mensural.u0"
148 \once \override Voice.Stem #'stencil = ##f
153 @node Intermediate substitution functions
154 @subsection Intermediate substitution functions
156 Slightly more complicated than simple substitution function,
157 intermediate substitution functions involve a mix of Scheme code and
158 LilyPond code in the music expression to be
161 Some @code{\override} commands require an argument consisting of
162 a pair of numbers (called a @code{cons cell} in Scheme).
164 The pair can be directly passed into the music function,
165 using a @code{pair?} variable:
170 #(define-music-function (parser location beg-end)
173 \once \override Beam #'positions = #$beg-end
177 \manualBeam #'(3 . 6) c8 d e f
182 Alternatively, the numbers making up the pair can be
183 passed as separate arguments, and the Scheme code
184 used to create the pair can be included in the
187 @lilypond[quote,verbatim,ragged-right]
189 #(define-music-function (parser location beg end)
192 \once \override Beam #'positions = #(cons $beg $end)
196 \manualBeam #3 #6 c8 d e f
201 @node Mathematics in functions
202 @subsection Mathematics in functions
204 Music functions can involve Scheme programming in
205 addition to simple substitution,
207 @lilypond[quote,verbatim,ragged-right]
208 AltOn = #(define-music-function (parser location mag) (number?)
209 #{ \override Stem #'length = #$(* 7.0 mag)
210 \override NoteHead #'font-size =
211 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
214 \revert Stem #'length
215 \revert NoteHead #'font-size
218 { c'2 \AltOn #0.5 c'4 c'
219 \AltOn #1.5 c' c' \AltOff c'2 }
223 This example may be rewritten to pass in music expressions,
225 @lilypond[quote,verbatim,ragged-right]
226 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
227 #{ \override Stem #'length = #$(* 7.0 mag)
228 \override NoteHead #'font-size =
229 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
231 \revert Stem #'length
232 \revert NoteHead #'font-size #})
234 { c'2 \withAlt #0.5 {c'4 c'}
235 \withAlt #1.5 {c' c'} c'2 }
239 @subsection Void functions
241 A music function must return a music expression, but sometimes we
242 may want to have a function that does not involve music (such as
243 turning off Point and Click). To do this, we return a @code{void}
247 that is returned is the @code{(make-music ...)}. With the
248 @code{'void} property set to @code{#t}, the parser is told to
249 actually disregard this returned music
250 expression. Thus the important part of the void music function is the
251 processing done by the function, not the music expression that is
256 #(define-music-function (parser location) ()
257 (ly:set-option 'point-and-click #f)
258 (make-music 'SequentialMusic 'void #t))
260 \noPointAndClick % disable point and click
264 @node Functions without arguments
265 @subsection Functions without arguments
267 In most cases a function without arguments should be written
271 dolce = \markup@{ \italic \bold dolce @}
274 However, in rare cases it may be useful to create a music function
279 #(define-music-function (parser location) ()
280 (if (eq? #t (ly:get-option 'display-bar-numbers))
281 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
285 To actually display bar numbers where this function is called,
286 invoke @command{lilypond} with
289 lilypond -d display-bar-numbers FILENAME.ly
294 @node Markup functions
295 @section Markup functions
297 Markups are implemented as special Scheme functions which produce a
298 @code{Stencil} object given a number of arguments.
301 * Markup construction in Scheme::
302 * How markups work internally::
303 * New markup command definition::
304 * New markup list command definition::
308 @node Markup construction in Scheme
309 @subsection Markup construction in Scheme
311 @cindex defining markup commands
313 The @code{markup} macro builds markup expressions in Scheme while
314 providing a LilyPond-like syntax. For example,
316 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
317 #:larger #:line ("foo" "bar" "baz")))
323 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
324 \larger \line @{ foo bar baz @} @}
328 This example demonstrates the main translation rules between regular
329 LilyPond markup syntax and Scheme markup syntax.
332 @multitable @columnfractions .3 .3
333 @item @b{LilyPond} @tab @b{Scheme}
334 @item @code{\markup markup1} @tab @code{(markup markup1)}
335 @item @code{\markup @{ markup1 markup2 ... @}} @tab
336 @code{(markup markup1 markup2 ... )}
337 @item @code{\markup-command} @tab @code{#:markup-command}
338 @item @code{\variable} @tab @code{variable}
339 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
340 @item @code{string} @tab @code{"string"}
341 @item @code{#scheme-arg} @tab @code{scheme-arg}
345 The whole Scheme language is accessible inside the
346 @code{markup} macro. For example, You may use function calls inside
347 @code{markup} in order to manipulate character strings. This is
348 useful when defining new markup commands (see
349 @ref{New markup command definition}).
354 The markup-list argument of commands such as @code{#:line},
355 @code{#:center}, and @code{#:column} cannot be a variable or
356 the result of a function call.
359 (markup #:line (function-that-returns-markups))
363 is invalid. One should use the @code{make-line-markup},
364 @code{make-center-markup}, or @code{make-column-markup} functions
368 (markup (make-line-markup (function-that-returns-markups)))
372 @node How markups work internally
373 @subsection How markups work internally
378 \raise #0.5 "text example"
382 @code{\raise} is actually represented by the @code{raise-markup}
383 function. The markup expression is stored as
386 (list raise-markup 0.5 (list simple-markup "text example"))
389 When the markup is converted to printable objects (Stencils), the
390 @code{raise-markup} function is called as
395 @var{list of property alists}
397 @var{the "text example" markup})
400 The @code{raise-markup} function first creates the stencil for the
401 @code{text example} string, and then it raises that Stencil by 0.5
402 staff space. This is a rather simple example; more complex examples
404 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
407 @node New markup command definition
408 @subsection New markup command definition
410 This section discusses the definition of new markup commands.
413 * Markup command definition syntax::
415 * A complete example::
416 * Adapting builtin commands::
419 @node Markup command definition syntax
420 @unnumberedsubsubsec Markup command definition syntax
422 New markup commands can be defined using the
423 @code{define-markup-command} Scheme macro, at top-level.
426 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
427 (@var{arg1-type?} @var{arg2-type?} ...)
428 [ #:properties ((@var{property1} @var{default-value1})
437 the markup command name
439 the @q{layout} definition.
441 a list of associative lists, containing all active properties.
443 @var{i}th command argument
445 a type predicate for the i@var{th} argument
448 If the command uses properties from the @var{props} arguments, the
449 @code{#:properties} keyword can be used, to specify which properties are
450 used, and their default values.
453 There are restrictions on the possible arguments to a markup command.
455 Arguments are distingued according to their type:
457 @item a markup, corresponding to type predicate @code{markup?};
458 @item a list of markup, corresponding to type predicate
460 @item any other scheme object, corresponding to type predicates such as
461 @code{list?}, @code{number?}, @code{boolean?}, etc.
464 The available combinations of arguments (after the standard @var{layout}
465 and @var{props} arguments) to a markup command defined with
466 @code{define-markup-command} are limited as follows.
470 @itemx @var{markup-list}
472 @itemx @var{markup markup}
474 @itemx @var{scheme markup}
475 @itemx @var{scheme scheme}
476 @itemx @var{scheme scheme markup}
477 @itemx @var{scheme scheme markup markup}
478 @itemx @var{scheme markup markup}
479 @itemx @var{scheme scheme scheme}
483 This means that it is not possible to define with e.g. three scheme
484 arguments and a markup arguments, like:
487 #(define-markup-command (foo layout props
488 num1 num2 a-list a-markup)
489 (number? number? list? markup?)
494 If you apply it as, say,
497 \markup \foo #1 #2 #'(bar baz) Blah
500 @cindex Scheme signature
501 @cindex signature, Scheme
503 @command{lilypond} complains that it cannot parse @code{foo} due to its
504 unknown Scheme signature.
507 @unnumberedsubsubsec On properties
509 The @code{layout} and @code{props} arguments of markup commands bring a
510 context for the markup interpretation: font size, line width, etc.
512 The @code{layout} argument allows access to properties defined in
513 @code{paper} blocks, using the @code{ly:output-def-lookup} function.
514 For instance, the line width (the same as the one used in scores) is
518 (ly:output-def-lookup layout 'line-width)
521 The @code{props} argument makes some properties accessible to markup
522 commands. For instance, when a book title markup is interpreted, all
523 the variables defined in the @code{\header} block are automatically
524 added to @code{props}, so that the book title markup can access the book
525 title, composer, etc. It is also a way to configure the behaviour of a
526 markup command: for example, when a command uses font size during
527 processing, the font size is read from @code{props} rather than having a
528 @code{font-size} argument. The caller of a markup command may change
529 the value of the font size property in order to change the behaviour.
530 Use the @code{#:properties} keyword of @code{define-markup-command} to
531 specify which properties shall be read from the @code{props} arguments.
533 The example in next section illustrates how to access and override
534 properties in a markup command.
536 @node A complete example
537 @unnumberedsubsubsec A complete example
539 The following example defines a markup command to draw a double box
540 around a piece of text.
542 Firstly, we need to build an approximative result using markups.
543 Consulting the @ruser{Text markup commands} shows us the @code{\box}
546 @lilypond[quote,verbatim,ragged-right]
547 \markup \box \box HELLO
550 Now, we consider that more padding between the text and the boxes is
551 preferable. According to the @code{\box} documentation, this command
552 uses a @code{box-padding} property, which defaults to 0.2. The
553 documentation also mentions how to override it:
555 @lilypond[quote,verbatim,ragged-right]
556 \markup \box \override #'(box-padding . 0.6) \box A
559 Then, the padding between the two boxes is considered too small, so we
562 @lilypond[quote,verbatim,ragged-right]
563 \markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
566 Repeating this lengthy markup would be painful. This is where a markup
567 command is needed. Thus, we write a @code{double-box} markup command,
568 taking one argument (the text). This draws the two boxes, with some
572 #(define-markup-command (double-box layout props text) (markup?)
573 "Draw a double box around text."
574 (interpret-markup layout props
575 (markup #:override '(box-padding . 0.4) #:box
576 #:override '(box-padding . 0.6) #:box text)))
579 @code{text} is the name of the command argument, and @code{markup?} its
580 type: it identifies it as a markup. The @code{interpret-markup}
581 function is used in most of markup commands: it builds a stencil, using
582 @code{layout}, @code{props}, and a markup. Here, this markup is built
583 using the @code{markup} scheme macro, see @ref{Markup construction in Scheme}.
584 The transformation from @code{\markup} expression to scheme
585 markup expression is straight-forward.
587 The new command can be used as follow:
590 \markup \double-box A
593 It would be nice to make the @code{double-box} command customizable:
594 here, the @code{box-padding} values are hard coded, and cannot be
595 changed by the user. Also, it would be better to distinguish the
596 padding between the two boxes, from the padding between the inner box
597 and the text. So we will introduce a new property,
598 @code{inter-box-padding}, for the padding between the two boxes. The
599 @code{box-padding} will be used for the inner padding. The new code is
603 #(define-markup-command (double-box layout props text) (markup?)
604 #:properties ((inter-box-padding 0.4)
606 "Draw a double box around text."
607 (interpret-markup layout props
608 (markup #:override `(box-padding . ,inter-box-padding) #:box
609 #:override `(box-padding . ,box-padding) #:box text)))
612 Here, the @code{#:properties} keyword is used so that the
613 @code{inter-box-padding} and @code{box-padding} properties are read from
614 the @code{props} argument, and default values are given to them if the
615 properties are not defined.
617 Then, these values are used to override the @code{box-padding}
618 properties used by the two @code{\box} commands. Note the backquote and
619 the comma in the @code{\override} argument: they allow you to introduce
620 a variable value into a literal expression.
622 Now, the command can be used in a markup, and the boxes padding be
625 @lilypond[quote,verbatim,ragged-right]
626 #(define-markup-command (double-box layout props text) (markup?)
627 #:properties ((inter-box-padding 0.4)
629 "Draw a double box around text."
630 (interpret-markup layout props
631 (markup #:override `(box-padding . ,inter-box-padding) #:box
632 #:override `(box-padding . ,box-padding) #:box text)))
634 \markup \double-box A
635 \markup \override #'(inter-box-padding . 0.8) \double-box A
636 \markup \override #'(box-padding . 1.0) \double-box A
639 @node Adapting builtin commands
640 @unnumberedsubsubsec Adapting builtin commands
642 A good way to start writing a new markup command, is to take example on
643 a builtin one. Most of the markup commands provided with LilyPond can be
644 found in file @file{scm/@/define@/-markup@/-commands@/.scm}.
646 For instance, we would like to adapt the @code{\draw-line} command, to
647 draw a double line instead. The @code{\draw-line} command is defined as
648 follow (documentation stripped):
651 (define-markup-command (draw-line layout props dest)
654 #:properties ((thickness 1))
656 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
660 (make-line-stencil th 0 0 x y)))
663 To define a new command based on an existing one, copy the definition,
664 and change the command name. The @code{#:category} keyword can be
665 safely removed, as it is only used for generating LilyPond
666 documentation, and is of no use for user-defined markup commands.
669 (define-markup-command (draw-double-line layout props dest)
671 #:properties ((thickness 1))
673 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
677 (make-line-stencil th 0 0 x y)))
680 Then, a property for setting the gap between two lines is added, called
681 @code{line-gap}, defaulting e.g. to 0.6:
684 (define-markup-command (draw-double-line layout props dest)
686 #:properties ((thickness 1)
692 Finally, the code for drawing two lines is added. Two calls to
693 @code{make-line-stencil} are used to draw the lines, and the resulting
694 stencils are combined using @code{ly:stencil-add}:
696 @lilypond[quote,verbatim,ragged-right]
697 #(define-markup-command (my-draw-line layout props dest)
699 #:properties ((thickness 1)
702 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
707 (x (cond ((= dx 0) w)
709 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
710 (y (* (if (< (* dx dy) 0) 1 -1)
713 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
714 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
715 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
717 \markup \my-draw-line #'(4 . 3)
718 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
722 @node New markup list command definition
723 @subsection New markup list command definition
724 Markup list commands are defined with the
725 @code{define-markup-list-command} Scheme macro, which is similar to the
726 @code{define-markup-command} macro described in
727 @ref{New markup command definition}, except that where the latter returns
728 a single stencil, the former returns a list of stencils.
730 In the following example, a @code{\paragraph} markup list command is
731 defined, which returns a list of justified lines, the first one being
732 indented. The indent width is taken from the @code{props} argument.
734 #(define-markup-list-command (paragraph layout props args) (markup-list?)
735 #:properties ((par-indent 2))
736 (interpret-markup-list layout props
737 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
741 Besides the usual @code{layout} and @code{props} arguments, the
742 @code{paragraph} markup list command takes a markup list argument, named
743 @code{args}. The predicate for markup lists is @code{markup-list?}.
745 First, the function gets the indent width, a property here named
746 @code{par-indent}, from the property list @code{props}. If the
747 property is not found, the default value is @code{2}. Then, a
748 list of justified lines is made using the
749 @code{make-justified-lines-markup-list} function, which is related
750 to the @code{\justified-lines} built-in markup list command. A
751 horizontal space is added at the beginning using the
752 @code{make-hspace-markup} function. Finally, the markup list is
753 interpreted using the @code{interpret-markup-list} function.
755 This new markup list command can be used as follows:
759 The art of music typography is called \italic @{(plate) engraving.@}
760 The term derives from the traditional process of music printing.
761 Just a few decades ago, sheet music was made by cutting and stamping
762 the music into a zinc or pewter plate in mirror image.
764 \override-lines #'(par-indent . 4) \paragraph @{
765 The plate would be inked, the depressions caused by the cutting
766 and stamping would hold ink. An image was formed by pressing paper
767 to the plate. The stamping and cutting was completely done by
773 @node Contexts for programmers
774 @section Contexts for programmers
777 * Context evaluation::
778 * Running a function on all layout objects::
781 @node Context evaluation
782 @subsection Context evaluation
784 @cindex calling code during interpreting
785 @funindex \applyContext
787 Contexts can be modified during interpretation with Scheme code. The
790 \applyContext @var{function}
793 @var{function} should be a Scheme function that takes a single
794 argument: the context in which the @code{\applyContext} command is
795 being called. The following code will print the current bar
796 number on the standard output during the compile:
801 (format #t "\nWe were called in barnumber ~a.\n"
802 (ly:context-property x 'currentBarNumber)))
807 @node Running a function on all layout objects
808 @subsection Running a function on all layout objects
811 @cindex calling code on layout objects
812 @funindex \applyOutput
815 The most versatile way of tuning an object is @code{\applyOutput}. Its
818 \applyOutput @var{context} @var{proc}
822 where @var{proc} is a Scheme function, taking three arguments.
824 When interpreted, the function @var{proc} is called for every layout
825 object found in the context @var{context}, with the following
828 @item the layout object itself,
829 @item the context where the layout object was created, and
830 @item the context where @code{\applyOutput} is processed.
834 In addition, the cause of the layout object, i.e., the music
835 expression or object that was responsible for creating it, is in the
836 object property @code{cause}. For example, for a note head, this is a
837 @rinternals{NoteHead} event, and for a @rinternals{Stem} object,
838 this is a @rinternals{NoteHead} object.
840 Here is a function to use for @code{\applyOutput}; it blanks
841 note-heads on the center-line:
843 @lilypond[quote,verbatim,ragged-right]
844 #(define (blanker grob grob-origin context)
845 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
846 (eq? (ly:grob-property grob 'staff-position) 0))
847 (set! (ly:grob-property grob 'transparent) #t)))
850 e4 g8 \applyOutput #'Voice #blanker b d2
855 @node Callback functions
856 @section Callback functions
858 Properties (like @code{thickness}, @code{direction}, etc.) can be
859 set at fixed values with @code{\override}, e.g.
862 \override Stem #'thickness = #2.0
865 Properties can also be set to a Scheme procedure,
867 @lilypond[fragment,verbatim,quote,relative=2]
868 \override Stem #'thickness = #(lambda (grob)
869 (if (= UP (ly:grob-property grob 'direction))
876 In this case, the procedure is executed as soon as the value of the
877 property is requested during the formatting process.
879 Most of the typesetting engine is driven by such callbacks.
880 Properties that typically use callbacks include
884 The printing routine, that constructs a drawing for the symbol
886 The routine that sets the horizontal position
888 The routine that computes the width of an object
891 The procedure always takes a single argument, being the grob.
893 If routines with multiple arguments must be called, the current grob
894 can be inserted with a grob closure. Here is a setting from
895 @code{AccidentalSuggestion},
899 ,(ly:make-simple-closure
901 ,(ly:make-simple-closure
902 (list ly:self-alignment-interface::centered-on-x-parent))
903 ,(ly:make-simple-closure
904 (list ly:self-alignment-interface::x-aligned-on-self)))))
908 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
909 @code{ly:self-alignment-interface::centered-on-x-parent} are called
910 with the grob as argument. The results are added with the @code{+}
911 function. To ensure that this addition is properly executed, the whole
912 thing is enclosed in @code{ly:make-simple-closure}.
914 In fact, using a single procedure as property value is equivalent to
917 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
921 The inner @code{ly:make-simple-closure} supplies the grob as argument
922 to @var{proc}, the outer ensures that result of the function is
923 returned, rather than the @code{simple-closure} object.
926 @node Inline Scheme code
927 @section Inline Scheme code
929 The main disadvantage of @code{\tweak} is its syntactical
930 inflexibility. For example, the following produces a syntax error.
933 F = \tweak #'font-size #-3 -\flageolet
941 In other words, @code{\tweak} doesn't behave like an articulation
942 regarding the syntax; in particular, it can't be attached with
943 @code{^} and @code{_}.
945 Using Scheme, this problem can be avoided. The route to the
946 result is given in @ref{Adding articulation to notes (example)},
947 especially how to use @code{\displayMusic} as a helping guide.
950 F = #(let ((m (make-music 'ArticulationEvent
951 'articulation-type "flageolet")))
952 (set! (ly:music-property m 'tweaks)
954 (ly:music-property m 'tweaks)))
963 Here, the @code{tweaks} properties of the flageolet object
964 @code{m} (created with @code{make-music}) are extracted with
965 @code{ly:music-property}, a new key-value pair to change the
966 font size is prepended to the property list with the
967 @code{acons} Scheme function, and the result is finally
968 written back with @code{set!}. The last element of the
969 @code{let} block is the return value, @code{m} itself.
973 @node Difficult tweaks
974 @section Difficult tweaks
976 There are a few classes of difficult adjustments.
982 One type of difficult adjustment involves the appearance of
983 spanner objects, such as slurs and ties. Usually, only one
984 spanner object is created at a time, and it can be adjusted with
985 the normal mechanism. However, occasionally a spanner crosses a
986 line break. When this happens, the object is cloned. A separate
987 object is created for every system in which the spanner appears.
988 The new objects are clones of the original object and inherit all
989 properties, including @code{\override}s.
992 In other words, an @code{\override} always affects all pieces of a
993 broken spanner. To change only one part of a spanner at a line break,
994 it is necessary to hook into the formatting process. The
995 @code{after-line-breaking} callback contains the Scheme procedure that
996 is called after the line breaks have been determined and layout
997 objects have been split over different systems.
999 In the following example, we define a procedure
1000 @code{my-callback}. This procedure
1004 determines if the spanner has been split across line breaks
1006 if yes, retrieves all the split objects
1008 checks if this grob is the last of the split objects
1010 if yes, it sets @code{extra-offset}.
1013 This procedure is installed into @rinternals{Tie}, so the last part
1014 of the broken tie is repositioned.
1016 @lilypond[quote,verbatim,ragged-right]
1017 #(define (my-callback grob)
1019 ; have we been split?
1020 (orig (ly:grob-original grob))
1022 ; if yes, get the split pieces (our siblings)
1023 (siblings (if (ly:grob? orig)
1024 (ly:spanner-broken-into orig) '() )))
1026 (if (and (>= (length siblings) 2)
1027 (eq? (car (last-pair siblings)) grob))
1028 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1031 \override Tie #'after-line-breaking =
1038 When applying this trick, the new @code{after-line-breaking} callback
1039 should also call the old one @code{after-line-breaking}, if there is
1040 one. For example, if using this with @code{Hairpin},
1041 @code{ly:hairpin::after-line-breaking} should also be called.
1044 @item Some objects cannot be changed with @code{\override} for
1045 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1046 and @code{PaperColumn}. They can be changed with the
1047 @code{\overrideProperty} function, which works similar to @code{\once
1048 \override}, but uses a different syntax.
1052 #"Score.NonMusicalPaperColumn" % Grob name
1053 #'line-break-system-details % Property name
1054 #'((next-padding . 20)) % Value
1057 Note, however, that @code{\override}, applied to
1058 @code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
1059 expected within @code{\context} blocks.
1063 @node LilyPond Scheme interfaces
1064 @chapter LilyPond Scheme interfaces
1066 This chapter covers the various tools provided by LilyPond to help
1067 Scheme programmers get information into and out of the music streams.
1069 TODO -- figure out what goes in here and how to organize it