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

   1 \version "2.14.0"
   2
   3 \header {
   4   lsrtags = "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
  18 @itemize
  19
  20 @item
  21 The types of parents a grob has may depend on context.
  22
  23 @item
  24 For some grobs, the X- and Y-parents are the same.
  25
  26 @item
  27 A particular @qq{ancestor} may be related to a grob in multiple ways.
  28
  29 @item
  30 The concept of @qq{generations} is misleading.
  31
  32 @end itemize
  33
  34
  35 For example, the @code{System} grob can be both parent (on the Y-side)
  36 and grandparent (twice on the X-side) to a @code{VerticalAlignment}
  37 grob.
  38
  39
  40 This macro prints (to the console) a textual representation of a grob's
  41 ancestry.
  42
  43
  44 When called this way
  45
  46 @example
  47 @{
  48    \\once \\override NoteHead #'before-line-breaking = #display-ancestry
  49    c4
  50 @}
  51 @end example
  52
  53
  54 The following output is generated:
  55
  56
  57 @example
  58 ------------------------------------
  59
  60 NoteHead X,Y: NoteColumn
  61     X: PaperColumn
  62        X,Y: System
  63     Y: VerticalAxisGroup
  64        X: NonMusicalPaperColumn
  65           X,Y: System
  66        Y: VerticalAlignment
  67           X: NonMusicalPaperColumn
  68              X,Y: System
  69           Y: System
  70 @end example
  71
  72
  73 "
  74   doctitle = "Displaying grob ancestry"
  75 }
  76
  77 #(define (grob-name grob)
  78    (if (ly:grob? grob)
  79        (assoc-ref (ly:grob-property grob 'meta) 'name)
  80        #f))
  81
  82 #(define (get-ancestry grob)
  83    (if (not (null? (ly:grob-parent grob X)))
  84        (list (grob-name grob)
  85              (get-ancestry (ly:grob-parent grob X))
  86              (get-ancestry (ly:grob-parent grob Y)))
  87        (grob-name grob)))
  88
  89 #(define (format-ancestry lst padding)
  90    (string-append
  91     (symbol->string (car lst))
  92     "\n"
  93     (let ((X-ancestry
  94            (if (list? (cadr lst))
  95                (format-ancestry (cadr lst) (+ padding 3))
  96                (symbol->string (cadr lst))))
  97           (Y-ancestry
  98            (if (list? (caddr lst))
  99                (format-ancestry (caddr lst) (+ padding 3))
 100                (symbol->string (caddr lst)))))
 101       (if (equal? X-ancestry Y-ancestry)
 102           (string-append
 103            (format #f "~&")
 104            (make-string padding #\space)
 105            "X,Y: "
 106            (if (list? (cadr lst))
 107                (format-ancestry (cadr lst) (+ padding 5))
 108                (symbol->string (cadr lst))))
 109           (string-append
 110            (format #f "~&")
 111            (make-string padding #\space)
 112            "X: " X-ancestry
 113            "\n"
 114            (make-string padding #\space)
 115            "Y: " Y-ancestry
 116            (format #f "~&"))))
 117     (format #f "~&")))
 118
 119 #(define (display-ancestry grob)
 120    (display
 121     (string-append
 122      (format #f "~3&~a~2%" (make-string 36 #\-))
 123      (format-ancestry (get-ancestry grob) 0)
 124      (format #f "~2&"))))
 125
 126 \relative c' {
 127   \once \override NoteHead #'before-line-breaking = #display-ancestry
 128   f4
 129   \once \override Accidental #'before-line-breaking = #display-ancestry
 130   \once \override Arpeggio #'before-line-breaking = #display-ancestry
 131   <f as c>4\arpeggio
 132 }