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, tweaks-and-overrides, scheme-language"
  11
  12 %% Translation of GIT committish: b482c3e5b56c3841a88d957e0ca12964bd3e64fa
  13
  14   texidoces = "
  15 Al trabajar con los callbacks de un grob, puede ser de mucha ayuda
  16 entender el @qq{árbol genealógico} de un grob.  La mayor parte de los
  17 grobs tienen @qq{padres} que influyen en el posicionamiento del grob.
  18 los padres X e Y influyen en las posiciones horizontal y vertical del
  19 grob, respectivamente.  Además, cada pade puede tener padres a su vez.
  20
  21
  22 Por desgracia, existen varios aspectos de la genealogía de un grob que
  23 pueden llevar a confusión:
  24
  25
  26 @itemize
  27
  28 @item Los tipos de padre que tiene un grob pueden depender del
  29 contexto.
  30
  31 @item Para ciertos grobs, los padres X e Y son el mismo.
  32
  33 @item Un @qq{ancestro} concreto puede estar relacionado con un grob de
  34 mas de una manera.
  35
  36 @item El concepto de @qq{generaciones} es engañoso.
  37
  38 @end itemize
  39
  40
  41 Por ejemplo, el grob @code{System} puede ser tanto un padre (sobre el
  42 lado Y) como un abuelo (dos veces en el lado X) de un grob
  43 @code{VerticalAlignment}.
  44
  45
  46 Este macro imprime, en la consola, una representación textual de la
  47 genealogía de un grob.
  48
  49
  50 Cuando se llama de esta forma
  51
  52 @example
  53 @{
  54    \\once \\override NoteHead #'before-line-breaking = #display-ancestry
  55    c4
  56 @}
  57 @end example
  58
  59
  60 Se genera la siguiente salida:
  61
  62
  63 @example
  64 ------------------------------------
  65
  66 NoteHead X,Y: NoteColumn
  67     X: PaperColumn
  68        X,Y: System
  69     Y: VerticalAxisGroup
  70        X: NonMusicalPaperColumn
  71           X,Y: System
  72        Y: VerticalAlignment
  73           X: NonMusicalPaperColumn
  74              X,Y: System
  75           Y: System
  76 @end example
  77
  78 "
  79
  80   doctitlees = "Imprimir el árbol genealógico de un grob"
  81
  82 %% Translation of GIT committish: 30339cb3706f6399c84607426988b25f79b4998c
  83   texidocfr = "
  84 Lorsque l'on manipule des rappels d'objet (@emph{grob callbacks}), il
  85 peut être intéressant d'en maîtriser la @qq{ascendants}.  La plupart des
  86 objets graphiques ont des parents, lesquels auront une influence sur le
  87 positionnement de l'objet en question.  Ainsi, les X- et Y-parents
  88 influenceront respectivement la position horizontale et verticale de
  89 l'objet.  De plus, chacun des parents peut avoir ses propres parents.
  90
  91 Certains aspects de la lignée d'un objet peuvent toutefois porter à
  92 confusion :
  93
  94 -- Les types de parents d'un @emph{grob} peuvent dépendre du contexte.
  95
  96 -- Dans le cas de certains @emph{grobs}, les parents X et Y peuvent être
  97    le même.
  98
  99 -- Un @qq{ascendant} particulier peut dépendre d'un @emph{grob} de
 100    différentes manières.
 101
 102 -- Le concept de @qq{génération} est trompeur.
 103
 104 Par exemple, l'objet @code{System} peut, vis à vis d'un objet
 105 @code{VerticalAlignment},  être à la fois parent (par son
 106 côté Y) et grand parent (par deux fois du côté X).
 107
 108 La macro ci-dessous affiche à l'écran une représentation textuelle de
 109 l'ascendance d'un @emph{grob}.
 110
 111
 112 Elle se lance ainsi :
 113
 114 @example
 115 @{
 116    \\once \\override NoteHead #'before-line-breaking = #display-ancestry
 117    c4
 118 @}
 119 @end example
 120
 121 et génère la sortie suivante :
 122
 123 @example
 124 ------------------------------------
 125
 126 NoteHead X,Y: NoteColumn
 127     X: PaperColumn
 128        X,Y: System
 129     Y: VerticalAxisGroup
 130        X: NonMusicalPaperColumn
 131           X,Y: System
 132        Y: VerticalAlignment
 133           X: NonMusicalPaperColumn
 134              X,Y: System
 135           Y: System
 136 @end example
 137
 138 "
 139   doctitlefr = "Affichage de la généalogie d'un objet"
 140
 141   texidoc = "
 142 When working with grob callbacks, it can be helpful to understand a
 143 grob's @qq{ancestry}. Most grobs have @qq{parents} which influence the
 144 positioning of the grob. X- and Y-parents influence the horizontal and
 145 vertical positions for the grob, respectively. Additionally, each
 146 parent may have parents of its own.
 147
 148
 149 Unfortunately, there are several aspects of a grob's ancestry that can
 150 lead to confusion:
 151
 152 * The types of parents a grob has may depend on context. * For some
 153 grobs, the X- and Y-parents are the same. * A particular @qq{ancestor}
 154 may be related to a grob in multiple ways. * The concept of
 155 @qq{generations} is misleading.
 156
 157
 158 For example, the @code{System} grob can be both parent (on the Y-side)
 159 and grandparent (twice on the X-side) to a @code{VerticalAlignment}
 160 grob.
 161
 162
 163 This macro prints (to the console) a textual representation of a grob's
 164 ancestry.
 165
 166
 167 When called this way
 168
 169
 170 @{
 171  \\once \\override NoteHead #'before-line-breaking = #display-ancestry
 172  c @}
 173
 174
 175 The following output is generated:
 176
 177
 178 ------------------------------------
 179
 180 NoteHead X,Y: NoteColumn
 181     X: PaperColumn
 182        X,Y: System
 183     Y: VerticalAxisGroup
 184        X: NonMusicalPaperColumn
 185           X,Y: System
 186        Y: VerticalAlignment
 187           X: NonMusicalPaperColumn
 188              X,Y: System
 189           Y: System
 190
 191
 192
 193 "
 194   doctitle = "Displaying grob ancestry"
 195 } % begin verbatim
 196
 197 #(define (grob-name grob)
 198    (if (ly:grob? grob)
 199        (assoc-ref (ly:grob-property grob 'meta) 'name)
 200        #f))
 201
 202 #(define (get-ancestry grob)
 203    (if (not (null? (ly:grob-parent grob X)))
 204        (list (grob-name grob)
 205              (get-ancestry (ly:grob-parent grob X))
 206              (get-ancestry (ly:grob-parent grob Y)))
 207        (grob-name grob)))
 208
 209 #(define (format-ancestry lst padding)
 210    (string-append
 211     (symbol->string (car lst))
 212     "\n"
 213     (let ((X-ancestry
 214            (if (list? (cadr lst))
 215                (format-ancestry (cadr lst) (+ padding 3))
 216                (symbol->string (cadr lst))))
 217           (Y-ancestry
 218            (if (list? (caddr lst))
 219                (format-ancestry (caddr lst) (+ padding 3))
 220                (symbol->string (caddr lst)))))
 221       (if (equal? X-ancestry Y-ancestry)
 222           (string-append
 223            (format #f "~&")
 224            (make-string padding #\space)
 225            "X,Y: "
 226            (if (list? (cadr lst))
 227                (format-ancestry (cadr lst) (+ padding 5))
 228                (symbol->string (cadr lst))))
 229           (string-append
 230            (format #f "~&")
 231            (make-string padding #\space)
 232            "X: " X-ancestry
 233            "\n"
 234            (make-string padding #\space)
 235            "Y: " Y-ancestry
 236            (format #f "~&"))))
 237     (format #f "~&")))
 238
 239 #(define (display-ancestry grob)
 240    (format (current-error-port)
 241       "~3&~a~2%~a~&"
 242       (make-string 36 #\-)
 243       (format-ancestry (get-ancestry grob) 0)))
 244
 245 \relative c' {
 246   \once \override NoteHead #'before-line-breaking = #display-ancestry
 247   f4
 248   \once \override Accidental #'before-line-breaking = #display-ancestry
 249   \once \override Arpeggio #'before-line-breaking = #display-ancestry
 250   <f as c>4\arpeggio
 251 }