2 ligature-engraver.cc -- implement Ligature_engraver
4 source file of the GNU LilyPond music typesetter
6 (c) 2002--2004 Juergen Reuter <reuter@ipd.uka.de>
10 #include "ligature-engraver.hh"
13 #include "score-engraver.hh"
14 #include "note-head.hh"
20 * This abstract class provides the general framework for ligatures of
21 * any kind. It cares for handling start/stop ligatures requests and
22 * collecting all noteheads inbetween, but delegates creation of a
23 * ligature spanner for each start/stop pair and typesetting of the
24 * ligature spanner to a concrete subclass.
26 * A concrete ligature engraver must subclass this class and provide
27 * functions create_ligature_spanner () and typeset_ligature
28 * (Spanner *, Array<Grob_info>). Subclasses of this class basically
29 * fall into two categories.
31 * The first category consists of engravers that engrave ligatures in
32 * a way that really deserves the name ligature. That is, they
33 * produce a single connected graphical object of fixed width,
34 * consisting of noteheads and other primitives. Space may be
35 * inserted only after each ligature, if necessary, but in no case
36 * between the primitives of the ligature. Accidentals have to be put
37 * to the left of the ligature, and not to the left of individual
38 * noteheads. Class Coherent_ligature_engraver is the common
39 * superclass for all of these engravers.
41 * The second category is for engravers that are relaxed in the sense
42 * that they do not require to produce a single connected graphical
43 * object. For example, in contemporary editions, ligatures are often
44 * marked, but otherwise use contemporary notation and spacing. In
45 * this category, there is currently only a single class,
46 * Ligature_bracket_engraver, which marks each ligature with a
47 * horizontal sqare bracket, but otherwise leaves the appearance
52 * TODO: lyrics/melisma/syllables: there should be at most one
53 * syllable of lyrics per ligature (i.e. for the lyrics context, a
54 * ligature should count as a single note, regardless of how many
55 * heads the ligature consists of).
57 * TODO: currently, you have to add/remove the proper
58 * Ligature_engraver (Ligature_bracket_engraver,
59 * Mensural_ligature_engraver) to the proper translator
60 * (e.g. VoiceContext) to choose between various representations.
61 * Since adding/removing an engraver to a translator is a global
62 * action in the layout block, you can not mix various representations
63 * _within_ the same score. Hence, for selecting a representation,
64 * one would rather like to have a property that can be set e.g. for
65 * several staves individually. However, it seems that this approach
66 * would require to have a single, complicated Ligature_engraver that
67 * consists of all the code... This needs further thoughts.
69 Ligature_engraver::Ligature_engraver ()
72 finished_ligature_ = 0;
73 reqs_drul_[LEFT] = reqs_drul_[RIGHT] = 0;
76 brew_ligature_primitive_proc = SCM_EOL;
80 Ligature_engraver::try_music (Music *m)
82 if (m->is_mus_type ("ligature-event"))
84 Direction d = to_dir (m->get_property ("span-direction"));
92 Ligature_engraver::create_ligature_spanner ()
94 programming_error ("Ligature_engraver::create_ligature_spanner (): "
95 "this is an abstract method that should not be called, "
96 "but overridden by a subclass");
101 * This method should do something that comes close to the following
104 * \property Voice.NoteHead \override #'print-function =
105 * < value of #'ligature-primitive-callback of Voice.NoteHead >
107 * TODO: What we are doing here on the c++ level, should actually be
108 * performed on the SCM level. However, I do not know how to teach
109 * lilypond to apply an \override and \revert on #'print-function,
110 * whenever lily encounters a \[ and \] in an .ly file, respectively.
111 * Also encounter, that lily should not crash if a user erronously
115 Ligature_engraver::override_stencil_callback ()
117 SCM target_callback = ly_symbol2scm ("print-function");
118 SCM source_callback = ly_symbol2scm ("ligature-primitive-callback");
119 SCM noteHeadProperties = updated_grob_properties (context (), ly_symbol2scm ("NoteHead"));
120 SCM value = scm_cdr (scm_sloppy_assq (source_callback, noteHeadProperties));
121 execute_pushpop_property (context (), ly_symbol2scm ("NoteHead"),
122 target_callback, value);
126 * This method should do something that comes close to the following
129 * \property Voice.NoteHead \revert #'print-function
131 * TODO: What we are doing here on the c++ level, should actually be
132 * performed on the SCM level. However, I do not know how to teach
133 * lilypond to apply an \override and \revert on #'print-function,
134 * whenever lily encounters a \[ and \] in an .ly file, respectively.
135 * Also encounter, that lily should not crash if a user erronously
139 Ligature_engraver::revert_stencil_callback ()
141 SCM symbol = ly_symbol2scm ("NoteHead");
142 SCM key = ly_symbol2scm ("print-function");
143 execute_pushpop_property (context (), symbol, key, SCM_UNDEFINED);
147 Ligature_engraver::process_music ()
149 if (reqs_drul_[STOP])
153 reqs_drul_[STOP]->origin ()->warning (_ ("can't find start of ligature"));
159 reqs_drul_[STOP]->origin ()->warning (_ ("no right bound"));
163 ligature_->set_bound (RIGHT, last_bound_);
167 finished_primitives_ = primitives_;
168 finished_ligature_ = ligature_;
169 primitives_.clear ();
171 revert_stencil_callback ();
173 last_bound_ = unsmob_grob (get_property ("currentMusicalColumn"));
177 // TODO: maybe forbid breaks only if not transcribing
178 get_score_engraver ()->forbid_breaks ();
181 if (reqs_drul_[START])
185 reqs_drul_[START]->origin ()->warning (_ ("already have a ligature"));
189 prev_start_req_ = reqs_drul_[START];
190 ligature_ = create_ligature_spanner ();
191 brew_ligature_primitive_proc =
192 ligature_->get_property ("ligature-primitive-callback");
193 if (brew_ligature_primitive_proc == SCM_EOL)
195 warning ("Ligature_engraver: ligature-primitive-callback undefined");
198 Grob *bound = unsmob_grob (get_property ("currentMusicalColumn"));
201 reqs_drul_[START]->origin ()->warning (_ ("no left bound"));
205 ligature_->set_bound (LEFT, bound);
208 ligature_start_mom_ = now_mom ();
210 // TODO: dump cause into make_item/spanner.
211 // announce_grob (ligature_, reqs_drul_[START]->self_scm ());
212 override_stencil_callback ();
217 Ligature_engraver::typeset_ligature (Spanner *, Array<Grob_info>)
219 programming_error ("Ligature_engraver::typeset_ligature (): "
220 "this is an abstract method that should not be called, "
221 "but overridden by a subclass");
225 Ligature_engraver::stop_translation_timestep ()
227 if (finished_ligature_)
229 if (!finished_primitives_.size ())
231 finished_ligature_->programming_error ("Ligature_engraver::stop_translation_timestep (): "
232 "junking empty ligature");
236 typeset_ligature (finished_ligature_, finished_primitives_);
237 finished_primitives_.clear ();
239 finished_ligature_ = 0;
242 reqs_drul_[START] = 0;
243 reqs_drul_[STOP] = 0;
247 Ligature_engraver::finalize ()
249 if (finished_ligature_)
251 typeset_ligature (finished_ligature_, finished_primitives_);
252 finished_primitives_.clear ();
253 finished_ligature_ = 0;
257 prev_start_req_->origin ()->warning (_ ("unterminated ligature"));
258 ligature_->suicide ();
263 Ligature_engraver::current_ligature ()
269 Ligature_engraver::acknowledge_grob (Grob_info info)
273 if (Note_head::has_interface (info.grob_))
275 primitives_.push (info);
276 info.grob_->set_property ("print-function",
277 brew_ligature_primitive_proc);
279 if (Rest::has_interface (info.grob_))
281 info.music_cause ()->origin ()->warning (_ ("ignoring rest: ligature may not contain rest"));
282 prev_start_req_->origin ()->warning (_ ("ligature was started here"));
283 // TODO: maybe better should stop ligature here rather than
284 // ignoring the rest?
289 ADD_TRANSLATOR (Ligature_engraver,
290 /* descr */ "Abstract class; a concrete subclass handles Ligature_events by engraving Ligatures in a concrete style.",
292 /* accepts */ "ligature-event",
293 /* acks */ "note-head-interface rest-interface",