Documentation/snippets/displaying-grob-ancestry.ly

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