1 % DO NOT EDIT this file manually; it is automatically
2 % generated from Documentation/snippets/new
3 % Make any changes in Documentation/snippets/new/
4 % and then run scripts/auxiliar/makelsr.py
6 % This file is in the public domain.
7 %% Note: this file works from version 2.15.31
12 lsrtags = "contexts-and-engravers"
15 texidoc = "This example demonstrates how the ambitus engraver may be
16 defined on the user side, with a Scheme engraver.
18 This is basically a rewrite in Scheme of the code from
19 @file{lily/ambitus-engraver.cc}.
22 doctitle = "Defining an engraver in Scheme: ambitus engraver"
26 #(use-modules (oop goops))
31 %%% These are literal rewrites of some C++ methods used by the ambitus engraver.
33 #(define (ly:separation-item::add-conditional-item grob grob-item)
34 "Add @var{grob-item} to the array of conditional elements of @var{grob}.
35 Rewrite of @code{Separation_item::add_conditional_item} from @file{lily/separation-item.cc}."
36 (ly:pointer-group-interface::add-grob grob 'conditional-elements grob-item))
38 #(define (ly:accidental-placement::accidental-pitch accidental-grob)
39 "Get the pitch from the grob cause of @var{accidental-grob}.
40 Rewrite of @code{accidental_pitch} from @file{lily/accidental-placement.cc}."
41 (ly:event-property (ly:grob-property (ly:grob-parent accidental-grob Y) 'cause)
44 #(define (ly:accidental-placement::add-accidental grob accidental-grob)
45 "Add @var{accidental-grob}, an @code{Accidental} grob, to the
46 list of the accidental grobs of @var{grob}, an @code{AccidentalPlacement}
48 Rewrite of @code{Accidental_placement::add_accidental} from @file{lily/accidental-placement.cc}."
49 (let ((pitch (ly:accidental-placement::accidental-pitch accidental-grob)))
50 (set! (ly:grob-parent accidental-grob X) grob)
51 (set! (ly:grob-property accidental-grob 'X-offset)
52 ly:grob::x-parent-positioning)
53 (let* ((accidentals (ly:grob-object grob 'accidental-grobs))
54 (handle (assq (ly:pitch-notename pitch) accidentals))
55 (entry (if handle (cdr handle) '())))
56 (set! (ly:grob-object grob 'accidental-grobs)
57 (assq-set! accidentals
58 (ly:pitch-notename pitch)
59 (cons accidental-grob entry))))))
62 %%% Ambitus data structure
65 %%% The <ambitus> class holds the various grobs that are created
66 %%% to print an ambitus:
67 %%% - ambitus-group: the grob that groups all the components of an ambitus
69 %%% - ambitus-line: the vertical line between the upper and lower ambitus
70 %%% notes (AmbitusLine grob);
71 %%% - ambitus-up-note and ambitus-down-note: the note head and accidental
72 %%% for the lower and upper note of the ambitus (see <ambitus-note> class
74 %%% The other slots define the key and clef context of the engraver:
75 %%% - start-c0: position of middle c at the beginning of the piece. It
76 %%% is used to place the ambitus notes according to their pitch;
77 %%% - start-key-sig: the key signature at the beginning of the piece. It
78 %%% is used to determine if accidentals shall be printed next to ambitus
81 #(define-class <ambitus> ()
82 (ambitus-group #:accessor ambitus-group)
83 (ambitus-line #:accessor ambitus-line)
84 (ambitus-up-note #:getter ambitus-up-note
85 #:init-form (make <ambitus-note>))
86 (ambitus-down-note #:getter ambitus-down-note
87 #:init-form (make <ambitus-note>))
88 (start-c0 #:accessor ambitus-start-c0
90 (start-key-sig #:accessor ambitus-start-key-sig
93 %%% Accessor for the lower and upper note data of an ambitus
94 #(define-method (ambitus-note (ambitus <ambitus>) direction)
95 "If @var{direction} is @code{UP}, then return the upper ambitus note
96 of @var{ambitus}, otherwise return the lower ambitus note."
98 (ambitus-up-note ambitus)
99 (ambitus-down-note ambitus)))
101 %%% The <ambitus-note> class holds the grobs that are specific to ambitus
102 %%% (lower and upper) notes:
103 %%% - head: an AmbitusNoteHead grob;
104 %%% - accidental: an AmbitusAccidental grob, to be possibly printed next
105 %%% to the ambitus note head.
107 %%% - pitch is the absolute pitch of the note
108 %%% - cause is the note event that causes this ambitus note, i.e. the lower
109 %%% or upper note of the considered music sequence.
111 #(define-class <ambitus-note> ()
112 (head #:accessor ambitus-note-head
114 (accidental #:accessor ambitus-note-accidental
116 (cause #:accessor ambitus-note-cause
118 (pitch #:accessor ambitus-note-pitch
122 %%% Ambitus engraving logics
124 %%% Rewrite of the code from @file{lily/ambitus-engraver.cc}.
126 #(define (make-ambitus translator)
127 "Build an ambitus object: initialize all the grobs and their relations.
129 The Ambitus grob contain all other grobs:
132 |- AmbitusNoteHead for upper note
133 |- AmbitusAccidental for upper note
134 |- AmbitusNoteHead for lower note
135 |- AmbitusAccidental for lower note
137 The parent of an accidental is the corresponding note head,
138 and the accidental is set as the 'accidental-grob of the note head
139 so that is printed by the function that prints notes."
140 ;; make the ambitus object
141 (let ((ambitus (make <ambitus>)))
142 ;; build the Ambitus grob, which will contain all other grobs
143 (set! (ambitus-group ambitus) (ly:engraver-make-grob translator 'Ambitus '()))
144 ;; build the AmbitusLine grob (line between lower and upper note)
145 (set! (ambitus-line ambitus) (ly:engraver-make-grob translator 'AmbitusLine '()))
146 ;; build the upper and lower AmbitusNoteHead and AmbitusAccidental
147 (for-each (lambda (direction)
148 (let ((head (ly:engraver-make-grob translator 'AmbitusNoteHead '()))
149 (accidental (ly:engraver-make-grob translator 'AmbitusAccidental '()))
150 (group (ambitus-group ambitus)))
151 ;; The parent of the AmbitusAccidental grob is the
152 ;; AmbitusNoteHead grob
153 (set! (ly:grob-parent accidental Y) head)
154 ;; The AmbitusAccidental grob is set as the accidental-grob
155 ;; object of the AmbitusNoteHead. This is later used by the
156 ;; function that prints notes.
157 (set! (ly:grob-object head 'accidental-grob) accidental)
158 ;; both the note head and the accidental grobs are added
159 ;; to the main ambitus grob.
160 (ly:axis-group-interface::add-element group head)
161 (ly:axis-group-interface::add-element group accidental)
162 ;; the note head and the accidental grobs are added to the
164 (set! (ambitus-note-head (ambitus-note ambitus direction))
166 (set! (ambitus-note-accidental (ambitus-note ambitus direction))
169 ;; The parent of the ambitus line is the lower ambitus note head
170 (set! (ly:grob-parent (ambitus-line ambitus) X)
171 (ambitus-note-head (ambitus-note ambitus DOWN)))
172 ;; the ambitus line is added to the ambitus main grob
173 (ly:axis-group-interface::add-element (ambitus-group ambitus) (ambitus-line ambitus))
176 #(define-method (initialize-ambitus-state (ambitus <ambitus>) translator)
177 "Initialize the state of @var{ambitus}, by getting the starting
178 position of middle C and key signature from @var{translator}'s context."
179 (if (not (ambitus-start-c0 ambitus))
181 (set! (ambitus-start-c0 ambitus)
182 (ly:context-property (ly:translator-context translator)
185 (set! (ambitus-start-key-sig ambitus)
186 (ly:context-property (ly:translator-context translator)
189 #(define-method (update-ambitus-notes (ambitus <ambitus>) note-grob)
190 "Update the upper and lower ambitus pithes of @var{ambitus}, using
192 ;; Get the event that caused the note-grob creation
193 ;; and check that it is a note-event.
194 (let ((note-event (ly:grob-property note-grob 'cause)))
195 (if (ly:in-event-class? note-event 'note-event)
196 ;; get the pitch from the note event
197 (let ((pitch (ly:event-property note-event 'pitch)))
198 ;; if this pitch is lower than the current ambitus lower
199 ;; note pitch (or it has not been initialized yet),
200 ;; then this pitch is the new ambitus lower pitch,
201 ;; and conversely for upper pitch.
202 (for-each (lambda (direction pitch-compare)
203 (if (or (not (ambitus-note-pitch (ambitus-note ambitus direction)))
205 (ambitus-note-pitch (ambitus-note ambitus direction))))
207 (set! (ambitus-note-pitch (ambitus-note ambitus direction))
209 (set! (ambitus-note-cause (ambitus-note ambitus direction))
212 (list ly:pitch<? (lambda (p1 p2)
213 (ly:pitch<? p2 p1))))))))
215 #(define-method (typeset-ambitus (ambitus <ambitus>) translator)
216 "Typeset the ambitus:
217 - place the lower and upper ambitus notes according to their pitch and
218 the position of the middle C;
219 - typeset or delete the note accidentals, according to the key signature.
220 An accidental, if it is to be printed, is added to an AccidentalPlacement
221 grob (a grob dedicated to the placement of accidentals near a chord);
222 - both note heads are added to the ambitus line grob, so that a line should
223 be printed between them."
224 ;; check if there are lower and upper pitches
225 (if (and (ambitus-note-pitch (ambitus-note ambitus UP))
226 (ambitus-note-pitch (ambitus-note ambitus DOWN)))
227 ;; make an AccidentalPlacement grob, for placement of note accidentals
228 (let ((accidental-placement (ly:engraver-make-grob
231 (ambitus-note-accidental (ambitus-note ambitus DOWN)))))
232 ;; For lower and upper ambitus notes:
233 (for-each (lambda (direction)
234 (let ((pitch (ambitus-note-pitch (ambitus-note ambitus direction))))
235 ;; set the cause and the staff position of the ambitus note
236 ;; according to the associated pitch
237 (set! (ly:grob-property (ambitus-note-head (ambitus-note ambitus direction))
239 (ambitus-note-cause (ambitus-note ambitus direction)))
240 (set! (ly:grob-property (ambitus-note-head (ambitus-note ambitus direction))
242 (+ (ambitus-start-c0 ambitus)
243 (ly:pitch-steps pitch)))
244 ;; determine if an accidental shall be printed for this note,
245 ;; according to the key signature
246 (let* ((handle (or (assoc (cons (ly:pitch-octave pitch)
247 (ly:pitch-notename pitch))
248 (ambitus-start-key-sig ambitus))
249 (assoc (ly:pitch-notename pitch)
250 (ambitus-start-key-sig ambitus))))
251 (sig-alter (if handle (cdr handle) 0)))
252 (cond ((= (ly:pitch-alteration pitch) sig-alter)
253 ;; the note alteration is in the key signature
254 ;; => it does not have to be printed
256 (ambitus-note-accidental (ambitus-note ambitus direction)))
257 (set! (ly:grob-object (ambitus-note-head (ambitus-note ambitus direction))
261 ;; otherwise, the accidental shall be printed
262 (set! (ly:grob-property (ambitus-note-accidental
263 (ambitus-note ambitus direction))
265 (ly:pitch-alteration pitch)))))
266 ;; add the AccidentalPlacement grob to the
267 ;; conditional items of the AmbitusNoteHead
268 (ly:separation-item::add-conditional-item
269 (ambitus-note-head (ambitus-note ambitus direction))
270 accidental-placement)
271 ;; add the AmbitusAccidental to the list of the
272 ;; AccidentalPlacement grob accidentals
273 (ly:accidental-placement::add-accidental
275 (ambitus-note-accidental (ambitus-note ambitus direction)))
276 ;; add the AmbitusNoteHead grob to the AmbitusLine grob
277 (ly:pointer-group-interface::add-grob
278 (ambitus-line ambitus)
280 (ambitus-note-head (ambitus-note ambitus direction)))))
282 ;; add the AccidentalPlacement grob to the main Ambitus grob
283 (ly:axis-group-interface::add-element (ambitus-group ambitus) accidental-placement))
284 ;; no notes ==> suicide the grobs
286 (for-each (lambda (direction)
287 (ly:grob-suicide! (ambitus-note-accidental (ambitus-note ambitus direction)))
288 (ly:grob-suicide! (ambitus-note-head (ambitus-note ambitus direction))))
290 (ly:grob-suicide! ambitus-line))))
293 %%% Ambitus engraver definition
295 #(define ambitus-engraver
298 ;; when music is processed: make the ambitus object, if not already built
300 ((process-music translator)
302 (set! ambitus (make-ambitus translator))))
303 ;; set the ambitus clef and key signature state
304 ((stop-translation-timestep translator)
306 (initialize-ambitus-state ambitus translator)))
307 ;; when a note-head grob is built, update the ambitus notes
309 ((note-head-interface engraver grob source-engraver)
311 (update-ambitus-notes ambitus grob))))
312 ;; finally, typeset the ambitus according to its upper and lower notes
314 ((finalize translator)
316 (typeset-ambitus ambitus translator)))))))
324 \new Staff { c'4 des' e' fis' gis' }
325 \new Staff { \clef "bass" c4 des ~ des ees b, }
327 \layout { \context { \Staff \consists #ambitus-engraver } }