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. See TRANSLATION for details.
12 @node Interfaces for programmers
13 @chapter Interfaces for programmers
15 Advanced tweaks may be performed by using Scheme. If you are
16 not familiar with Scheme, you may wish to read our
17 @ref{Scheme tutorial}.
22 * Contexts for programmers::
23 * Callback functions::
24 * Inline Scheme code::
30 @section Music functions
32 Music functions are scheme functions that are used to
33 automatically create music expressions. They can be used to
34 greatly simplify the input file.
37 * Music function syntax::
38 * Simple substitution functions::
39 * Intermediate substitution functions::
40 * Mathematics in functions::
42 * Functions without arguments::
45 @node Music function syntax
46 @subsection Music function syntax
48 The general syntax of a music function is:
52 #(define-music-function (parser location @var{var_1} @var{var_2}...@var{var_n})
53 (@var{var_1-type?} @var{var_2-type?}...@var{var_n-type?})
54 @var{...valid music expression...})
60 @multitable @columnfractions .33 .66
61 @item @var{var_i} @tab @var{i}th variable
62 @item @var{var_i-type?} @tab type of @var{i}th variable
63 @item @var{...valid music expression...} @tab expression that returns
64 valid music, generally in the form of a Scheme expression. There is
65 also special syntax that allows LilyPond input code in this music
69 The variable type checkers are scheme procedures that will return
70 @code{#t} if a variable is of a given type. Some common types
71 are shown in the table below. Other types can be found in the files
72 @file{lily/music-scheme.cc} and @file{scm/c++.scm}.
74 @multitable @columnfractions .33 .66
75 @headitem Input type @tab @var{vari-type?} notation
76 @item Integer @tab @code{integer?}
77 @item Float (decimal number) @tab @code{number?}
78 @item Text string @tab @code{string?}
79 @item Markup @tab @code{markup?}
80 @item Music expression @tab @code{ly:music?}
81 @item A pair of variables @tab @code{pair?}
84 The @code{parser} and @code{location} arguments are mandatory.
85 The @code{parser} argument is used in the body of the function
86 to gain access to the value of another LilyPond variable.
87 The @code{location} argument is used to set the @q{origin}
88 of the music expression that is built by the music function,
89 so that in case of a syntax error LilyPond
90 can tell the user an appropriate place to look in the input file.
92 @node Simple substitution functions
93 @subsection Simple substitution functions
95 A simple substitution function is a music function whose output music
96 expression is written in LilyPond code, but with an input variable
97 substituted into the LilyPond code. The general form of these functions is
101 #(define-music-function (parser location @var{var1})
104 @emph{... LilyPond input code with} @code{#$var1} @emph{for substition ...}
108 Note that the special characters @code{#@{} and @code{#@}} surround the
111 @multitable @columnfractions .33 .66
112 @item @var{vari} @tab @var{i}th variable
113 @item @var{vari-type?} @tab type of @var{i}th variable
114 @item @var{...music...} @tab normal LilyPond input, using
115 variables as @code{#$var1}, etc.
118 For example, a function can be defined that simplifies
119 setting the padding of a TextScript:
121 @lilypond[quote,verbatim,ragged-right]
122 padText = #(define-music-function (parser location padding) (number?)
124 \once \override TextScript #'padding = #$padding
132 c4^"piu mosso" fis a g
136 In addition to numbers, we can use music expressions such
137 as notes for arguments to music functions:
139 @lilypond[quote,verbatim,ragged-right]
140 custosNote = #(define-music-function (parser location note)
143 \once \override Voice.NoteHead #'stencil =
144 #ly:text-interface::print
145 \once \override Voice.NoteHead #'text =
146 \markup \musicglyph #"custodes.mensural.u0"
147 \once \override Voice.Stem #'stencil = ##f
152 @node Intermediate substitution functions
153 @subsection Intermediate substitution functions
155 Slightly more complicated than simple substitution function,
156 intermediate substitution functions involve a mix of Scheme code and
157 LilyPond code in the music expression to be
160 Some @code{\override} commands require an argument consisting of
161 a pair of numbers (called a @code{cons cell} in Scheme).
163 The pair can be directly passed into the music function,
164 using a @code{pair?} variable:
169 #(define-music-function (parser location beg-end)
172 \once \override Beam #'positions = #$beg-end
176 \manualBeam #'(3 . 6) c8 d e f
181 Alternatively, the numbers making up the pair can be
182 passed as separate arguments, and the Scheme code
183 used to create the pair can be included in the
186 @lilypond[quote,verbatim,ragged-right]
188 #(define-music-function (parser location beg end)
191 \once \override Beam #'positions = #(cons $beg $end)
195 \manualBeam #3 #6 c8 d e f
200 @node Mathematics in functions
201 @subsection Mathematics in functions
203 Music functions can involve Scheme programming in
204 addition to simple substitution,
206 @lilypond[quote,verbatim,ragged-right]
207 AltOn = #(define-music-function (parser location mag) (number?)
208 #{ \override Stem #'length = #$(* 7.0 mag)
209 \override NoteHead #'font-size =
210 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
213 \revert Stem #'length
214 \revert NoteHead #'font-size
217 { c'2 \AltOn #0.5 c'4 c'
218 \AltOn #1.5 c' c' \AltOff c'2 }
222 This example may be rewritten to pass in music expressions,
224 @lilypond[quote,verbatim,ragged-right]
225 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
226 #{ \override Stem #'length = #$(* 7.0 mag)
227 \override NoteHead #'font-size =
228 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
230 \revert Stem #'length
231 \revert NoteHead #'font-size #})
233 { c'2 \withAlt #0.5 {c'4 c'}
234 \withAlt #1.5 {c' c'} c'2 }
238 @subsection Void functions
240 A music function must return a music expression, but sometimes we
241 may want to have a function that does not involve music (such as
242 turning off Point and Click). To do this, we return a @code{void}
246 that is returned is the @code{(make-music ...)}. With the
247 @code{'void} property set to @code{#t}, the parser is told to
248 actually disregard this returned music
249 expression. Thus the important part of the void music function is the
250 processing done by the function, not the music expression that is
255 #(define-music-function (parser location) ()
256 (ly:set-option 'point-and-click #f)
257 (make-music 'SequentialMusic 'void #t))
259 \noPointAndClick % disable point and click
263 @node Functions without arguments
264 @subsection Functions without arguments
266 In most cases a function without arguments should be written
270 dolce = \markup@{ \italic \bold dolce @}
273 However, in rare cases it may be useful to create a music function
278 #(define-music-function (parser location) ()
279 (if (eq? #t (ly:get-option 'display-bar-numbers))
280 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
284 To actually display bar numbers where this function is called,
285 invoke @command{lilypond} with
288 lilypond -d display-bar-numbers FILENAME.ly
293 @node Markup functions
294 @section Markup functions
296 Markups are implemented as special Scheme functions which produce a
297 @code{Stencil} object given a number of arguments.
300 * Markup construction in Scheme::
301 * How markups work internally::
302 * New markup command definition::
303 * New markup list command definition::
307 @node Markup construction in Scheme
308 @subsection Markup construction in Scheme
310 @cindex defining markup commands
312 The @code{markup} macro builds markup expressions in Scheme while
313 providing a LilyPond-like syntax. For example,
315 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
316 #:larger #:line ("foo" "bar" "baz")))
322 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
323 \larger \line @{ foo bar baz @} @}
327 This example demonstrates the main translation rules between regular
328 LilyPond markup syntax and Scheme markup syntax.
331 @multitable @columnfractions .3 .3
332 @item @b{LilyPond} @tab @b{Scheme}
333 @item @code{\markup markup1} @tab @code{(markup markup1)}
334 @item @code{\markup @{ markup1 markup2 ... @}} @tab
335 @code{(markup markup1 markup2 ... )}
336 @item @code{\markup-command} @tab @code{#:markup-command}
337 @item @code{\variable} @tab @code{variable}
338 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
339 @item @code{string} @tab @code{"string"}
340 @item @code{#scheme-arg} @tab @code{scheme-arg}
344 The whole Scheme language is accessible inside the
345 @code{markup} macro. For example, You may use function calls inside
346 @code{markup} in order to manipulate character strings. This is
347 useful when defining new markup commands (see
348 @ref{New markup command definition}).
353 The markup-list argument of commands such as @code{#:line},
354 @code{#:center}, and @code{#:column} cannot be a variable or
355 the result of a function call.
358 (markup #:line (function-that-returns-markups))
362 is invalid. One should use the @code{make-line-markup},
363 @code{make-center-markup}, or @code{make-column-markup} functions
367 (markup (make-line-markup (function-that-returns-markups)))
371 @node How markups work internally
372 @subsection How markups work internally
377 \raise #0.5 "text example"
381 @code{\raise} is actually represented by the @code{raise-markup}
382 function. The markup expression is stored as
385 (list raise-markup 0.5 (list simple-markup "text example"))
388 When the markup is converted to printable objects (Stencils), the
389 @code{raise-markup} function is called as
394 @var{list of property alists}
396 @var{the "text example" markup})
399 The @code{raise-markup} function first creates the stencil for the
400 @code{text example} string, and then it raises that Stencil by 0.5
401 staff space. This is a rather simple example; more complex examples
403 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
406 @node New markup command definition
407 @subsection New markup command definition
409 This section discusses the definition of new markup commands.
412 * Markup command definition syntax::
414 * A complete example::
415 * Adapting builtin commands::
418 @node Markup command definition syntax
419 @unnumberedsubsubsec Markup command definition syntax
421 New markup commands can be defined using the
422 @code{define-markup-command} Scheme macro, at top-level.
425 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
426 (@var{arg1-type?} @var{arg2-type?} ...)
427 [ #:properties ((@var{property1} @var{default-value1})
436 the markup command name
438 the @q{layout} definition.
440 a list of associative lists, containing all active properties.
442 @var{i}th command argument
444 a type predicate for the i@var{th} argument
447 If the command uses properties from the @var{props} arguments, the
448 @code{#:properties} keyword can be used, to specify which properties are
449 used, and their default values.
452 There are restrictions on the possible arguments to a markup command.
454 Arguments are distingued according to their type:
456 @item a markup, corresponding to type predicate @code{markup?};
457 @item a list of markup, corresponding to type predicate
459 @item any other scheme object, corresponding to type predicates such as
460 @code{list?}, @code{number?}, @code{boolean?}, etc.
463 The available combinations of arguments (after the standard @var{layout}
464 and @var{props} arguments) to a markup command defined with
465 @code{define-markup-command} are limited as follows.
469 @itemx @var{markup-list}
471 @itemx @var{markup markup}
473 @itemx @var{scheme markup}
474 @itemx @var{scheme scheme}
475 @itemx @var{scheme scheme markup}
476 @itemx @var{scheme scheme markup markup}
477 @itemx @var{scheme markup markup}
478 @itemx @var{scheme scheme scheme}
482 This means that it is not possible to define with e.g. three scheme
483 arguments and a markup arguments, like:
486 #(define-markup-command (foo layout props
487 num1 num2 a-list a-markup)
488 (number? number? list? markup?)
493 If you apply it as, say,
496 \markup \foo #1 #2 #'(bar baz) Blah
499 @cindex Scheme signature
500 @cindex signature, Scheme
502 @command{lilypond} complains that it cannot parse @code{foo} due to its
503 unknown Scheme signature.
506 @unnumberedsubsubsec On properties
508 The @code{layout} and @code{props} arguments of markup commands bring a
509 context for the markup interpretation: font size, line width, etc.
511 The @code{layout} argument allows access to properties defined in
512 @code{paper} blocks, using the @code{ly:output-def-lookup} function.
513 For instance, the line width (the same as the one used in scores) is
517 (ly:output-def-lookup layout 'line-width)
520 The @code{props} argument makes some properties accessible to markup
521 commands. For instance, when a book title markup is interpreted, all
522 the variables defined in the @code{\header} block are automatically
523 added to @code{props}, so that the book title markup can access the book
524 title, composer, etc. It is also a way to configure the behaviour of a
525 markup command: for example, when a command uses font size during
526 processing, the font size is read from @code{props} rather than having a
527 @code{font-size} argument. The caller of a markup command may change
528 the value of the font size property in order to change the behaviour.
529 Use the @code{#:properties} keyword of @code{define-markup-command} to
530 specify which properties shall be read from the @code{props} arguments.
532 The example in next section illustrates how to access and override
533 properties in a markup command.
535 @node A complete example
536 @unnumberedsubsubsec A complete example
538 The following example defines a markup command to draw a double box
539 around a piece of text.
541 Firstly, we need to build an approximative result using markups.
542 Consulting the @ruser{Text markup commands} shows us the @code{\box}
545 @lilypond[quote,verbatim,ragged-right]
546 \markup \box \box HELLO
549 Now, we consider that more padding between the text and the boxes is
550 preferable. According to the @code{\box} documentation, this command
551 uses a @code{box-padding} property, which defaults to 0.2. The
552 documentation also mentions how to override it:
554 @lilypond[quote,verbatim,ragged-right]
555 \markup \box \override #'(box-padding . 0.6) \box A
558 Then, the padding between the two boxes is considered too small, so we
561 @lilypond[quote,verbatim,ragged-right]
562 \markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
565 Repeating this lengthy markup would be painful. This is where a markup
566 command is needed. Thus, we write a @code{double-box} markup command,
567 taking one argument (the text). This draws the two boxes, with some
571 #(define-markup-command (double-box layout props text) (markup?)
572 "Draw a double box around text."
573 (interpret-markup layout props
574 (markup #:override '(box-padding . 0.4) #:box
575 #:override '(box-padding . 0.6) #:box text)))
578 @code{text} is the name of the command argument, and @code{markup?} its
579 type: it identifies it as a markup. The @code{interpret-markup}
580 function is used in most of markup commands: it builds a stencil, using
581 @code{layout}, @code{props}, and a markup. Here, this markup is built
582 using the @code{markup} scheme macro, see @ref{Markup construction in Scheme}.
583 The transformation from @code{\markup} expression to scheme
584 markup expression is straight-forward.
586 The new command can be used as follow:
589 \markup \double-box A
592 It would be nice to make the @code{double-box} command customizable:
593 here, the @code{box-padding} values are hard coded, and cannot be
594 changed by the user. Also, it would be better to distinguish the
595 padding between the two boxes, from the padding between the inner box
596 and the text. So we will introduce a new property,
597 @code{inter-box-padding}, for the padding between the two boxes. The
598 @code{box-padding} will be used for the inner padding. The new code is
602 #(define-markup-command (double-box layout props text) (markup?)
603 #:properties ((inter-box-padding 0.4)
605 "Draw a double box around text."
606 (interpret-markup layout props
607 (markup #:override `(box-padding . ,inter-box-padding) #:box
608 #:override `(box-padding . ,box-padding) #:box text)))
611 Here, the @code{#:properties} keyword is used so that the
612 @code{inter-box-padding} and @code{box-padding} properties are read from
613 the @code{props} argument, and default values are given to them if the
614 properties are not defined.
616 Then, these values are used to override the @code{box-padding}
617 properties used by the two @code{\box} commands. Note the backquote and
618 the comma in the @code{\override} argument: they allow you to introduce
619 a variable value into a literal expression.
621 Now, the command can be used in a markup, and the boxes padding be
624 @lilypond[quote,verbatim,ragged-right]
625 #(define-markup-command (double-box layout props text) (markup?)
626 #:properties ((inter-box-padding 0.4)
628 "Draw a double box around text."
629 (interpret-markup layout props
630 (markup #:override `(box-padding . ,inter-box-padding) #:box
631 #:override `(box-padding . ,box-padding) #:box text)))
633 \markup \double-box A
634 \markup \override #'(inter-box-padding . 0.8) \double-box A
635 \markup \override #'(box-padding . 1.0) \double-box A
638 @node Adapting builtin commands
639 @unnumberedsubsubsec Adapting builtin commands
641 A good way to start writing a new markup command, is to take example on
642 a builtin one. Most of the markup commands provided with LilyPond can be
643 found in file @file{scm/@/define@/-markup@/-commands@/.scm}.
645 For instance, we would like to adapt the @code{\draw-line} command, to
646 draw a double line instead. The @code{\draw-line} command is defined as
647 follow (documentation stripped):
650 (define-markup-command (draw-line layout props dest)
653 #:properties ((thickness 1))
655 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
659 (make-line-stencil th 0 0 x y)))
662 To define a new command based on an existing one, copy the definition,
663 and change the command name. The @code{#:category} keyword can be
664 safely removed, as it is only used for generating LilyPond
665 documentation, and is of no use for user-defined markup commands.
668 (define-markup-command (draw-double-line layout props dest)
670 #:properties ((thickness 1))
672 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
676 (make-line-stencil th 0 0 x y)))
679 Then, a property for setting the gap between two lines is added, called
680 @code{line-gap}, defaulting e.g. to 0.6:
683 (define-markup-command (draw-double-line layout props dest)
685 #:properties ((thickness 1)
691 Finally, the code for drawing two lines is added. Two calls to
692 @code{make-line-stencil} are used to draw the lines, and the resulting
693 stencils are combined using @code{ly:stencil-add}:
695 @lilypond[quote,verbatim,ragged-right]
696 #(define-markup-command (my-draw-line layout props dest)
698 #:properties ((thickness 1)
701 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
706 (x (cond ((= dx 0) w)
708 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
709 (y (* (if (< (* dx dy) 0) 1 -1)
712 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
713 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
714 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
716 \markup \my-draw-line #'(4 . 3)
717 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
721 @node New markup list command definition
722 @subsection New markup list command definition
723 Markup list commands are defined with the
724 @code{define-markup-list-command} Scheme macro, which is similar to the
725 @code{define-markup-command} macro described in
726 @ref{New markup command definition}, except that where the latter returns
727 a single stencil, the former returns a list of stencils.
729 In the following example, a @code{\paragraph} markup list command is
730 defined, which returns a list of justified lines, the first one being
731 indented. The indent width is taken from the @code{props} argument.
733 #(define-markup-list-command (paragraph layout props args) (markup-list?)
734 #:properties ((par-indent 2))
735 (interpret-markup-list layout props
736 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
740 Besides the usual @code{layout} and @code{props} arguments, the
741 @code{paragraph} markup list command takes a markup list argument, named
742 @code{args}. The predicate for markup lists is @code{markup-list?}.
744 First, the function gets the indent width, a property here named
745 @code{par-indent}, from the property list @code{props}. If the
746 property is not found, the default value is @code{2}. Then, a
747 list of justified lines is made using the
748 @code{make-justified-lines-markup-list} function, which is related
749 to the @code{\justified-lines} built-in markup list command. A
750 horizontal space is added at the beginning using the
751 @code{make-hspace-markup} function. Finally, the markup list is
752 interpreted using the @code{interpret-markup-list} function.
754 This new markup list command can be used as follows:
758 The art of music typography is called \italic @{(plate) engraving.@}
759 The term derives from the traditional process of music printing.
760 Just a few decades ago, sheet music was made by cutting and stamping
761 the music into a zinc or pewter plate in mirror image.
763 \override-lines #'(par-indent . 4) \paragraph @{
764 The plate would be inked, the depressions caused by the cutting
765 and stamping would hold ink. An image was formed by pressing paper
766 to the plate. The stamping and cutting was completely done by
772 @node Contexts for programmers
773 @section Contexts for programmers
776 * Context evaluation::
777 * Running a function on all layout objects::
780 @node Context evaluation
781 @subsection Context evaluation
783 @cindex calling code during interpreting
784 @funindex \applyContext
786 Contexts can be modified during interpretation with Scheme code. The
789 \applyContext @var{function}
792 @var{function} should be a Scheme function that takes a single
793 argument: the context in which the @code{\applyContext} command is
794 being called. The following code will print the current bar
795 number on the standard output during the compile:
800 (format #t "\nWe were called in barnumber ~a.\n"
801 (ly:context-property x 'currentBarNumber)))
806 @node Running a function on all layout objects
807 @subsection Running a function on all layout objects
810 @cindex calling code on layout objects
811 @funindex \applyOutput
814 The most versatile way of tuning an object is @code{\applyOutput}. Its
817 \applyOutput @var{context} @var{proc}
821 where @var{proc} is a Scheme function, taking three arguments.
823 When interpreted, the function @var{proc} is called for every layout
824 object found in the context @var{context}, with the following
827 @item the layout object itself,
828 @item the context where the layout object was created, and
829 @item the context where @code{\applyOutput} is processed.
833 In addition, the cause of the layout object, i.e., the music
834 expression or object that was responsible for creating it, is in the
835 object property @code{cause}. For example, for a note head, this is a
836 @rinternals{NoteHead} event, and for a @rinternals{Stem} object,
837 this is a @rinternals{NoteHead} object.
839 Here is a function to use for @code{\applyOutput}; it blanks
840 note-heads on the center-line:
842 @lilypond[quote,verbatim,ragged-right]
843 #(define (blanker grob grob-origin context)
844 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
845 (eq? (ly:grob-property grob 'staff-position) 0))
846 (set! (ly:grob-property grob 'transparent) #t)))
849 e4 g8 \applyOutput #'Voice #blanker b d2
854 @node Callback functions
855 @section Callback functions
857 Properties (like @code{thickness}, @code{direction}, etc.) can be
858 set at fixed values with @code{\override}, e.g.
861 \override Stem #'thickness = #2.0
864 Properties can also be set to a Scheme procedure,
866 @lilypond[fragment,verbatim,quote,relative=2]
867 \override Stem #'thickness = #(lambda (grob)
868 (if (= UP (ly:grob-property grob 'direction))
875 In this case, the procedure is executed as soon as the value of the
876 property is requested during the formatting process.
878 Most of the typesetting engine is driven by such callbacks.
879 Properties that typically use callbacks include
883 The printing routine, that constructs a drawing for the symbol
885 The routine that sets the horizontal position
887 The routine that computes the width of an object
890 The procedure always takes a single argument, being the grob.
892 If routines with multiple arguments must be called, the current grob
893 can be inserted with a grob closure. Here is a setting from
894 @code{AccidentalSuggestion},
898 ,(ly:make-simple-closure
900 ,(ly:make-simple-closure
901 (list ly:self-alignment-interface::centered-on-x-parent))
902 ,(ly:make-simple-closure
903 (list ly:self-alignment-interface::x-aligned-on-self)))))
907 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
908 @code{ly:self-alignment-interface::centered-on-x-parent} are called
909 with the grob as argument. The results are added with the @code{+}
910 function. To ensure that this addition is properly executed, the whole
911 thing is enclosed in @code{ly:make-simple-closure}.
913 In fact, using a single procedure as property value is equivalent to
916 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
920 The inner @code{ly:make-simple-closure} supplies the grob as argument
921 to @var{proc}, the outer ensures that result of the function is
922 returned, rather than the @code{simple-closure} object.
925 @node Inline Scheme code
926 @section Inline Scheme code
928 The main disadvantage of @code{\tweak} is its syntactical
929 inflexibility. For example, the following produces a syntax error.
932 F = \tweak #'font-size #-3 -\flageolet
940 In other words, @code{\tweak} doesn't behave like an articulation
941 regarding the syntax; in particular, it can't be attached with
942 @code{^} and @code{_}.
944 Using Scheme, this problem can be avoided. The route to the
945 result is given in @ref{Adding articulation to notes (example)},
946 especially how to use @code{\displayMusic} as a helping guide.
949 F = #(let ((m (make-music 'ArticulationEvent
950 'articulation-type "flageolet")))
951 (set! (ly:music-property m 'tweaks)
953 (ly:music-property m 'tweaks)))
962 Here, the @code{tweaks} properties of the flageolet object
963 @code{m} (created with @code{make-music}) are extracted with
964 @code{ly:music-property}, a new key-value pair to change the
965 font size is prepended to the property list with the
966 @code{acons} Scheme function, and the result is finally
967 written back with @code{set!}. The last element of the
968 @code{let} block is the return value, @code{m} itself.
972 @node Difficult tweaks
973 @section Difficult tweaks
975 There are a few classes of difficult adjustments.
981 One type of difficult adjustment involves the appearance of
982 spanner objects, such as slurs and ties. Usually, only one
983 spanner object is created at a time, and it can be adjusted with
984 the normal mechanism. However, occasionally a spanner crosses a
985 line break. When this happens, the object is cloned. A separate
986 object is created for every system in which the spanner appears.
987 The new objects are clones of the original object and inherit all
988 properties, including @code{\override}s.
991 In other words, an @code{\override} always affects all pieces of a
992 broken spanner. To change only one part of a spanner at a line break,
993 it is necessary to hook into the formatting process. The
994 @code{after-line-breaking} callback contains the Scheme procedure that
995 is called after the line breaks have been determined and layout
996 objects have been split over different systems.
998 In the following example, we define a procedure
999 @code{my-callback}. This procedure
1003 determines if the spanner has been split across line breaks
1005 if yes, retrieves all the split objects
1007 checks if this grob is the last of the split objects
1009 if yes, it sets @code{extra-offset}.
1012 This procedure is installed into @rinternals{Tie}, so the last part
1013 of the broken tie is repositioned.
1015 @lilypond[quote,verbatim,ragged-right]
1016 #(define (my-callback grob)
1018 ; have we been split?
1019 (orig (ly:grob-original grob))
1021 ; if yes, get the split pieces (our siblings)
1022 (siblings (if (ly:grob? orig)
1023 (ly:spanner-broken-into orig) '() )))
1025 (if (and (>= (length siblings) 2)
1026 (eq? (car (last-pair siblings)) grob))
1027 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1030 \override Tie #'after-line-breaking =
1037 When applying this trick, the new @code{after-line-breaking} callback
1038 should also call the old one @code{after-line-breaking}, if there is
1039 one. For example, if using this with @code{Hairpin},
1040 @code{ly:hairpin::after-line-breaking} should also be called.
1043 @item Some objects cannot be changed with @code{\override} for
1044 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1045 and @code{PaperColumn}. They can be changed with the
1046 @code{\overrideProperty} function, which works similar to @code{\once
1047 \override}, but uses a different syntax.
1051 #"Score.NonMusicalPaperColumn" % Grob name
1052 #'line-break-system-details % Property name
1053 #'((next-padding . 20)) % Value
1056 Note, however, that @code{\override}, applied to
1057 @code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
1058 expected within @code{\context} blocks.
1062 @node LilyPond Scheme interfaces
1063 @chapter LilyPond Scheme interfaces
1065 This chapter covers the various tools provided by LilyPond to help
1066 Scheme programmers get information into and out of the music streams.
1068 TODO -- figure out what goes in here and how to organize it