scm/interface.scm

   1
   2 ; should include default value?
   3
   4 ;;; ::::::: should generate documentation for score elements from here.
   5
   6 (define (property-description symbol type? description)
   7   (list symbol type? description))
   8
   9 (define (lily-interface symbol description props)
  10   (list symbol
  11         description
  12         props
  13         )
  14   )
  15
  16
  17 (define (merge-interfaces ifs)
  18    (list
  19     (apply append (map car ifs))
  20     (apply append (map cadr ifs))
  21     (apply append (map caddr ifs))
  22   ))
  23
  24 (define (uniqued-alist  alist acc)
  25   (if (null? alist) acc
  26       (if (assoc (caar alist) acc)
  27           (uniqued-alist (cdr alist) acc)
  28           (uniqued-alist (cdr alist) (cons (car alist) acc)
  29   ))))
  30
  31 (define (element-description name . interfaces)
  32   (let* ((ifs (cons general-element-interface interfaces))
  33          (props (map caddr ifs))
  34          (syms (map car ifs))
  35         )
  36     (list (cons 'separator "\n\n\n")    ;easy printing.
  37           (cons 'name name)
  38           (cons 'interfaces syms)
  39           (cons 'interface-descriptions ifs)
  40           ; (cons 'interface-descriptions (cadr merged))
  41           ;; description of the element itself?
  42           (cons 'properties (apply append props))
  43   )))
  44
  45
  46 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  47 ;;;;;;;;;;;;;;;;
  48 ;;;;;;;;;;;;;;;;;
  49
  50 (define general-element-interface
  51   (lily-interface
  52    'general-element-interface
  53    "All elements support this"
  54    (list (property-description 'X-offset-callbacks list? "")
  55     (property-description 'Y-offset-callbacks list? "")
  56     (property-description 'X-extent-callback procedure? "")
  57     (property-description 'Y-extent-callback procedure? "")
  58     (property-description 'font-size integer? "")
  59     ))
  60 )
  61
  62 (define beam-interface
  63   (lily-interface
  64    'beam-interface
  65    "A beam. "
  66    (list
  67     (property-description 'y-position number? "position of left edge")
  68     (property-description 'height number? "dy")
  69     (property-description 'flag-width-function procedure? "")
  70     (property-description 'damping integer? "amount of beam slope damping should beam slope be damped? 0: no, 1: yes, 100000: horizontal beams ")
  71     (property-description 'default-neutral-direction dir? "which
  72 direction to choose if we're in the middle of the staff ")
  73     (property-description 'thickness number? "weight of beams, in staffspace")
  74     (property-description 'space-function procedure? "function of type multiplicity -> real (in staffspace)")
  75     (property-description 'beamed-stem-shorten number? "")
  76     (property-description 'height-quants number? "")
  77     (property-description 'vertical-position-quant-function procedure? "")
  78     (property-description 'dir-function procedure? "")
  79     (property-description 'damping number? "damping factor.")
  80     (property-description 'outer-stem-length-limit number? "catch
  81 suspect beam slopes, set slope to zero if outer stem is lengthened
  82 more than this (in staffspace)")
  83     (property-description 'slope-limit number? "set slope to zero if slope is running away steeper than this.")
  84     )
  85 ))
  86
  87
  88
  89 ;;;;;;;;;;;;;;;;;;;;
  90
  91 (define clef-interface
  92   (lily-interface
  93    'clef-interface
  94    "A clef sign"
  95    (list
  96     (property-description 'non-default boolean? "not set because of existence of a bar?")
  97     (property-description 'change boolean? "is this a change clef (smaller size)?")
  98     (property-description 'glyph string? "a string determining what glyph is typeset")
  99     ))
 100   )
 101
 102 (define axis-group-interface
 103   (lily-interface
 104    'axis-group-interface
 105    "a group of coupled elements"
 106    (list
 107     (property-description 'axes list? "list of axis (number) in which this group works")
 108    )))
 109
 110 (define note-column-interface
 111   (lily-interface
 112    'note-column-interface
 113    "Stem and noteheads combined"
 114    (list
 115     (property-description 'horizontal-shift integer? "integer that identifies ranking of note-column for horizontal shifting.")
 116     (property-description 'force-hshift number? "amount of collision_note_width that overides automatic collision settings.")
 117     (property-description 'merge-differently-dotted boolean? "merge black noteheads with differing dot count.")
 118     ))
 119   )
 120
 121 (define stem-interface
 122   (lily-interface
 123    'stem-interface
 124    "A stem"
 125    (list
 126     (property-description 'thickness number? "")
 127     (property-description 'beamed-lengths list? "")
 128     (property-description 'beamed-minimum-lengths list? "")
 129     (property-description 'lengths list? "")
 130     (property-description 'stem-shorten list? "")
 131     (property-description 'default-neutral-direction dir? "")
 132     (property-description 'direction dir? "")
 133     (property-description 'stem-length number? "")
 134     (property-description 'style string? "") ; symbol!?
 135     (property-description 'flag-style string? "") ; symbol!?
 136     (property-description 'X-offset-callbacks list? "")
 137     )))
 138
 139
 140 (define slur-interface
 141   (lily-interface
 142    'slur-interface
 143    "A slur"
 144    (list
 145     (property-description 'de-uglify-parameters list? "list of 3 real constants. They define the valid areas for the middle control points. Used in de_uglyfy. They are a bit empirical.")
 146     (property-description 'details list? "alist containing contaning a few magic constants.")
 147     (property-description 'attachment pair? "cons of symbols, '(LEFT-TYPE . RIGHT-TYPE), where both types may be alongside-stem, stem, head or loose-end")
 148     (property-description 'attachment-offset pair? "cons of offsets, '(LEFT-offset . RIGHT-offset).  This offset is added to the attachments to prevent ugly slurs.")
 149     (property-description 'direction dir? "up or down?")
 150     (property-description 'beautiful number? "number that dictates when a slur should be de-uglyfied.  It correlates with the enclosed area between noteheads and slurs.  A value of 0.1 yields only undisturbed slurs, a value of 5 will tolerate quite high blown slurs.")
 151     (property-description 'y-free number? "minimal vertical gap between slur and noteheads or stems")
 152     (property-description 'control-points list? "[internal] control points of bezier curve")
 153     (property-description 'extremity-rules  list? "an alist (procedure slur dir) -> attachment to determine the attachment (see above).  If procedure returns #t, attachment is used.  Otherwise, the next procedure is tried.")
 154     (property-description 'extremity-offset-alist list? "an alist (attachment stem-dir*dir slur-dir*dir) -> offset.  The offset adds to the centre of the notehead, or stem.")
 155     (property-description 'thickness list? "The thickness[stafflinethickness] of slur in the centre.")
 156     (property-description 'dashed number? "[FIXME: use dash-period/dash length; see text-spanner] number representing the length of the dashes.")
 157     )
 158    )
 159   )
 160
 161 (define side-position-interface
 162   (lily-interface
 163    'side-position-interface
 164    "put an element next to another one."
 165    (list
 166     (property-description 'direction dir? "where to put the victim object (left or right?)")
 167     (property-description 'side-relative-direction dir? "if set: get the direction from a different object, and multiply by this.")
 168     (property-description 'minimum-space number? "minimum distance that the victim should move (after padding)")
 169     (property-description 'padding number? "add this much extra space between victim and support")
 170     (property-description 'self-alignment-X number? "real number: -1 = left aligned, 0 = center, 1 right-aligned in X direction. Set to an element pointer, if you want that element to be the center. ")
 171     (property-description 'self-alignment-Y number? "like self-alignment-X but for Y axis")
 172
 173     )
 174   ))
 175
 176 (define accidentals-interface
 177   (lily-interface
 178    'accidentals-interface
 179    "Accidentals"
 180    (list
 181     (property-description 'left-padding number? "space left of accs")
 182     (property-description 'right-padding number? "space right of accs")
 183     )
 184    ))
 185
 186 (define note-head-interface
 187   (lily-interface
 188    'note-head-interface
 189    "Note head"
 190    (list
 191     (property-description 'style symbol? "symbol that sets note head style")
 192     )
 193    ))
 194
 195 (define note-name-interface
 196   (lily-interface
 197    'note-name-interface
 198    "Note naem"
 199    (list
 200     (property-description 'style symbol? "symbol that sets note name style")
 201     )
 202    ))
 203
 204
 205 (define rhythmic-head-interface
 206   (lily-interface
 207    'rhythmic-head-interface
 208    "Note head or rest"
 209    (list
 210     (property-description 'dot ly-element? "reference to Dots object.")
 211     (property-description 'stem ly-element? "pointer to Stem object")
 212     (property-description 'duration-log integer? "2-log of the notehead duration")
 213     )))
 214
 215 (define rest-interface
 216   (lily-interface
 217    'rest-interface
 218    "a rest"
 219    (list
 220     (property-description 'style string? "string specifying glyph style"))))
 221
 222 (define tuplet-bracket-interface
 223   (lily-interface
 224    'tuplet-bracket-interface
 225    "A bracket with a number in the middle"
 226    (list
 227     (property-description 'beams list? "list of beam ptrs.")
 228     (property-description 'columns list? " list of note-columns.")
 229     (property-description 'number-gap number? "")
 230     (property-description 'delta-y number? "")
 231     (property-description 'thick number? "")
 232     )
 233 ))
 234
 235
 236 (define align-interface
 237   (lily-interface
 238    'align-interface
 239    " Order elements top to bottom/left to right/right to left etc."
 240    (list
 241     (property-description 'stacking-dir  dir? "stack contents of elements in which direction ?")
 242     (property-description 'align-dir  dir? "Which side to align? -1: left side, 0: centered around center-element if not nil, or around center of width), 1: right side")
 243     (property-description 'threshold  pair? "(cons MIN MAX), where MIN and MAX are dimensions in staffspace")
 244     (property-description 'alignment-done  boolean? "boolean to administrate whether we've done the alignment already (to ensure that the process is done only once)")
 245     (property-description 'center-element ly-element? "element which will be at the
 246 center of the group after aligning (when using
 247 Align_interface::center_on_element). The center element should have
 248 this object as a reference point.")
 249     (property-description 'elements  list? "to be aligned elements ")
 250     (property-description 'axes  list? "list of axis numbers. Should contain only one number.")
 251     )))
 252
 253 (define aligned-interface
 254   (lily-interface
 255    'aligned-interface
 256    "read by align-interface"
 257    (list
 258     (property-description 'minimum-space pair? "(cons LEFT RIGHT)")
 259     (property-description 'extra-space pair? "(cons LEFT RIGHT)")
 260     )))
 261
 262 (define break-aligned-interface
 263   (lily-interface
 264    'break-aligned-interface
 265    "Items that are aligned in prefatory matter"
 266    (list
 267     (property-description 'break-align-symbol symbol? "the index in the spacing table (symbol) of the to be aligned item.")
 268     (property-description 'visibility-lambda procedure? "")
 269     (property-description 'breakable boolean? "")
 270     )))
 271
 272 (define chord-name-interface
 273   (lily-interface
 274    'chord-name-interface
 275    ""
 276    (list
 277     )))
 278 (define time-signature-interface
 279   (lily-interface
 280    'time-signature-interface
 281    "A time signature, in different styles"
 282    (list
 283     (property-description 'fraction pair? "")
 284     (property-description 'style string? "")
 285     )))
 286
 287 (define bar-line-interface
 288   (lily-interface
 289    'bar-line-interface
 290    "Bar line"
 291    (list
 292     (property-description 'barsize-procedure procedure? "")
 293     (property-description 'kern number? "")
 294     (property-description 'thin-kern number? "")
 295     (property-description 'hair-thickness number? "")
 296     (property-description 'thick-thickness number? "")
 297     (property-description 'glyph string? "")
 298     (property-description 'bar-size number? "")
 299     (property-description 'break-glyph-function procedure? "")
 300    )))
 301
 302
 303
 304 (define hairpin-interface
 305   (lily-interface
 306    'hairpin-interface
 307    "hairpin crescendo"
 308    (list
 309     (property-description 'grow-direction dir? "")
 310     (property-description 'thickness number? "")
 311     (property-description 'height number? "")
 312     )))
 313
 314
 315 (define arpeggio-interface
 316   (lily-interface
 317    'arpeggio-interface
 318    "arpeggio "
 319    (list
 320     (property-description 'stems list? "list of stem objects, corresponding to the notes that the  arp has to be before.")
 321     )
 322    )
 323   )
 324
 325 (define note-collision-interface
 326   (lily-interface
 327    'note-collision-interface
 328    "note collision"
 329    (list
 330     (property-description 'note-width 'number? "unit for horizontal translation, measured in staff-space.")
 331     )   )  )
 332 (define dot-interface
 333   (lily-interface
 334    'dots-interface
 335    "The dots to go with a notehead/rest.  A separate interface, since they
 336   are a party in collision resolution."
 337    (list
 338     (property-description 'dot-count integer? "number of dots")
 339     )))
 340
 341 (define text-interface
 342   (lily-interface
 343    'text-interface
 344    "A scheme markup text"
 345    (list
 346     (property-description 'text (lambda (x) (or (string? x) (list? x))) "the scheme markup text.  Either a string, or a list of which the CAR is a markup '(MARKUP text text ...).  MARKUP is either a CONS: an element property '(key . value) or a symbol: an abbreviation for a list of element properties.  These abbreviations are currently defined: rows lines roman music bold italic named super sub text, as well as all font-style's.")
 347     (property-description 'font-style string? "font definition for a special purpose, one of: finger volta timesig mark script large Large dynamic")
 348     (property-description 'font-series string? "partial font definition: medium, bold")
 349     (property-description 'font-shape string?  "partial font definition: upright or italic")
 350     (property-description 'font-family string? "partial font definition: music roman braces dynamic math ...")
 351     (property-description 'font-name string? "partial font definition: base name of font file FIXME: should override other partials")
 352     (property-description 'font-point string? "partial font definition: exact font size in points FIXME: should override font-size")
 353     (property-description 'font-size string? "partial font definition: the relative size, 0 is style-sheet's normal size, -1 is smaller, +1 is bigger")
 354     (property-description 'align number? "the alignment of the text, 0 is horizontal, 1 is vertical")
 355     (property-description 'lookup symbol? "lookup method: 'value for plain text, 'name for character-name")
 356     (property-description 'raise number? "height for text to be raised (a negative value lowers the text")
 357     (property-description 'kern number? "amount of extra white space to add before text.  This is `relative'(?) to the current alignment.")
 358     (property-description 'magnify number? "the magnification factor.  FIXME: doesn't work for feta fonts")
 359     )))
 360
 361
 362 (define dot-column-interface
 363   (lily-interface
 364    'dot-column-interface
 365    ""
 366    (list
 367     )))
 368
 369 (define dynamic-interface
 370   (lily-interface
 371    'dynamic-interface
 372    "Any kind of loudness sign"
 373    '()
 374     ))
 375
 376
 377 (define finger-interface
 378   (lily-interface
 379    'finger-interface
 380    "Any kind of loudness sign"
 381    '()
 382     ))
 383
 384 (define separation-spanner-interface
 385   (lily-interface
 386    'separation-spanner-interface
 387    ""
 388    '()
 389   ))
 390 (define text-script-interface
 391   (lily-interface
 392    'text-script-interface
 393    "Any text script"
 394    '()
 395     ))
 396
 397 (define grace-alignment-interface
 398   (lily-interface
 399    'grace-alignment-interface
 400    "put grace notes in line"
 401    (list
 402     (property-description 'horizontal-space number? "amount of space to add after a note (in staff-space)")
 403     )
 404    ))
 405
 406 (define hara-kiri-group-interface
 407   (lily-interface
 408    'hara-kiri-group-interface
 409    "seppuku"
 410    '()))
 411
 412 (define lyric-hyphen-interface
 413   (lily-interface
 414    'lyric-hyphen-interface
 415    "A centred hyphen is a simple line between lyrics used to divide
 416 syllables.   The length of the hyphen line should stretch based on the
 417   size of the gap between syllables."
 418    (list
 419
 420     (property-description 'thickness number? "thickness of line (in stafflinethickness)")
 421     (property-description 'height number? "vertical offset  (in staffspace)")
 422
 423     (property-description 'minimum-length number? "try to make the hyphens at least this long. Also works as a scaling parameter for the length")
 424     (property-description 'word-space number? "elongate left by this much (FIXME: cumbersome semantics)")
 425     )))
 426
 427 (define key-signature-interface
 428   (lily-interface
 429    'key-signature-interface
 430    "A group of  accidentals."
 431    (list
 432     (property-description 'c0-position  integer? "integer indicating the position of central C?")
 433     (property-description 'old-accidentals  list? "list of (pitch, accidental) pairs")
 434     (property-description 'new-accidentals  list? "list of (pitch, accidental) pairs")
 435     )))
 436
 437 (define lyric-extender-interface
 438   (lily-interface
 439    'lyric-extender-interface
 440    "The extender is a simple line at the baseline of the lyric
 441   that helps show the length of a melissima (tied/slurred note)."
 442    (list
 443     (property-description 'word-space  number? "")
 444     (property-description 'height  number? "in stafflinethickness")
 445     (property-description 'right-trim-amount  number? "")
 446     )))
 447
 448
 449 (define lyric-syllable-interface
 450   (lily-interface
 451    'lyric-syllable-interface
 452    ""
 453    (list
 454     (property-description 'word-space  number? "")
 455     )))
 456
 457
 458 (define mark-interface
 459   (lily-interface
 460    'mark-interface
 461    ""
 462    (list
 463     )))
 464
 465 (define multi-measure-rest-interface
 466   (lily-interface
 467    'multi-measure-rest-interface
 468    ""
 469    (list
 470
 471     (property-description 'columns  list? "list of paper-columns")
 472     (property-description 'expand-limit  integer? "int : max number of measures expanded in church rests")
 473     (property-description 'minimum-width number? "Real in staffspace")
 474     (property-description 'padding  number? "staffspace")
 475     )))
 476
 477 (define paper-column-interface
 478   (lily-interface
 479    'paper-column-interface
 480    ""
 481    (list
 482     (property-description 'dir-list  list? "list of stem directions")
 483     (property-description 'shortest-playing-duration  moment? "duration of the shortest playing in that column.")
 484     (property-description 'shortest-starter-duration  moment? "duration of the shortest notes that starts exactly in this column.")
 485     (property-description 'contains-grace  boolean? "Used to widen entries for grace notes.")
 486     (property-description 'extra-space  pair? "pair of distances")
 487     (property-description 'stretch-distance pair? "pair of distances")
 488     )))
 489
 490 (define spaceable-element-interface
 491   (lily-interface
 492    'spaceable-element-interface
 493    ""
 494    (list
 495      (property-description 'minimum-distances list? "list of rods (ie. (OBJ . DIST) pairs)")
 496      (property-description 'ideal-distances  list? "(OBJ . (DIST . STRENGTH)) pairs")
 497      (property-description 'dir-list list? "list of stem directions.")
 498      )))
 499
 500 (define rest-collision-interface
 501   (lily-interface
 502    'rest-collision-interface
 503    ""
 504    (list
 505     (property-description 'maximum-rest-count integer? "")
 506     (property-description 'minimum-distance number? "")
 507     )))
 508
 509 (define script-interface
 510   (lily-interface
 511    'script-interface
 512    ""
 513    (list
 514     (property-description 'script-priority number? "")
 515     )))
 516
 517 (define script-column-interface
 518   (lily-interface
 519    'script-column-interface
 520    ""
 521    (list )))
 522
 523
 524 (define spacing-spanner-interface
 525   (lily-interface
 526    'spacing-spanner-interface
 527    ""
 528    (list
 529     (property-description 'maximum-duration-for-spacing moment? "space as if a duration of this type is available in this measure.")
 530     )))
 531
 532 (define staff-symbol-interface
 533   (lily-interface
 534    'staff-symbol-interface
 535    "This spanner draws the lines of a staff.  The middle line is
 536 position 0."
 537    (list
 538     (property-description 'staff-space number? "")
 539     (property-description 'line-count integer? "")
 540     )))
 541
 542 (define stem-tremolo-interface
 543   (lily-interface
 544    'stem-tremolo-interface
 545    ""
 546    (list
 547     (property-description 'stem ly-element? "pointer to the stem object.")
 548     (property-description 'beam-width number? "")
 549     (property-description 'beam-thickness number? "")
 550     (property-description 'beam-space-function procedure? "")
 551     )))
 552
 553 (define separation-item-interface
 554   (lily-interface
 555    'separation-item-interface
 556    ""
 557    (list
 558     )))
 559
 560 (define sustain-pedal-interface
 561   (lily-interface
 562    'sustain-pedal-interface
 563    ""
 564    (list
 565     )))
 566 (define system-start-delimiter
 567   (lily-interface
 568    'system-start-delimiter
 569    ""
 570    (list
 571     (property-description 'collapse-height number? "")
 572     (property-description 'thickness number? "")
 573     (property-description 'arch-height number? "")
 574     (property-description 'arch-angle number? "")
 575     (property-description 'arch-thick number? "")
 576     (property-description 'arch-width number? "")
 577     (property-description 'bracket-thick number? "")
 578     (property-description 'bracket-width number? "")
 579     )))
 580
 581 (define text-script-interface
 582   (lily-interface
 583    'text-script-interface
 584    ""
 585    (list
 586
 587     )))
 588
 589 (define text-spanner-interface
 590   (lily-interface
 591    'text-spanner-interface
 592    "generic text spanner"
 593    (list
 594     (property-description 'dash-period  number? "the length of one dash + white space")
 595     (property-description 'dash-length number? "the length of a dash")
 596     (property-description 'line-thickness number? "the thickness[stafflinethickness] of the line")
 597     (property-description 'edge-height pair? "a cons that specifies the heights of the vertical egdes '(LEFT-height . RIGHT-height)")
 598     (property-description 'edge-text pair? "a cons that specifies the texts to be set at the edges '(LEFT-text . RIGHT-text)")
 599     (property-description 'type string? "one of: line, dashed-line or dotted-line") ; SYMBOL!!?
 600     )
 601 ))
 602
 603 (define tie-interface
 604   (lily-interface
 605    'tie-interface
 606    ""
 607    (list
 608     (property-description 'staffline-clearance number? "")
 609     (property-description 'heads pair? "pair of element pointers, pointing to the two heads of the  tie. ")
 610     (property-description 'details list? "")
 611     (property-description 'thickness number? "")
 612     (property-description 'x-gap number? "")
 613     (property-description 'minimum-length number? "")
 614     )))
 615
 616
 617
 618 (define tie-column-interface
 619   (lily-interface
 620    'tie-column-interface
 621    ""
 622    (list
 623     )))
 624
 625 (define volta-bracket-interface
 626   (lily-interface
 627    'volta-bracket-interface
 628    "Volta bracket with number"
 629    (list
 630     (property-description 'bars  list? "list of barline ptrs.")
 631     (property-description 'thickness  number? "in stafflinethickness")
 632     (property-description 'height  number? "in staffspace ")
 633     )))
 634
 635 (define span-bar-interface
 636   (lily-interface
 637    'span-bar-interface
 638    ""
 639    (list
 640     )))
 641