version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.51"
+@c \version "2.12.0"
@node Interfaces for programmers
@chapter Interfaces for programmers
@rlearning{Scheme tutorial}.
@menu
-* Music functions::
-* Programmer interfaces::
-* Building complicated functions::
-* Markup programmer interface::
-* Contexts for programmers::
-* Scheme procedures as properties::
-* TODO moved into scheme::
+* Music functions::
+* Programmer interfaces::
+* Building complicated functions::
+* Markup programmer interface::
+* Contexts for programmers::
+* Scheme procedures as properties::
+* Using Scheme code instead of \tweak::
+* Difficult tweaks::
@end menu
This section discusses how to create music functions within LilyPond.
@menu
-* Overview of music functions::
-* Simple substitution functions::
-* Paired substitution functions::
-* Mathematics in functions::
-* Void functions::
-* Functions without arguments::
-* Overview of available music functions::
+* Overview of music functions::
+* Simple substitution functions::
+* Paired substitution functions::
+* Mathematics in functions::
+* Void functions::
+* Functions without arguments::
+* Overview of available music functions::
@end menu
@node Overview of music functions
@example
function =
-#(define-music-function (parser location @var{var1} @var{var2}... )
- (@var{var1-type?} @var{var2-type?}...)
+#(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... )
+ (@var{var1-type?} @var{var2-type?}...@var{vari-type?}...)
#@{
@emph{...music...}
#@})
where
@multitable @columnfractions .33 .66
-@item @var{argi} @tab @var{i}th variable
-@item @var{argi-type?} @tab type of variable
+@item @var{vari} @tab @var{i}th variable
+@item @var{vari-type?} @tab type of @var{i}th variable
@item @var{...music...} @tab normal LilyPond input, using
- variables as @code{#$var1}.
+ variables as @code{#$var1}, etc.
@end multitable
There following input types may be used as variables
variable types.
@multitable @columnfractions .33 .66
-@headitem Input type @tab @var{argi-type?} notation
+@headitem Input type @tab @var{vari-type?} notation
@item Integer @tab @code{integer?}
@item Float (decimal number) @tab @code{number?}
@item Text string @tab @code{string?}
@item A pair of variables @tab @code{pair?}
@end multitable
-The @code{parser} and @code{location} argument are mandatory,
+The @code{parser} and @code{location} arguments are mandatory,
and are used in some advanced situations. The @code{parser}
-argument is used to access to the value of another LilyPond
+argument is used to gain access to the value of another LilyPond
variable. The @code{location} argument
is used to set the @q{origin} of the music expression that is built
by the music function, so that in case of a syntax error LilyPond
Multiple variables may be used,
@lilypond[quote,verbatim,ragged-right]
-tempoMark = #(define-music-function (parser location padding marktext)
- (number? string?)
+tempoPadded = #(define-music-function (parser location padding tempotext)
+ (number? string?)
#{
- \once \override Score . RehearsalMark #'padding = $padding
- \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
- \mark \markup { \bold $marktext }
+ \once \override Score.MetronomeMark #'padding = $padding
+ \tempo \markup { \bold $tempotext }
#})
\relative c'' {
-c2 e
-\tempoMark #3.0 #"Allegro"
-g c
+ \tempo \markup { "Low tempo" }
+ c4 d e f g1
+ \tempoPadded #4.0 #"High tempo"
+ g4 f e d c1
}
@end lilypond
and Scheme.
@menu
-* Input variables and Scheme::
-* Internal music representation::
+* Input variables and Scheme::
+* Internal music representation::
@end menu
{ \twice }
@end lilypond
-Due to parser lookahead
+@c Due to parser lookahead
In this example, the assignment happens after parser has verified that
nothing interesting happens after @code{traLaLa = @{ ... @}}. Without
value is interpreted as if it were entered in LilyPond syntax.
Instead of defining @code{\twice}, the example above could also have
been written as
+
@example
-@dots{}
+...
@{ #(ly:export (make-sequential-music (list newLa))) @}
@end example
A compound music expression is a music object that contains other
music objects in its properties. A list of objects can be stored in
the @code{elements} property of a music object, or a single @q{child}
-music object in the @code{element} object. For example,
+music object in the @code{element} property. For example,
@rinternals{SequentialMusic} has its children in @code{elements},
and @rinternals{GraceMusic} has its single argument in
@code{element}. The body of a repeat is stored in the @code{element}
@subsection Displaying music expressions
@cindex internal storage
+@cindex displaying music expressions
+@cindex internal representation, displaying
+@cindex displayMusic
@funindex \displayMusic
When writing a music function it is often instructive to inspect how
Stencil object given a number of arguments.
@menu
-* Markup construction in Scheme::
-* How markups work internally::
-* New markup command definition::
-* New markup list command definition::
+* Markup construction in Scheme::
+* How markups work internally::
+* New markup command definition::
+* New markup list command definition::
@end menu
providing a LilyPond-like syntax. For example,
@example
(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
- #:bigger #:line ("foo" "bar" "baz")))
+ #:larger #:line ("foo" "bar" "baz")))
@end example
@noindent
is equivalent to:
@example
\markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
- \bigger \line @{ foo bar baz @} @}
+ \larger \line @{ foo bar baz @} @}
@end example
@noindent
@code{(markup markup1 markup2 ... )}
@item @code{\command} @tab @code{#:command}
@item @code{\variable} @tab @code{variable}
-@item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
+@item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
@item @code{string} @tab @code{"string"}
@item @code{#scheme-arg} @tab @code{scheme-arg}
@end multitable
@example
#(define-markup-list-command (paragraph layout props args) (markup-list?)
(let ((indent (chain-assoc-get 'par-indent props 2)))
- (interpret-markup-list layout props
+ (interpret-markup-list layout props
(make-justified-lines-markup-list (cons (make-hspace-markup indent)
args)))))
@end example
@section Contexts for programmers
@menu
-* Context evaluation::
-* Running a function on all layout objects::
+* Context evaluation::
+* Running a function on all layout objects::
@end menu
@node Context evaluation
Here is a function to use for @code{\applyOutput}; it blanks
note-heads on the center-line:
-@example
-(define (blanker grob grob-origin context)
- (if (and (memq (ly:grob-property grob 'interfaces)
- note-head-interface)
- (eq? (ly:grob-property grob 'staff-position) 0))
- (set! (ly:grob-property grob 'transparent) #t)))
-@end example
+@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))
+ (set! (ly:grob-property grob 'transparent) #t)))
+
+\relative {
+ e4 g8 \applyOutput #'Voice #blanker b d2
+}
+@end lilypond
@node Scheme procedures as properties
property is requested during the formatting process.
Most of the typesetting engine is driven by such callbacks.
-Properties that typically use callbacks include
+Properties that typically use callbacks include
@table @code
@item stencil
returned, rather than the @code{simple-closure} object.
-@node TODO moved into scheme
-@section TODO moved into scheme
-
-@menu
-* Using Scheme code instead of \tweak::
-* Difficult tweaks::
-@end menu
-
@node Using Scheme code instead of \tweak
-@subsection Using Scheme code instead of @code{\tweak}
+@section Using Scheme code instead of @code{\tweak}
The main disadvantage of @code{\tweak} is its syntactical
inflexibility. For example, the following produces a syntax error.
(acons 'font-size -3
(ly:music-property m 'tweaks)))
m)
-
+
\relative c'' @{
c4^\F c4_\F
@}
@node Difficult tweaks
-@subsection Difficult tweaks
+@section Difficult tweaks
There are a few classes of difficult adjustments.
@end example
Note, however, that @code{\override}, applied to
-@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
+@code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
expected within @code{\context} blocks.
@end itemize
projects / lilypond.git / blobdiff