Documentation/snippets/displaying-grob-ancestry.ly

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