version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.38"
+@c \version "2.11.61"
@node Interfaces for programmers
@chapter Interfaces for programmers
* Building complicated functions::
* Markup programmer interface::
* Contexts for programmers::
-* Scheme procedures as properties::
+* Scheme procedures as properties::
+* Using Scheme code instead of \tweak::
+* Difficult tweaks::
@end menu
@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
{ \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
@itemize
@item
music name: Each music expression has a name. For example, a note
-leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
-a @internalsref{SimultaneousMusic}. A list of all expressions
+leads to a @rinternals{NoteEvent}, and @code{\simultaneous} leads to
+a @rinternals{SimultaneousMusic}. A list of all expressions
available is in the Internals Reference manual, under
-@internalsref{Music expressions}.
+@rinternals{Music expressions}.
@item
@q{type} or interface: Each music name has several @q{types} or
@code{note-event}, a @code{rhythmic-event}, and a
@code{melodic-event}. All classes of music are listed in the
Internals Reference, under
-@internalsref{Music classes}.
+@rinternals{Music classes}.
@item
C++ object: Each music object is represented by an object of the C++
@end itemize
The actual information of a music expression is stored in properties.
-For example, a @internalsref{NoteEvent} has @code{pitch} and
+For example, a @rinternals{NoteEvent} has @code{pitch} and
@code{duration} properties that store the pitch and duration of that
note. A list of all properties available is in the internals manual,
-under @internalsref{Music properties}.
+under @rinternals{Music properties}.
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,
-@internalsref{SequentialMusic} has its children in @code{elements},
-and @internalsref{GraceMusic} has its single argument in
+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}
-property of @internalsref{RepeatedMusic}, and the alternatives in
+property of @rinternals{RepeatedMusic}, and the alternatives in
@code{elements}.
to create complicated music functions.
@menu
-* Displaying music expressions::
-* Music properties::
-* Doubling a note with slurs (example)::
-* Adding articulation to notes (example)::
+* Displaying music expressions::
+* Music properties::
+* Doubling a note with slurs (example)::
+* Adding articulation to notes (example)::
@end menu
@cindex internal storage
@funindex \displayMusic
-@funindex \displayLilyMusic
When writing a music function it is often instructive to inspect how
a music expression is stored internally. This can be done with the
The note pitch can be changed by setting this 'pitch property,
+@funindex \displayLilyMusic
+
@example
#(set! (ly:music-property (first (ly:music-property someNote 'elements))
'pitch)
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
be used to set text in small caps. See
@ref{Text markup commands}, for details.
+@knownissues
+
+Currently, 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{list}
+@itemx @var{markup}
+@itemx @var{markup markup}
+@itemx @var{scm}
+@itemx @var{scm markup}
+@itemx @var{scm scm}
+@itemx @var{scm scm markup}
+@itemx @var{scm scm markup markup}
+@itemx @var{scm markup markup}
+@itemx @var{scm scm scm}
+@end table
+
+@noindent
+In the above table, @var{scm} represents native Scheme data types like
+@q{number} or @q{string}.
+
+As an example, it is not possible to use a markup command @code{foo} with
+four arguments defined as
+
+@example
+#(define-markup-command (foo layout props
+ num1 str1 num2 str2)
+ (number? string? number? string?)
+ ...)
+@end example
+
+@noindent
+If you apply it as, say,
+
+@example
+\markup \foo #1 #"bar" #2 #"baz"
+@end example
+
+@cindex Scheme signature
+@cindex signature, Scheme
+@noindent
+@command{lilypond} complains that it cannot parse @code{foo} due to its
+unknown Scheme signature.
+
@node New markup list command definition
@subsection New markup list command definition
Markup list commands are defined with the
@code{define-markup-list-command} Scheme macro, which is similar to the
@code{define-markup-command} macro described in
-@ref{New markup command definition}, except that where the later returns
+@ref{New markup command definition}, except that where the latter returns
a single stencil, the former returns a list stencils.
In the following example, a @code{\paragraph} markup list command is
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
-@internalsref{NoteHead} event, and for a @internalsref{Stem} object,
-this is a @internalsref{NoteHead} object.
+@rinternals{NoteHead} event, and for a @rinternals{Stem} object,
+this is a @rinternals{NoteHead} object.
Here is a function to use for @code{\applyOutput}; it blanks
note-heads on the center-line:
The inner @code{ly:make-simple-closure} supplies the grob as argument
to @var{proc}, the outer ensures that result of the function is
returned, rather than the @code{simple-closure} object.
+
+
+@node Using Scheme code instead of \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.
+
+@example
+F = \tweak #'font-size #-3 -\flageolet
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@end example
+
+@noindent
+With other words, @code{\tweak} doesn't behave like an articulation
+regarding the syntax; in particular, it can't be attached with
+@code{^} and @code{_}.
+
+Using Scheme, this problem can be circumvented. The route to the
+result is given in @ref{Adding articulation to notes (example)},
+especially how to use @code{\displayMusic} as a helping guide.
+
+@example
+F = #(let ((m (make-music 'ArticulationEvent
+ 'articulation-type "flageolet")))
+ (set! (ly:music-property m 'tweaks)
+ (acons 'font-size -3
+ (ly:music-property m 'tweaks)))
+ m)
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@end example
+
+@noindent
+Here, the @code{tweaks} properties of the flageolet object
+@code{m} (created with @code{make-music}) are extracted with
+@code{ly:music-property}, a new key-value pair to change the
+font size is prepended to the property list with the
+@code{acons} Scheme function, and the result is finally
+written back with @code{set!}. The last element of the
+@code{let} block is the return value, @code{m} itself.
+
+
+
+@node Difficult tweaks
+@section Difficult tweaks
+
+There are a few classes of difficult adjustments.
+
+@itemize
+
+
+@item
+One type of difficult adjustment is the appearance of spanner objects,
+such as slur and tie. Initially, only one of these objects is created,
+and they can be adjusted with the normal mechanism. However, in some
+cases the spanners cross line breaks. If this happens, these objects
+are cloned. A separate object is created for every system that it is
+in. These are clones of the original object and inherit all
+properties, including @code{\override}s.
+
+
+In other words, an @code{\override} always affects all pieces of a
+broken spanner. To change only one part of a spanner at a line break,
+it is necessary to hook into the formatting process. The
+@code{after-line-breaking} callback contains the Scheme procedure that
+is called after the line breaks have been determined, and layout
+objects have been split over different systems.
+
+In the following example, we define a procedure
+@code{my-callback}. This procedure
+
+@itemize
+@item
+determines if we have been split across line breaks
+@item
+if yes, retrieves all the split objects
+@item
+checks if we are the last of the split objects
+@item
+if yes, it sets @code{extra-offset}.
+@end itemize
+
+This procedure is installed into @rinternals{Tie}, so the last part
+of the broken tie is translated up.
+
+@lilypond[quote,verbatim,ragged-right]
+#(define (my-callback 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 (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
+}
+@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.
+
+
+@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
+\override}, but uses a different syntax.
+
+@example
+\overrideProperty
+#"Score.NonMusicalPaperColumn" % Grob name
+#'line-break-system-details % Property name
+#'((next-padding . 20)) % Value
+@end example
+
+Note, however, that @code{\override}, applied to
+@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
+expected within @code{\context} blocks.
+
+@end itemize
+
+
+
+
+
projects / lilypond.git / blobdiff