Documentation/snippets/displaying-grob-ancestry.ly

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