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