Documentation/snippets/new/displaying-grob-ancestry.ly

   1 \version "2.19.12"
   2
   3 \header {
   4   lsrtags = "devel, scheme-language, tweaks-and-overrides"
   5
   6   texidoc = "
   7 When working with grob callbacks, it can be helpful to understand a
   8 grob's @qq{ancestry}. Most grobs have @qq{parents} which influence the
   9 positioning of the grob. X- and Y-parents influence the horizontal and
  10 vertical positions for the grob, respectively. Additionally, each
  11 parent may have parents of its own.
  12
  13
  14 Unfortunately, there are several aspects of a grob's ancestry that can
  15 lead to confusion:
  16
  17 * The types of parents a grob has may depend on context. * For some
  18 grobs, the X- and Y-parents are the same. * A particular @qq{ancestor}
  19 may be related to a grob in multiple ways. * The concept of
  20 @qq{generations} is misleading.
  21
  22
  23 For example, the @code{System} grob can be both parent (on the Y-side)
  24 and grandparent (twice on the X-side) to a @code{VerticalAlignment}
  25 grob.
  26
  27
  28 This macro prints (to the console) a textual representation of a grob's
  29 ancestry.
  30
  31
  32 When called this way
  33
  34
  35 @{
  36  \\once \\override NoteHead.before-line-breaking = #display-ancestry
  37  c @}
  38
  39
  40 The following output is generated:
  41
  42
  43 ------------------------------------
  44
  45 NoteHead X,Y: NoteColumn
  46     X: PaperColumn
  47        X,Y: System
  48     Y: VerticalAxisGroup
  49        X: NonMusicalPaperColumn
  50           X,Y: System
  51        Y: VerticalAlignment
  52           X: NonMusicalPaperColumn
  53              X,Y: System
  54           Y: System
  55
  56
  57
  58 "
  59   doctitle = "Displaying grob ancestry"
  60 }
  61 %% http://lsr.di.unimi.it/LSR/Item?id=622
  62 %% see also http://www.lilypond.org/doc/v2.18/Documentation/snippets/tweaks-and-overrides#tweaks-and-overrides-displaying-grob-ancestry
  63
  64 #(define (grob-name grob)
  65    (if (ly:grob? grob)
  66        (assoc-ref (ly:grob-property grob 'meta) 'name)
  67        #f))
  68
  69 #(define (get-ancestry grob)
  70    (if (not (null? (ly:grob-parent grob X)))
  71        (list (grob-name grob)
  72              (get-ancestry (ly:grob-parent grob X))
  73              (get-ancestry (ly:grob-parent grob Y)))
  74        (grob-name grob)))
  75
  76 #(define (format-ancestry lst padding)
  77    (string-append
  78     (symbol->string (car lst))
  79     "\n"
  80     (let ((X-ancestry
  81            (if (list? (cadr lst))
  82                (format-ancestry (cadr lst) (+ padding 3))
  83                (symbol->string (cadr lst))))
  84           (Y-ancestry
  85            (if (list? (caddr lst))
  86                (format-ancestry (caddr lst) (+ padding 3))
  87                (symbol->string (caddr lst)))))
  88       (if (equal? X-ancestry Y-ancestry)
  89           (string-append
  90            (format #f "~&")
  91            (make-string padding #\space)
  92            "X,Y: "
  93            (if (list? (cadr lst))
  94                (format-ancestry (cadr lst) (+ padding 5))
  95                (symbol->string (cadr lst))))
  96           (string-append
  97            (format #f "~&")
  98            (make-string padding #\space)
  99            "X: " X-ancestry
 100            "\n"
 101            (make-string padding #\space)
 102            "Y: " Y-ancestry
 103            (format #f "~&"))))
 104     (format #f "~&")))
 105
 106 #(define (display-ancestry grob)
 107    (format (current-error-port)
 108       "~3&~a~2%~a~&"
 109       (make-string 36 #\-)
 110       (format-ancestry (get-ancestry grob) 0)))
 111
 112 \relative c' {
 113   \once \override NoteHead.before-line-breaking = #display-ancestry
 114   f4
 115   \once \override Accidental.before-line-breaking = #display-ancestry
 116   \once \override Arpeggio.before-line-breaking = #display-ancestry
 117   <f as c>4\arpeggio
 118 }