Thanks Carl, Johannes, and David for working on this overview.
On Apr 23, 2015, at 4:25 AM, Johannes Rohrer <address@hidden> wrote:
Translators selectively (based on assigned Event Classes) "accept"
Events from the stream that were sorted into "their" context and process
them. Typically, they will produce "output objects" (for Engravers:
layout objects, aka Grobs; for Performers: Audio_items) and "announce"
these. Other Translators can "acknowledge" certain types of announced
objects to process them further.
Thanks especially for this insight. After a little digging into the source code I now
understand the difference between “listeners” and “acknowledgers” in a scheme engraver
created with the "make-engraver" macro.
In short, “listeners” respond to particular stream events:
http://lilypond.org/doc/v2.18/Documentation/internals/music-classes
while “acknowledgers” respond to particular grobs that have been “announced” by
other engravers (that created the grobs based on the stream events that they
“listened” to). This process of acknowledging grobs happens through grob
interfaces:
http://lilypond.org/doc/v2.18/Documentation/internals/graphical-object-interfaces
Basically like this:
[stream event] —> [engraver A with listener] —> [grob]
[grob] —> [engraver B with acknowledger] —> […]
but engravers can have both listeners and acknowledgers, and more than one of
each. Here’s an example:
%%%%%%%%%%%%%%%%%%
\version "2.18.2"
#(define Some_custom_engraver
(make-engraver
(listeners
((key-change-event engraver event)
(display event)(newline)
;; do something with key-change-event events
)
((note-event engraver event)
(display event)(newline)
;; do something with note-event events
))
(acknowledgers
((key-signature-interface engraver grob source-engraver)
(display grob)(newline)
;; do something with key-signature grobs
)
((note-head-interface engraver grob source-engraver)
(display grob)(newline)
;; do something with note-head grobs
))))
\new Staff \with {
\consists \Some_custom_engraver
}{
\key c \major
c'1
}
%%%%%%%%%%%%%%%%%%
As far as I can tell the order in which engravers are “consisted” in their
given context determines the order in which they receive the incoming events
and grobs.
It’s probably *very* rare that a user would ever need to create an engraver and
need to know about listeners and acknowledgers.
For anyone wanting to go further there’s more that I don’t understand
(initialize, start-translation-timestep, process-music, etc.), to quote from
the doc string of the make-engraver macro at the bottom of scm/output-lib.scm:
Symbols mapping to a function would be @code{initialize},
@code{start-translation-timestep}, @code{process-music},
@code{process-acknowledged}, @code{stop-translation-timestep}, and
@code{finalize}. Symbols mapping to another alist specified in the
same manner are @code{listeners} with the subordinate symbols being
event classes, and @code{acknowledgers} and @code{end-acknowledgers}
with the subordinate symbols being interfaces.”
Let me know if I’ve misrepresented anything.
Thanks again,
-Paul
_______________________________________________
lilypond-user mailing list
address@hidden
https://lists.gnu.org/mailman/listinfo/lilypond-user