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}.
21 * Lilypond code blocks::
26 * Contexts for programmers::
27 * Callback functions::
28 * Inline Scheme code::
32 @node Lilypond code blocks
33 @section Lilypond code blocks
35 Lilypond code blocks look like
37 #@{ @var{Lilypond code} #@}
39 They can be used anywhere where you can write Scheme code: the Scheme
40 reader actually is changed for accommodating LilyPond code blocks. When
41 the LilyPond code block is being read, it is parsed superficially and
42 replaced by a call to the LilyPond @code{parser} which is executed at
43 runtime to interpret the LilyPond code block.
45 The point of the superficial parsing is the interpretation of @code{$}
46 signs which can be used for splicing in expressions from the surrounding
47 lexical Scheme context (like @code{let} variables and function
48 parameters). @code{$} can be used in the following ways:
52 just passes a single @code{$} to the LilyPond parser.
54 will evaluate the Scheme form at runtime and splice its value as an
55 identifier @code{\form} into the LilyPond parser. Depending on the
56 value type, it may be interpreted as several different syntactic
59 will evaluate the Scheme form at runtime and splice its value as a
60 Scheme expression into the LilyPond parser.
62 Forms in Scheme expressions started with @code{#} are read and parsed
63 recursively for @code{$} signs. Those are treated as follows:
64 @item #@dots{}$@var{variable}
65 splices the value of the variable into the surrounding expression.
66 @item #@dots{}($ @var{form} @dots{})
67 splices the value of the form into the surrounding expression. As
68 opposed to a LilyPond level @code{$@var{form}}, you need to separate the
69 form with a blank, making @code{$} be recognizable as a separate Scheme
73 A LilyPond code block may contain anything that you can use on the right
74 side of an assignment. In addition, an empty LilyPond block corresponds
75 to a void music expression, and a LilyPond block containing multiple
76 music events gets turned into a sequential music expression.
78 @node Scheme functions
79 @section Scheme functions
80 @cindex Scheme functions (LilyPond syntax)
82 @emph{Scheme functions} are Scheme procedures that can create Scheme
83 expressions from input written in LilyPond syntax. They can be called
84 in pretty much all places where using @code{#} for specifying a value in
85 Scheme syntax is allowed. While Scheme has functions of its own, this
86 chapter is concerned with @emph{syntactic} functions, functions that
87 receive arguments specified in LilyPond syntax.
90 * Scheme function definitions::
91 * Scheme function usage::
92 * Void scheme functions::
95 @node Scheme function definitions
96 @subsection Scheme function definitions
97 @funindex define-scheme-function
99 The general form for defining scheme functions is:
103 #(define-scheme-function
104 (parser location @var{arg1} @var{arg2} @dots{})
105 (@var{type1?} @var{type2?} @dots{})
112 @multitable @columnfractions .33 .66
114 @tab needs to be literally @code{parser} in order to give LilyPond code
115 blocks (@code{#@{}@dots{}@code{#@}}) access to the parser.
117 @item @code{@var{argN}}
118 @tab @var{n}th argument
120 @item @code{@var{typeN?}}
121 @tab a Scheme @emph{type predicate} for which @code{@var{argN}}
122 must return @code{#t}. Some of these predicates are specially
123 recognized by the parser, see below. There is also a special form
124 @code{(@emph{predicate?} @emph{default})} for specifying optional
125 arguments. If the actual argument is missing when the function is being
126 called, the default value is substituted instead. Default values are
127 evaluated at definition time (including LilyPond code blocks!), so if
128 you need a default calculated at runtime, instead write a special value
129 you can easily recognize. If you write the predicate in parentheses but
130 don't follow it with a default value, @code{#f} is used as the default.
131 Default values are not verified with @emph{predicate?} at either
132 definition or run time: it is your responsibility to deal with the
133 values you specify. Default values that happen to be music expressions
134 are copied while setting @code{origin} to the @code{location} parameter.
136 @item @code{@var{body}}
137 @tab A sequence of Scheme forms evaluated in order, the last one being
138 used as the return value of the scheme function. It may contain
139 LilyPond code blocks enclosed in hashed braces
140 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), like described in @ref{Lilypond
141 code blocks}. Within LilyPond code blocks, use @code{$} to reference
142 function arguments (eg., @samp{$arg1}) or to start an inline Scheme
143 expression containing function arguments (eg., @w{@samp{$(cons arg1
144 arg2)}}). If your function returns a music expression, it is cloned and
145 given the correct @code{origin}.
149 Some type predicates are specially recognized by the parser and will
150 make the parser look for the respective arguments in LilyPond syntax
151 rather than in Scheme syntax. Currently these are @code{ly:music?},
152 @code{markup?}, @code{ly:pitch?}, and @code{ly:duration?}.
154 If you really want to input one of the special items as a Scheme rather
155 than a LilyPond expression, you may write them as a Scheme expression
156 that calls @code{ly:export} at its outermost level.
158 Other type predicates, including user-defined ones, will make the
159 respective argument only be accepted as a Scheme expression, usually
160 introduced with @code{#} or as the result of calling a scheme function
163 For a list of available type predicates, see
164 @ruser{Predefined type predicates}.
169 @ruser{Predefined type predicates}.
172 @file{lily/music-scheme.cc},
176 @node Scheme function usage
177 @subsection Scheme function usage
179 Scheme functions can be called pretty much anywhere where a Scheme
180 expression starting with @code{#} can be written. You call a scheme
181 function by writing its name preceded by @code{\}, followed by its
182 arguments. The last argument can't be an optional argument. If there
183 are several optional arguments in a row, they are filled with values
184 left to right. Once an optional argument can't match input, it and all
185 immediately following optional arguments are replaced with their default
186 values, and the matching continues with the next non-optional argument.
188 Apart from places where a Scheme value is required, there are a few
189 places where @code{#} expressions are accepted and evaluated for their
190 side effects but otherwise ignored. Mostly those are the places where
191 an assignment would be acceptable as well.
193 There are a few special places where an argument matching
194 @code{ly:music?} has to be either a music identifier or a music
195 expression enclosed in @code{@{}@dots{}@code{@}} or
196 @code{<<}@dots{}@code{>>} explicitly, so that possibly following
197 optional durations or postevents can't be confused with additional
198 arguments. One obvious place is before a @code{ly:duration?}
199 predicate. Another is as the last argument of a scheme function when it
200 is used in a place where such optional parts could be considered either
201 part of the music argument or not.
203 In those rare cases, you have to delimit your music arguments
204 appropriately to spare LilyPond from getting confused.
206 @node Void scheme functions
207 @subsection Void scheme functions
209 Sometimes a function is only executed for its side effects. In that
210 case, using a scheme function means that its value will not usually be
215 #(define-scheme-function
218 (ly:set-option 'point-and-click #f))
220 \noPointAndClick % disable point and click
223 @node Music functions
224 @section Music functions
226 @cindex music functions
228 @emph{Music functions} are Scheme procedures that can create music
229 expressions automatically, and can be used to greatly simplify the
233 * Music function definitions::
234 * Music function usage::
235 * Simple substitution functions::
236 * Intermediate substitution functions::
237 * Mathematics in functions::
238 * Functions without arguments::
239 * Void music functions::
243 @node Music function definitions
244 @subsection Music function definitions
245 @cindex defining music functions
246 @funindex define-music-function
248 The general form for defining music functions is:
252 #(define-music-function
253 (parser location @var{arg1} @var{arg2} @dots{})
254 (@var{type1?} @var{type2?} @dots{})
259 quite in analogy to @ref{Scheme function definitions}. More often than
260 not, @var{body} will be a @ref{Lilypond code blocks, Lilypond code block}.
262 For a list of available type predicates, see
263 @ruser{Predefined type predicates}.
268 @ruser{Predefined type predicates}.
271 @file{lily/music-scheme.cc},
276 @node Music function usage
277 @subsection Music function usage
278 Music functions may currently be used in three places. Depending on
279 where they are used, restrictions apply in order to be able to parse
280 them unambiguously. The result a music function returns must be
281 compatible with the context in which it is called.
285 At top level in a music expression. There are no special restrictions
286 on the argument list.
289 As a post-event, explicitly started with a direction indicator (one of
290 @code{-}, @code{^}, @w{and @code{_}}). All trailing arguments of the
291 music function with the predicate @code{ly:music?} will get parsed also
292 as post-events (if the last argument is a scheme function, this will
293 hold for trailing @code{ly:music?} arguments of the scheme function
294 instead). Note that returning a post-event will be acceptable for music
295 functions called as normal music, leading to a result roughly equivalent
302 As a chord constituent. All trailing arguments of the music function
303 with the predicate @code{ly:music?} will get parsed also as chord
308 The special rules for trailing arguments make it possible to write
309 polymorphic functions like @code{\tweak} that can be applied to
310 different constructs.
312 @node Simple substitution functions
313 @subsection Simple substitution functions
315 Simple substitution functions are music functions whose output
316 music expression is written in LilyPond format and contains
317 function arguments in the output expression. They are described
318 in @ruser{Substitution function examples}.
321 @node Intermediate substitution functions
322 @subsection Intermediate substitution functions
324 Intermediate substitution functions involve a mix of Scheme code
325 and LilyPond code in the music expression to be returned.
327 Some @code{\override} commands require an argument consisting of
328 a pair of numbers (called a @emph{cons cell} in Scheme).
330 The pair can be directly passed into the music function,
331 using a @code{pair?} variable:
335 #(define-music-function
336 (parser location beg-end)
339 \once \override Beam #'positions = $beg-end
343 \manualBeam #'(3 . 6) c8 d e f
347 Alternatively, the numbers making up the pair can be
348 passed as separate arguments, and the Scheme code
349 used to create the pair can be included in the
352 @lilypond[quote,verbatim,ragged-right]
354 #(define-music-function
355 (parser location beg end)
358 \once \override Beam #'positions = $(cons beg end)
362 \manualBeam #3 #6 c8 d e f
367 @node Mathematics in functions
368 @subsection Mathematics in functions
370 Music functions can involve Scheme programming in
371 addition to simple substitution,
373 @lilypond[quote,verbatim,ragged-right]
375 #(define-music-function
376 (parser location mag)
379 \override Stem #'length = $(* 7.0 mag)
380 \override NoteHead #'font-size =
381 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
385 \revert Stem #'length
386 \revert NoteHead #'font-size
391 \AltOn #1.5 c c \AltOff c2
396 This example may be rewritten to pass in music expressions,
398 @lilypond[quote,verbatim,ragged-right]
400 #(define-music-function
401 (parser location mag music)
404 \override Stem #'length = $(* 7.0 mag)
405 \override NoteHead #'font-size =
406 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
408 \revert Stem #'length
409 \revert NoteHead #'font-size
413 c2 \withAlt #0.5 { c4 c }
414 \withAlt #1.5 { c c } c2
419 @node Functions without arguments
420 @subsection Functions without arguments
422 In most cases a function without arguments should be written
426 dolce = \markup@{ \italic \bold dolce @}
429 However, in rare cases it may be useful to create a music function
434 #(define-music-function
437 (if (eq? #t (ly:get-option 'display-bar-numbers))
438 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
442 To actually display bar numbers where this function is called,
443 invoke @command{lilypond} with
446 lilypond -d display-bar-numbers FILENAME.ly
450 @node Void music functions
451 @subsection Void music functions
453 A music function must return a music expression. If you want to execute
454 a function only for its side effect, it might make more sense to use a
455 scheme function instead. But there may be cases where you sometimes
456 want to produce a music expression, and sometimes not (like in the
457 previous example). Returning a @code{void} music expression via
458 @code{#@{ #@}} will do that.
460 @node Event functions
461 @section Event functions
462 @funindex define-event-function
463 @cindex event functions
465 To use a music function in the place of an event, you need to write a
466 direction indicator before it. But sometimes, this does not quite match
467 the syntax of constructs you want to replace. For example, if you want
468 to write dynamics commands, those are usually attached without direction
469 indicator, like @code{c'\pp}. Here is a way to write arbitrary
471 @lilypond[quote,verbatim,raggedright]
472 dyn=#(define-event-function (parser location arg) (markup?)
473 (make-dynamic-script arg))
474 \relative c' { c\dyn pfsss }
476 You could do the same using a music function, but then you always would
477 have to write a direction indicator before calling it, like
478 @code{@w{c-\dyn pfsss}}.
481 @node Markup functions
482 @section Markup functions
484 Markups are implemented as special Scheme functions which produce a
485 @code{Stencil} object given a number of arguments.
488 * Markup construction in Scheme::
489 * How markups work internally::
490 * New markup command definition::
491 * New markup list command definition::
495 @node Markup construction in Scheme
496 @subsection Markup construction in Scheme
498 @cindex defining markup commands
500 The @code{markup} macro builds markup expressions in Scheme while
501 providing a LilyPond-like syntax. For example,
503 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
504 #:larger #:line ("foo" "bar" "baz")))
510 #@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
511 \larger \line @{ foo bar baz @} @} #@}
515 This example demonstrates the main translation rules between regular
516 LilyPond markup syntax and Scheme markup syntax. Using @code{#@{
517 @dots{} #@}} for entering in LilyPond syntax will often be most
518 convenient, but we explain how to use the @code{markup} macro to get a
519 Scheme-only solution.
522 @multitable @columnfractions .3 .3
523 @item @b{LilyPond} @tab @b{Scheme}
524 @item @code{\markup markup1} @tab @code{(markup markup1)}
525 @item @code{\markup @{ markup1 markup2 ... @}} @tab
526 @code{(markup markup1 markup2 ... )}
527 @item @code{\markup-command} @tab @code{#:markup-command}
528 @item @code{\variable} @tab @code{variable}
529 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
530 @item @code{string} @tab @code{"string"}
531 @item @code{#scheme-arg} @tab @code{scheme-arg}
535 The whole Scheme language is accessible inside the
536 @code{markup} macro. For example, You may use function calls inside
537 @code{markup} in order to manipulate character strings. This is
538 useful when defining new markup commands (see
539 @ref{New markup command definition}).
544 The markup-list argument of commands such as @code{#:line},
545 @code{#:center}, and @code{#:column} cannot be a variable or
546 the result of a function call.
549 (markup #:line (function-that-returns-markups))
553 is invalid. One should use the @code{make-line-markup},
554 @code{make-center-markup}, or @code{make-column-markup} functions
558 (markup (make-line-markup (function-that-returns-markups)))
562 @node How markups work internally
563 @subsection How markups work internally
568 \raise #0.5 "text example"
572 @code{\raise} is actually represented by the @code{raise-markup}
573 function. The markup expression is stored as
576 (list raise-markup 0.5 (list simple-markup "text example"))
579 When the markup is converted to printable objects (Stencils), the
580 @code{raise-markup} function is called as
585 @var{list of property alists}
587 @var{the "text example" markup})
590 The @code{raise-markup} function first creates the stencil for the
591 @code{text example} string, and then it raises that Stencil by 0.5
592 staff space. This is a rather simple example; more complex examples
594 of this section, and in @file{scm/define-markup-commands.scm}.
597 @node New markup command definition
598 @subsection New markup command definition
600 This section discusses the definition of new markup commands.
603 * Markup command definition syntax::
605 * A complete example::
606 * Adapting builtin commands::
609 @node Markup command definition syntax
610 @unnumberedsubsubsec Markup command definition syntax
612 New markup commands can be defined using the
613 @code{define-markup-command} Scheme macro, at top-level.
616 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
617 (@var{arg1-type?} @var{arg2-type?} ...)
618 [ #:properties ((@var{property1} @var{default-value1})
626 @item @var{command-name}
627 the markup command name
629 the @q{layout} definition.
631 a list of associative lists, containing all active properties.
633 @var{i}th command argument
634 @item @var{argi-type?}
635 a type predicate for the i@var{th} argument
638 If the command uses properties from the @code{props} arguments,
639 the @code{#:properties} keyword can be used to specify which
640 properties are used along with their default values.
642 Arguments are distinguished according to their type:
644 @item a markup, corresponding to type predicate @code{markup?};
645 @item a list of markups, corresponding to type predicate
647 @item any other scheme object, corresponding to type predicates such as
648 @code{list?}, @code{number?}, @code{boolean?}, etc.
651 There is no limitation on the order of arguments (after the
652 standard @code{layout} and @code{props} arguments). However,
653 markup functions taking a markup as their last argument are
654 somewhat special as you can apply them to a markup list, and the
655 result is a markup list where the markup function (with the
656 specified leading arguments) has been applied to every element of
657 the original markup list.
659 Since replicating the leading arguments for applying a markup
660 function to a markup list is cheap mostly for Scheme arguments,
661 you avoid performance pitfalls by just using Scheme arguments for
662 the leading arguments of markup functions that take a markup as
666 @unnumberedsubsubsec On properties
668 The @code{layout} and @code{props} arguments of markup commands bring a
669 context for the markup interpretation: font size, line width, etc.
671 The @code{layout} argument allows access to properties defined in
672 @code{paper} blocks, using the @code{ly:output-def-lookup} function.
673 For instance, the line width (the same as the one used in scores) is
677 (ly:output-def-lookup layout 'line-width)
680 The @code{props} argument makes some properties accessible to markup
681 commands. For instance, when a book title markup is interpreted, all
682 the variables defined in the @code{\header} block are automatically
683 added to @code{props}, so that the book title markup can access the book
684 title, composer, etc. It is also a way to configure the behaviour of a
685 markup command: for example, when a command uses font size during
686 processing, the font size is read from @code{props} rather than having a
687 @code{font-size} argument. The caller of a markup command may change
688 the value of the font size property in order to change the behaviour.
689 Use the @code{#:properties} keyword of @code{define-markup-command} to
690 specify which properties shall be read from the @code{props} arguments.
692 The example in next section illustrates how to access and override
693 properties in a markup command.
695 @node A complete example
696 @unnumberedsubsubsec A complete example
698 The following example defines a markup command to draw a double box
699 around a piece of text.
701 Firstly, we need to build an approximative result using markups.
702 Consulting the @ruser{Text markup commands} shows us the @code{\box}
705 @lilypond[quote,verbatim,ragged-right]
706 \markup \box \box HELLO
709 Now, we consider that more padding between the text and the boxes is
710 preferable. According to the @code{\box} documentation, this command
711 uses a @code{box-padding} property, which defaults to 0.2. The
712 documentation also mentions how to override it:
714 @lilypond[quote,verbatim,ragged-right]
715 \markup \box \override #'(box-padding . 0.6) \box A
718 Then, the padding between the two boxes is considered too small, so we
721 @lilypond[quote,verbatim,ragged-right]
722 \markup \override #'(box-padding . 0.4) \box
723 \override #'(box-padding . 0.6) \box A
726 Repeating this lengthy markup would be painful. This is where a markup
727 command is needed. Thus, we write a @code{double-box} markup command,
728 taking one argument (the text). This draws the two boxes, with some
732 #(define-markup-command (double-box layout props text) (markup?)
733 "Draw a double box around text."
734 (interpret-markup layout props
735 #@{\markup \override #'(box-padding . 0.4) \box
736 \override #'(box-padding . 0.6) \box @{ $text @}#@}))
742 #(define-markup-command (double-box layout props text) (markup?)
743 "Draw a double box around text."
744 (interpret-markup layout props
745 (markup #:override '(box-padding . 0.4) #:box
746 #:override '(box-padding . 0.6) #:box text)))
749 @code{text} is the name of the command argument, and @code{markup?} its
750 type: it identifies it as a markup. The @code{interpret-markup}
751 function is used in most of markup commands: it builds a stencil, using
752 @code{layout}, @code{props}, and a markup. In the second case, this
753 markup is built using the @code{markup} scheme macro, see @ref{Markup
754 construction in Scheme}. The transformation from @code{\markup}
755 expression to scheme markup expression is straight-forward.
757 The new command can be used as follow:
760 \markup \double-box A
763 It would be nice to make the @code{double-box} command customizable:
764 here, the @code{box-padding} values are hard coded, and cannot be
765 changed by the user. Also, it would be better to distinguish the
766 padding between the two boxes, from the padding between the inner box
767 and the text. So we will introduce a new property,
768 @code{inter-box-padding}, for the padding between the two boxes. The
769 @code{box-padding} will be used for the inner padding. The new code is
773 #(define-markup-command (double-box layout props text) (markup?)
774 #:properties ((inter-box-padding 0.4)
776 "Draw a double box around text."
777 (interpret-markup layout props
778 #@{\markup \override #`(box-padding . ,$inter-box-padding) \box
779 \override #`(box-padding . ,$box-padding) \box
783 Again, the equivalent version using the markup macro would be:
786 #(define-markup-command (double-box layout props text) (markup?)
787 #:properties ((inter-box-padding 0.4)
789 "Draw a double box around text."
790 (interpret-markup layout props
791 (markup #:override `(box-padding . ,inter-box-padding) #:box
792 #:override `(box-padding . ,box-padding) #:box text)))
795 Here, the @code{#:properties} keyword is used so that the
796 @code{inter-box-padding} and @code{box-padding} properties are read from
797 the @code{props} argument, and default values are given to them if the
798 properties are not defined.
800 Then, these values are used to override the @code{box-padding}
801 properties used by the two @code{\box} commands. Note the backquote and
802 the comma in the @code{\override} argument: they allow you to introduce
803 a variable value into a literal expression.
805 Now, the command can be used in a markup, and the boxes padding be
808 @lilypond[quote,verbatim,ragged-right]
809 #(define-markup-command (double-box layout props text) (markup?)
810 #:properties ((inter-box-padding 0.4)
812 "Draw a double box around text."
813 (interpret-markup layout props
814 #{\markup \override #`(box-padding . ,$inter-box-padding) \box
815 \override #`(box-padding . ,$box-padding) \box
818 \markup \double-box A
819 \markup \override #'(inter-box-padding . 0.8) \double-box A
820 \markup \override #'(box-padding . 1.0) \double-box A
823 @node Adapting builtin commands
824 @unnumberedsubsubsec Adapting builtin commands
826 A good way to start writing a new markup command, is to take example on
827 a builtin one. Most of the markup commands provided with LilyPond can be
828 found in file @file{scm/define-markup-commands.scm}.
830 For instance, we would like to adapt the @code{\draw-line} command, to
831 draw a double line instead. The @code{\draw-line} command is defined as
832 follow (documentation stripped):
835 (define-markup-command (draw-line layout props dest)
838 #:properties ((thickness 1))
840 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
844 (make-line-stencil th 0 0 x y)))
847 To define a new command based on an existing one, copy the definition,
848 and change the command name. The @code{#:category} keyword can be
849 safely removed, as it is only used for generating LilyPond
850 documentation, and is of no use for user-defined markup commands.
853 (define-markup-command (draw-double-line layout props dest)
855 #:properties ((thickness 1))
857 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
861 (make-line-stencil th 0 0 x y)))
864 Then, a property for setting the gap between two lines is added, called
865 @code{line-gap}, defaulting e.g. to 0.6:
868 (define-markup-command (draw-double-line layout props dest)
870 #:properties ((thickness 1)
876 Finally, the code for drawing two lines is added. Two calls to
877 @code{make-line-stencil} are used to draw the lines, and the resulting
878 stencils are combined using @code{ly:stencil-add}:
880 @lilypond[quote,verbatim,ragged-right]
881 #(define-markup-command (my-draw-line layout props dest)
883 #:properties ((thickness 1)
886 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
891 (x (cond ((= dx 0) w)
893 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
894 (y (* (if (< (* dx dy) 0) 1 -1)
897 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
898 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
899 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
901 \markup \my-draw-line #'(4 . 3)
902 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
906 @node New markup list command definition
907 @subsection New markup list command definition
908 Markup list commands are defined with the
909 @code{define-markup-list-command} Scheme macro, which is similar to the
910 @code{define-markup-command} macro described in
911 @ref{New markup command definition}, except that where the latter returns
912 a single stencil, the former returns a list of stencils.
914 In the following example, a @code{\paragraph} markup list command is
915 defined, which returns a list of justified lines, the first one being
916 indented. The indent width is taken from the @code{props} argument.
919 #(define-markup-list-command (paragraph layout props args) (markup-list?)
920 #:properties ((par-indent 2))
921 (interpret-markup-list layout props
922 #@{\markuplines \justified-lines @{ \hspace #$par-indent $args @} #@}))
926 The version using just Scheme is more complex:
928 #(define-markup-list-command (paragraph layout props args) (markup-list?)
929 #:properties ((par-indent 2))
930 (interpret-markup-list layout props
931 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
935 Besides the usual @code{layout} and @code{props} arguments, the
936 @code{paragraph} markup list command takes a markup list argument, named
937 @code{args}. The predicate for markup lists is @code{markup-list?}.
939 First, the function gets the indent width, a property here named
940 @code{par-indent}, from the property list @code{props}. If the
941 property is not found, the default value is @code{2}. Then, a
942 list of justified lines is made using the built-in markup list command
943 @code{\justified-lines}, which is related to the
944 @code{make-justified-lines-markup-list} function. A
945 horizontal space is added at the beginning using @code{\hspace} (or the
946 @code{make-hspace-markup} function). Finally, the markup list is
947 interpreted using the @code{interpret-markup-list} function.
949 This new markup list command can be used as follows:
953 The art of music typography is called \italic @{(plate) engraving.@}
954 The term derives from the traditional process of music printing.
955 Just a few decades ago, sheet music was made by cutting and stamping
956 the music into a zinc or pewter plate in mirror image.
958 \override-lines #'(par-indent . 4) \paragraph @{
959 The plate would be inked, the depressions caused by the cutting
960 and stamping would hold ink. An image was formed by pressing paper
961 to the plate. The stamping and cutting was completely done by
967 @node Contexts for programmers
968 @section Contexts for programmers
971 * Context evaluation::
972 * Running a function on all layout objects::
975 @node Context evaluation
976 @subsection Context evaluation
978 @cindex calling code during interpreting
979 @funindex \applyContext
981 Contexts can be modified during interpretation with Scheme code. The
984 \applyContext @var{function}
987 @code{@var{function}} should be a Scheme function that takes a
988 single argument: the context in which the @code{\applyContext}
989 command is being called. The following code will print the
990 current bar number on the standard output during the compile:
995 (format #t "\nWe were called in barnumber ~a.\n"
996 (ly:context-property x 'currentBarNumber)))
1001 @node Running a function on all layout objects
1002 @subsection Running a function on all layout objects
1005 @cindex calling code on layout objects
1006 @funindex \applyOutput
1009 The most versatile way of tuning an object is @code{\applyOutput} which
1010 works by inserting an event into the specified context
1011 (@rinternals{ApplyOutputEvent}). Its syntax is
1013 \applyOutput @var{context} @var{proc}
1017 where @code{@var{proc}} is a Scheme function, taking three arguments.
1019 When interpreted, the function @code{@var{proc}} is called for
1020 every layout object found in the context @code{@var{context}} at
1021 the current time step, with the following arguments:
1023 @item the layout object itself,
1024 @item the context where the layout object was created, and
1025 @item the context where @code{\applyOutput} is processed.
1029 In addition, the cause of the layout object, i.e., the music
1030 expression or object that was responsible for creating it, is in the
1031 object property @code{cause}. For example, for a note head, this is a
1032 @rinternals{NoteHead} event, and for a stem object,
1033 this is a @rinternals{Stem} object.
1035 Here is a function to use for @code{\applyOutput}; it blanks
1036 note-heads on the center-line and next to it:
1038 @lilypond[quote,verbatim,ragged-right]
1039 #(define (blanker grob grob-origin context)
1040 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1041 (< (abs (ly:grob-property grob 'staff-position)) 2))
1042 (set! (ly:grob-property grob 'transparent) #t)))
1045 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1050 @node Callback functions
1051 @section Callback functions
1053 Properties (like @code{thickness}, @code{direction}, etc.) can be
1054 set at fixed values with @code{\override}, e.g.
1057 \override Stem #'thickness = #2.0
1060 Properties can also be set to a Scheme procedure,
1062 @lilypond[fragment,verbatim,quote,relative=2]
1063 \override Stem #'thickness = #(lambda (grob)
1064 (if (= UP (ly:grob-property grob 'direction))
1071 In this case, the procedure is executed as soon as the value of the
1072 property is requested during the formatting process.
1074 Most of the typesetting engine is driven by such callbacks.
1075 Properties that typically use callbacks include
1079 The printing routine, that constructs a drawing for the symbol
1081 The routine that sets the horizontal position
1083 The routine that computes the width of an object
1086 The procedure always takes a single argument, being the grob.
1088 If routines with multiple arguments must be called, the current grob
1089 can be inserted with a grob closure. Here is a setting from
1090 @code{AccidentalSuggestion},
1094 ,(ly:make-simple-closure
1096 ,(ly:make-simple-closure
1097 (list ly:self-alignment-interface::centered-on-x-parent))
1098 ,(ly:make-simple-closure
1099 (list ly:self-alignment-interface::x-aligned-on-self)))))
1103 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
1104 @code{ly:self-alignment-interface::centered-on-x-parent} are called
1105 with the grob as argument. The results are added with the @code{+}
1106 function. To ensure that this addition is properly executed, the whole
1107 thing is enclosed in @code{ly:make-simple-closure}.
1109 In fact, using a single procedure as property value is equivalent to
1112 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1116 The inner @code{ly:make-simple-closure} supplies the grob as argument
1117 to @var{proc}, the outer ensures that result of the function is
1118 returned, rather than the @code{simple-closure} object.
1120 From within a callback, the easiest method for evaluating a markup is
1121 to use grob-interpret-markup. For example:
1124 my-callback = #(lambda (grob)
1125 (grob-interpret-markup grob (markup "foo")))
1128 @node Inline Scheme code
1129 @section Inline Scheme code
1131 The main disadvantage of @code{\tweak} is its syntactical
1132 inflexibility. For example, the following produces a syntax error.
1135 F = \tweak #'font-size #-3 -\flageolet
1143 In other words, @code{\tweak} doesn't behave like an articulation
1144 regarding the syntax; in particular, it can't be attached with
1145 @code{^} and @code{_}.
1147 Using Scheme, this problem can be avoided. The route to the
1148 result is given in @ref{Adding articulation to notes (example)},
1149 especially how to use @code{\displayMusic} as a helping guide.
1152 F = #(let ((m (make-music 'ArticulationEvent
1153 'articulation-type "flageolet")))
1154 (set! (ly:music-property m 'tweaks)
1155 (acons 'font-size -3
1156 (ly:music-property m 'tweaks)))
1165 Here, the @code{tweaks} properties of the flageolet object
1166 @code{m} (created with @code{make-music}) are extracted with
1167 @code{ly:music-property}, a new key-value pair to change the
1168 font size is prepended to the property list with the
1169 @code{acons} Scheme function, and the result is finally
1170 written back with @code{set!}. The last element of the
1171 @code{let} block is the return value, @code{m} itself.
1175 @node Difficult tweaks
1176 @section Difficult tweaks
1178 There are a few classes of difficult adjustments.
1184 One type of difficult adjustment involves the appearance of
1185 spanner objects, such as slurs and ties. Usually, only one
1186 spanner object is created at a time, and it can be adjusted with
1187 the normal mechanism. However, occasionally a spanner crosses a
1188 line break. When this happens, the object is cloned. A separate
1189 object is created for every system in which the spanner appears.
1190 The new objects are clones of the original object and inherit all
1191 properties, including @code{\override}s.
1194 In other words, an @code{\override} always affects all pieces of a
1195 broken spanner. To change only one part of a spanner at a line break,
1196 it is necessary to hook into the formatting process. The
1197 @code{after-line-breaking} callback contains the Scheme procedure that
1198 is called after the line breaks have been determined and layout
1199 objects have been split over different systems.
1201 In the following example, we define a procedure
1202 @code{my-callback}. This procedure
1206 determines if the spanner has been split across line breaks
1208 if yes, retrieves all the split objects
1210 checks if this grob is the last of the split objects
1212 if yes, it sets @code{extra-offset}.
1215 This procedure is installed into @rinternals{Tie}, so the last part
1216 of the broken tie is repositioned.
1218 @lilypond[quote,verbatim,ragged-right]
1219 #(define (my-callback grob)
1221 ;; have we been split?
1222 (orig (ly:grob-original grob))
1224 ;; if yes, get the split pieces (our siblings)
1225 (siblings (if (ly:grob? orig)
1226 (ly:spanner-broken-into orig)
1229 (if (and (>= (length siblings) 2)
1230 (eq? (car (last-pair siblings)) grob))
1231 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1234 \override Tie #'after-line-breaking =
1242 When applying this trick, the new @code{after-line-breaking} callback
1243 should also call the old one, if such a default exists. For example,
1244 if using this with @code{Hairpin}, @code{ly:spanner::kill-zero-spanned-time}
1245 should also be called.
1249 Some objects cannot be changed with @code{\override} for
1250 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1251 and @code{PaperColumn}. They can be changed with the
1252 @code{\overrideProperty} function, which works similar to @code{\once
1253 \override}, but uses a different syntax.
1257 #"Score.NonMusicalPaperColumn" % Grob name
1258 #'line-break-system-details % Property name
1259 #'((next-padding . 20)) % Value
1262 Note, however, that @code{\override}, applied to
1263 @code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
1264 expected within @code{\context} blocks.
1268 @node LilyPond Scheme interfaces
1269 @chapter LilyPond Scheme interfaces
1271 This chapter covers the various tools provided by LilyPond to help
1272 Scheme programmers get information into and out of the music streams.
1274 TODO -- figure out what goes in here and how to organize it