Documentation/snippets/displaying-grob-ancestry.ly

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