[ << Programming work ][Top][Contents][ Release work >> ]
[ < Listening to music events ][ Up : Engraver tutorial ][]

10.11.4 Acknowledging grobs

Some engravers also need information from grobs as they are created and as they terminate. The mechanism and methods to obtain this information are set up by the macros:

where grob_interface is an interface supported by the grob(s) which should be acknowledged. For example, the following code would declare acknowledgers for a NoteHead grob (via the note-head-interface) and any grobs which support the side-position-interface: 

DECLARE_ACKNOWLEDGER (note_head)
DECLARE_ACKNOWLEDGER (side_position)

The DECLARE_END_ACKNOWLEDGER () macro sets up a spanner-specific acknowledger which will be called whenever a spanner ends.

Following declaration of an acknowledger, the method is coded as follows: 

void
Engraver_name::acknowledge_interface_name (Grob_info info)
{
  ...body of acknowledger method...
}

Acknowledge functions are called in the order engravers are \consist-ed (the only exception is if you set must-be-last to #t).

There will always be a call to process-acknowledged () whenever grobs have been created, and reading stuff from grobs should be delayed until then since other acknowledgers might write stuff into a grob even after your acknowledger has been called. So the basic workflow is to use the various acknowledgers to record the grobs you are interested in and write stuff into them (or do read/write stuff that more or less is accumulative and/or really unrelated to other engravers), and then use the process-acknowledged () hook for processing (including reading) the grobs you had recorded.

You can create new grobs in process-acknowledged (). That will lead to a new cycle of acknowledger () calls followed by a new cycle of process-acknowledged () calls.

Only when all those cycles are over is stop-translator-timestep () called, and then creating grobs is no longer an option. You can still ‘process’ parts of the grob there (if that means just reading out properties and possibly setting context properties based on them) but stop-translation-timestep () is a cleanup hook, and other engravers might have already cleaned up stuff you might have wanted to use. Creating grobs in there is not possible since engravers and other code may no longer be in a state where they could process them, possibly causing a crash.

[ << Programming work ][Top][Contents][ Release work >> ]
[ < Listening to music events ][ Up : Engraver tutorial ][]

<< Back to Documentation Index

LilyPond — Contributor’s Guide v2.24.4 (stable-branch).