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.13.36
   8 \version "2.14.0"
   9
  10 \header {
  11 %% Translation of GIT committish: 59caa3adce63114ca7972d18f95d4aadc528ec3d
  12
  13   texidoces = "
  14 Al trabajar con los callbacks de un grob, puede ser de mucha ayuda
  15 entender el @qq{árbol genealógico} de un grob.  La mayor parte de los
  16 grobs tienen @qq{padres} que influyen en el posicionamiento del grob.
  17 los padres X e Y influyen en las posiciones horizontal y vertical del
  18 grob, respectivamente.  Además, cada pade puede tener padres a su vez.
  19
  20
  21 Por desgracia, existen varios aspectos de la genealogía de un grob que
  22 pueden llevar a confusión:
  23
  24
  25 @itemize
  26
  27 @item Los tipos de padre que tiene un grob pueden depender del
  28 contexto.
  29
  30 @item Para ciertos grobs, los padres X e Y son el mismo.
  31
  32 @item Un @qq{ancestro} concreto puede estar relacionado con un grob de
  33 mas de una manera.
  34
  35 @item El concepto de @qq{generaciones} es engañoso.
  36
  37 @end itemize
  38
  39
  40 Por ejemplo, el grob @code{System} puede ser tanto un padre (sobre el
  41 lado Y) como un abuelo (dos veces en el lado X) de un grob
  42 @code{VerticalAlignment}.
  43
  44
  45 Este macro imprime, en la consola, una representación textual de la
  46 genealogía de un grob.
  47
  48
  49 Cuando se llama de esta forma
  50
  51 @example
  52 @{
  53    \\once \\override NoteHead #'before-line-breaking = #display-ancestry
  54    c4
  55 @}
  56 @end example
  57
  58
  59 Se genera la siguiente salida:
  60
  61
  62 @example
  63 ------------------------------------
  64
  65 NoteHead X,Y: NoteColumn
  66     X: PaperColumn
  67        X,Y: System
  68     Y: VerticalAxisGroup
  69        X: NonMusicalPaperColumn
  70           X,Y: System
  71        Y: VerticalAlignment
  72           X: NonMusicalPaperColumn
  73              X,Y: System
  74           Y: System
  75 @end example
  76
  77 "
  78
  79   doctitlees = "Imprimir el árbol genealógico de un grob"
  80
  81   lsrtags = "tweaks-and-overrides"
  82
  83   texidoc = "
  84 When working with grob callbacks, it can be helpful to understand a
  85 grob's @qq{ancestry}.  Most grobs have @qq{parents} which influence the
  86 positioning of the grob.  X- and Y-parents influence the horizontal and
  87 vertical positions for the grob, respectively.  Additionally, each
  88 parent may have parents of its own.
  89
  90
  91 Unfortunately, there are several aspects of a grob's ancestry that can
  92 lead to confusion:
  93
  94
  95 @itemize
  96
  97 @item
  98 The types of parents a grob has may depend on context.
  99
 100 @item
 101 For some grobs, the X- and Y-parents are the same.
 102
 103 @item
 104 A particular @qq{ancestor} may be related to a grob in multiple ways.
 105
 106 @item
 107 The concept of @qq{generations} is misleading.
 108
 109 @end itemize
 110
 111
 112 For example, the @code{System} grob can be both parent (on the Y-side)
 113 and grandparent (twice on the X-side) to a @code{VerticalAlignment}
 114 grob.
 115
 116
 117 This macro prints (to the console) a textual representation of a grob's
 118 ancestry.
 119
 120
 121 When called this way
 122
 123 @example
 124 @{
 125    \\once \\override NoteHead #'before-line-breaking = #display-ancestry
 126    c4
 127 @}
 128 @end example
 129
 130
 131 The following output is generated:
 132
 133
 134 @example
 135 ------------------------------------
 136
 137 NoteHead X,Y: NoteColumn
 138     X: PaperColumn
 139        X,Y: System
 140     Y: VerticalAxisGroup
 141        X: NonMusicalPaperColumn
 142           X,Y: System
 143        Y: VerticalAlignment
 144           X: NonMusicalPaperColumn
 145              X,Y: System
 146           Y: System
 147 @end example
 148
 149
 150 "
 151   doctitle = "Displaying grob ancestry"
 152 } % begin verbatim
 153
 154
 155 #(define (grob-name grob)
 156    (if (ly:grob? grob)
 157        (assoc-ref (ly:grob-property grob 'meta) 'name)
 158        #f))
 159
 160 #(define (get-ancestry grob)
 161    (if (not (null? (ly:grob-parent grob X)))
 162        (list (grob-name grob)
 163              (get-ancestry (ly:grob-parent grob X))
 164              (get-ancestry (ly:grob-parent grob Y)))
 165        (grob-name grob)))
 166
 167 #(define (format-ancestry lst padding)
 168    (string-append
 169     (symbol->string (car lst))
 170     "\n"
 171     (let ((X-ancestry
 172            (if (list? (cadr lst))
 173                (format-ancestry (cadr lst) (+ padding 3))
 174                (symbol->string (cadr lst))))
 175           (Y-ancestry
 176            (if (list? (caddr lst))
 177                (format-ancestry (caddr lst) (+ padding 3))
 178                (symbol->string (caddr lst)))))
 179       (if (equal? X-ancestry Y-ancestry)
 180           (string-append
 181            (format #f "~&")
 182            (make-string padding #\space)
 183            "X,Y: "
 184            (if (list? (cadr lst))
 185                (format-ancestry (cadr lst) (+ padding 5))
 186                (symbol->string (cadr lst))))
 187           (string-append
 188            (format #f "~&")
 189            (make-string padding #\space)
 190            "X: " X-ancestry
 191            "\n"
 192            (make-string padding #\space)
 193            "Y: " Y-ancestry
 194            (format #f "~&"))))
 195     (format #f "~&")))
 196
 197 #(define (display-ancestry grob)
 198    (display
 199     (string-append
 200      (format #f "~3&~a~2%" (make-string 36 #\-))
 201      (format-ancestry (get-ancestry grob) 0)
 202      (format #f "~2&"))))
 203
 204 \relative c' {
 205   \once \override NoteHead #'before-line-breaking = #display-ancestry
 206   f4
 207   \once \override Accidental #'before-line-breaking = #display-ancestry
 208   \once \override Arpeggio #'before-line-breaking = #display-ancestry
 209   <f as c>4\arpeggio
 210 }