Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.13.36"
@node Interfaces for programmers
@chapter Interfaces for programmers
@ruser{Predefined type predicates}.
Installed Files:
-@file{lily/music-scheme.cc},
-@file{scm/c++.scm},
-@file{scm/lily.scm}.
+@file{lily/@/music@/-scheme@/.cc},
+@file{scm/@/c++@/.scm},
+@file{scm/@/lily@/.scm}.
@node Simple substitution functions
and LilyPond code in the music expression to be returned.
Some @code{\override} commands require an argument consisting of
-a pair of numbers (called a @code{cons cell} in Scheme).
+a pair of numbers (called a @emph{cons cell} in Scheme).
The pair can be directly passed into the music function,
using a @code{pair?} variable:
The arguments are
-@table @var
-@item command-name
+@table @code
+@item @var{command-name}
the markup command name
@item layout
the @q{layout} definition.
@item props
a list of associative lists, containing all active properties.
-@item argi
+@item @var{argi}
@var{i}th command argument
-@item argi-type?
+@item @var{argi-type?}
a type predicate for the i@var{th} argument
@end table
-If the command uses properties from the @var{props} arguments, the
-@code{#:properties} keyword can be used, to specify which properties are
-used, and their default values.
-
-@knownissues
-There are restrictions on the possible arguments to a markup command.
+If the command uses properties from the @code{props} arguments,
+the @code{#:properties} keyword can be used to specify which
+properties are used along with their default values.
-Arguments are distingued according to their type:
+Arguments are distinguished according to their type:
@itemize
@item a markup, corresponding to type predicate @code{markup?};
-@item a list of markup, corresponding to type predicate
+@item a list of markups, corresponding to type predicate
@code{markup-list?};
@item any other scheme object, corresponding to type predicates such as
@code{list?}, @code{number?}, @code{boolean?}, etc.
@end itemize
-The available combinations of arguments (after the standard @var{layout}
-and @var{props} arguments) to a markup command defined with
-@code{define-markup-command} are limited as follows.
-
-@table @asis
-@item (no argument)
-@itemx @var{markup-list}
-@itemx @var{markup}
-@itemx @var{markup markup}
-@itemx @var{scheme}
-@itemx @var{scheme markup}
-@itemx @var{scheme scheme}
-@itemx @var{scheme scheme markup}
-@itemx @var{scheme scheme markup markup}
-@itemx @var{scheme markup markup}
-@itemx @var{scheme scheme scheme}
-@end table
-
-@noindent
-This means that it is not possible to define with e.g. three scheme
-arguments and a markup arguments, like:
-
-@example
-#(define-markup-command (foo layout props
- num1 num2 a-list a-markup)
- (number? number? list? markup?)
- ...)
-@end example
-
-@noindent
-If you apply it as, say,
-
-@example
-\markup \foo #1 #2 #'(bar baz) Blah
-@end example
+There is no limitation on the order of arguments (after the
+standard @code{layout} and @code{props} arguments). However,
+markup functions taking a markup as their last argument are
+somewhat special as you can apply them to a markup list, and the
+result is a markup list where the markup function (with the
+specified leading arguments) has been applied to every element of
+the original markup list.
-@cindex Scheme signature
-@cindex signature, Scheme
-@noindent
-@command{lilypond} complains that it cannot parse @code{foo} due to its
-unknown Scheme signature.
+Since replicating the leading arguments for applying a markup
+function to a markup list is cheap mostly for Scheme arguments,
+you avoid performance pitfalls by just using Scheme arguments for
+the leading arguments of markup functions that take a markup as
+their last argument.
@node On properties
@unnumberedsubsubsec On properties
here, the @code{box-padding} values are hard coded, and cannot be
changed by the user. Also, it would be better to distinguish the
padding between the two boxes, from the padding between the inner box
-and the text. So we will introduce a new property,
-@code{inter-box-padding}, for the padding between the two boxes. The
+and the text. So we will introduce a new property,
+@code{inter-box-padding}, for the padding between the two boxes. The
@code{box-padding} will be used for the inner padding. The new code is
now as follows:
\applyContext @var{function}
@end example
-@var{function} should be a Scheme function that takes a single
-argument: the context in which the @code{\applyContext} command is
-being called. The following code will print the current bar
-number on the standard output during the compile:
+@code{@var{function}} should be a Scheme function that takes a
+single argument: the context in which the @code{\applyContext}
+command is being called. The following code will print the
+current bar number on the standard output during the compile:
@example
\applyContext
@funindex \applyOutput
-The most versatile way of tuning an object is @code{\applyOutput}. Its
-syntax is
+The most versatile way of tuning an object is @code{\applyOutput} which
+works by inserting an event into the specified context
+(@rinternals{ApplyOutputEvent}). Its syntax is
@example
\applyOutput @var{context} @var{proc}
@end example
@noindent
-where @var{proc} is a Scheme function, taking three arguments.
+where @code{@var{proc}} is a Scheme function, taking three arguments.
-When interpreted, the function @var{proc} is called for every layout
-object found in the context @var{context}, with the following
-arguments:
+When interpreted, the function @code{@var{proc}} is called for
+every layout object found in the context @code{@var{context}} at
+the current time step, with the following arguments:
@itemize
@item the layout object itself,
@item the context where the layout object was created, and
In addition, the cause of the layout object, i.e., the music
expression or object that was responsible for creating it, is in the
object property @code{cause}. For example, for a note head, this is a
-@rinternals{NoteHead} event, and for a @rinternals{Stem} object,
-this is a @rinternals{NoteHead} object.
+@rinternals{NoteHead} event, and for a stem object,
+this is a @rinternals{Stem} object.
Here is a function to use for @code{\applyOutput}; it blanks
-note-heads on the center-line:
+note-heads on the center-line and next to it:
@lilypond[quote,verbatim,ragged-right]
#(define (blanker grob grob-origin context)
(if (and (memq 'note-head-interface (ly:grob-interfaces grob))
- (eq? (ly:grob-property grob 'staff-position) 0))
+ (< (abs (ly:grob-property grob 'staff-position)) 2))
(set! (ly:grob-property grob 'transparent) #t)))
\relative c' {
- e4 g8 \applyOutput #'Voice #blanker b d2
+ a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
}
@end lilypond
@lilypond[quote,verbatim,ragged-right]
#(define (my-callback grob)
- (let* (
- ; have we been split?
- (orig (ly:grob-original grob))
+ (let* (
+ ;; have we been split?
+ (orig (ly:grob-original grob))
- ; if yes, get the split pieces (our siblings)
- (siblings (if (ly:grob? orig)
- (ly:spanner-broken-into orig) '() )))
+ ;; if yes, get the split pieces (our siblings)
+ (siblings (if (ly:grob? orig)
+ (ly:spanner-broken-into orig)
+ '())))
- (if (and (>= (length siblings) 2)
- (eq? (car (last-pair siblings)) grob))
- (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
+ (if (and (>= (length siblings) 2)
+ (eq? (car (last-pair siblings)) grob))
+ (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
\relative c'' {
\override Tie #'after-line-breaking =
#my-callback
- c1 ~ \break c2 ~ c
+ c1 ~ \break
+ c2 ~ c
}
@end lilypond
@noindent
When applying this trick, the new @code{after-line-breaking} callback
-should also call the old one @code{after-line-breaking}, if there is
-one. For example, if using this with @code{Hairpin},
-@code{ly:hairpin::after-line-breaking} should also be called.
+should also call the old one, if such a default exists. For example,
+if using this with @code{Hairpin}, @code{ly:spanner::kill-zero-spanned-time}
+should also be called.
-@item Some objects cannot be changed with @code{\override} for
+@item
+Some objects cannot be changed with @code{\override} for
technical reasons. Examples of those are @code{NonMusicalPaperColumn}
and @code{PaperColumn}. They can be changed with the
@code{\overrideProperty} function, which works similar to @code{\once
projects / lilypond.git / blobdiff