X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=scm%2Finterface-description.scm;h=60532b53130fce7d7c397daef80d0aa0abf69deb;hb=6288ae0c2d5a9e4c6246833cd131906c239b8272;hp=9d2249cac2d4eb3de7ac11c9f6364c9da09c92a5;hpb=fbc5381fb54df596fd5652236eedc7c1078601e6;p=lilypond.git diff --git a/scm/interface-description.scm b/scm/interface-description.scm index 9d2249cac2..60532b5313 100644 --- a/scm/interface-description.scm +++ b/scm/interface-description.scm @@ -6,786 +6,75 @@ ;;;; Jan Nieuwenhuizen - ; should include default value? +; should include default value? - -;;; FIXME: naming. -;;; Score elements are called `objects' now and then, which gets -;;; rather confusing, we now have `elements', `items', `spanners' -;;; and `objects'. - - -(define all-interfaces '()) - -(define (lily-interface symbol description props) - (set! all-interfaces (acons symbol (list symbol - description - props) all-interfaces) - ) - ) - -(define (grob-description . interfaces) - (let* ((ifs (cons grob-interface interfaces)) - (props (map caddr ifs)) - ; (prop-typep-pairs (map (lambda (x) (cons (car x) (cadr x))) - ; (apply append props))) - (syms (map car ifs)) - ) - (list (cons 'separator "\n\n\n") ;easy printing. - (cons 'interfaces syms) - (cons 'interface-descriptions ifs) - ; (cons 'interface-descriptions (cadr merged)) - ;; description of the grob itself? - ; (cons 'properties prop-typep-pairs) - ))) - - -(lily-interface - 'grob-interface - "All grobs support this" - '( - X-offset-callbacks - Y-offset-callbacks - X-extent-callback - Y-extent-callback - molecule-callback - font-relative-size - extra-offset - interfaces - dependencies - no-spacing-rods - extra-extent-X - extra-extent-Y - minimum-extent-X - minimum-extent-Y - origin - transparent - )) - - -(lily-interface - 'beam-interface - "A beam. - -#'thickness= weight of beams, in staffspace - " - '(auto-knee-gap - staff-position - height - flag-width-function - damping - neutral-direction - thickness - space-function - beamed-stem-shorten - height-quants - vertical-position-quant-function - damping - outer-stem-length-limit - slope-limit - auto-knee-gap - ) - ) - - -(lily-interface - 'clef-interface - "A clef sign" - '( - non-default - full-size-change - glyph - )) - - - -(lily-interface - 'axis-group-interface - "a group of coupled grobs" - '( - axes - )) - - -(lily-interface - 'note-column-interface - "Stem and noteheads combined" - '( - horizontal-shift - force-hshift - )) - - -(lily-interface - 'stem-interface - "A stem" - '( - thickness - beamed-lengths - beamed-minimum-lengths - lengths - beam - stem-shorten - duration-log - beaming - neutral-direction - stem-end-position - support-head - heads - direction - length - style - flag-style - dir-forced - )) - - - -(lily-interface - 'slur-interface - "A slur" - '( - de-uglify-parameters - details - attachment - direction - attachment-offset - beautiful - y-free - control-points - extremity-rules - extremity-offset-alist - thickness - dashed - - ) - ) - - - -(lily-interface - 'side-position-interface - "Position a victim object (this one) next to other objects (the support). -#'direction = where to put the victim object (left or right?) -" - '( - side-support - direction-source - direction - side-relative-direction - minimum-space - padding - self-alignment-X - self-alignment-Y - - ) - ) - - -(lily-interface - 'accidentals-interface - "Accidentals" - '(accidentals - left-padding - right-padding - )) - - - -(lily-interface - 'line-of-score-interface - "Super grob, parent of all: - -The columns of a score that form one line. The toplevel grob. Any -grob has a Line_of_score as both X and Y reference point. The -Paper_score contains one grob of this type. Control enters the -Grob dependency calculation from this single Line_of_score -object." - '( - between-system-string - spacing-procedure - before-line-breaking-callback - after-line-breaking-callback - all-elements - columns - )) - - -(lily-interface - 'note-head-interface - "Note head" - '( style stem-attachment-function note-character )) - - -(lily-interface - 'note-name-interface +(ly-add-interface +'note-name-interface "Note name" - '( style )) - - - -(lily-interface - 'rhythmic-head-interface - "Note head or rest" - '( - dot - stem - duration-log - )) - - -(lily-interface - 'rest-interface - "a rest" - '(style )) - - -(lily-interface - 'tuplet-bracket-interface - "A bracket with a number in the middle, used for tuplets." - '( - columns - number-gap - delta-y - tuplet-bracket-visibility - tuplet-number-visibility - thick - direction - )) - - -(lily-interface - 'align-interface - " Order grobs top to bottom/left to right/right to left etc." - '( - stacking-dir - align-dir - threshold - alignment-done - center-element - elements - axes - )) - - -(lily-interface - 'aligned-interface - "read by align-interface" - '( - minimum-space - extra-space - )) - - -(lily-interface - 'break-aligned-interface - "Items that are aligned in prefatory matter" - '( - break-align-symbol - visibility-lambda - breakable - )) - - -(lily-interface - 'chord-name-interface - "generate a chord name" - '( pitches inversion bass)) - - -(lily-interface - 'time-signature-interface - "A time signature, in different styles. - The following values for 'style are are recognized: - - @table @samp - @item @code{C} - 4/4 and 2/2 are typeset as C and struck C, respectively. All - other time signatures are written with two digits. - - @item @code{old} - 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are - typeset with old-style mensuration marks. All other time - signatures are written with two digits. - - @item @code{1xxx} - All time signatures are typeset with a single - digit, e.g. 3/2 is written as 3. (Any symbol starting - with the digit @code{1} will do.) - - @item @code{C}@var{M}@code{/}@var{N}, -@code{old}@var{M}@code{/}@var{N} or - @code{old6/8alt} - Tells LilyPond to use a specific symbol as time signature, - regardless of the actual time signature. - @end table - -See also the test-file @file{input/test/time.ly}. -" - '(fraction style )) - - -(lily-interface - 'bar-line-interface - "Bar line. - -This is a request to print a special bar symbol. It replaces the -regular bar symbol with a special -symbol. The argument @var{bartype} is a string which specifies the -kind of bar to print. Options are @code{\":|\"} -@cindex \"|A@@@code{:|} -, -@code{\"|:\"} -@cindex \"|B@@@code{|:} -, @code{\":|:\"} -@cindex \"|C@@@code{:|:} -, -@code{\"||\"} -@cindex \"|D@@@code{||} -, @code{\"|.\"} -@cindex \"|E@@@code{|.} -, -@code{\".|\"} -@cindex \"|F@@@code{.|} -, and @code{\".|.\"} -@cindex \"|G@@@code{.|.} -. - -These produce, respectively, a right repeat, a left repeat, a double -repeat, a double bar, a start bar, an end bar, and a thick double bar. -If @var{bartype} is set to @code{\"empty\"} then nothing is printed, -but a line break is allowed at that spot. - -" - '(bar-size-procedure kern thin-kern hair-thickness thick-thickness glyph bar-size break-glyph-function )) - - -(lily-interface - 'hairpin-interface - "hairpin crescendo. - -padding -- horizontal padding. This is useful if a crescendo is set next to a text like `mf' - -" - '( grow-direction thickness height padding - )) - - -(lily-interface - 'arpeggio-interface - "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads." - '(stems)) - - - -(lily-interface - 'note-collision-interface - "An object that handles collisions between notes with different -stem directions and horizontal shifts. Most of the interesting -properties are to be set in @ref{note-column-interface}" - '(merge-differently-dotted note-width)) - - - -(lily-interface - 'custos-interface - "A custos is a staff context symbol that appears at the end of a - staff line with monophonic musical contents (i.e. with a single - voice). It anticipates the pitch of the first note of the following - line and thus helps the player or singer to manage line breaks - during performance, thus enhancing readability of a score. - - Custodes were frequently used in music notation until the 16th - century. There were different appearences for different notation - styles. Nowadays, they have survived only in special forms of - musical notation such as via the editio vaticana dating back to the - beginning of the 20th century. - -[TODO: add to glossary]" - - '(style)) - - - + '(style)) - - - (lily-interface - 'dots-interface - "The dots to go with a notehead/rest. A separate interface, since they -are a party in collision resolution. -#'direction is the Direction to handle staff-line collisions in." - '(direction dot-count)) - - - (lily-interface - 'font-interface - "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)" - '(font-style font-series font-shape font-family font-name -font-design-size font-relative-size) - ) - - - - (lily-interface - 'text-interface - "A scheme markup text" - '(text align baseline-skip lookup raise kern magnify)) - - - (lily-interface - 'dot-column-interface - "Interface that groups dots so they form a column" - '( ) - ) - - - (lily-interface - 'dynamic-interface +(ly-add-interface + 'dynamic-interface "Any kind of loudness sign" '() ) +(ly-add-interface + 'finger-interface + "A fingering instruction" + '() + ) +(ly-add-interface + 'ligature-interface + "A ligature" + '() + ) - (lily-interface - 'finger-interface - "A fingering instruction" - '() - ) - - - (lily-interface - 'separation-spanner-interface - "Spanner that containing @code{separation-item-interface} grobs to calculate rods" - '() - ) - - (lily-interface - 'text-script-interface - "Any text script" - '() - ) - - - (lily-interface - 'grace-alignment-interface - "put grace notes in line" - '( - horizontal-space - ) - ) - - - (lily-interface - 'hara-kiri-group-interface - " As Vertical_group_spanner, but keep track of interesting items. If -we don't contain any interesting items after linebreaking, then -gracefully commit suicide. Objective: don't disgrace Lily by -typesetting empty lines in orchestral scores." - '( items-worth-living ) -) - - - (lily-interface - 'line-spanner-interface - "Generic line drawn between two objects, eg. for use with glissandi. -gap is measured in staff-spaces. " - - '(gap dash-period dash-length line-thickness type - )) - - - (lily-interface - 'lyric-hyphen-interface - "A centred hyphen is a simple line between lyrics used to divide -syllables. The length of the hyphen line should stretch based on the -size of the gap between syllables." - - '( thickness height minimum-length word-space +(ly-add-interface + 'mark-interface + "a rehearsal mark" + '( )) - - (lily-interface - 'key-signature-interface - "A group of accidentals." - '( - c0-position - old-accidentals - new-accidentals - )) - - - (lily-interface - 'lyric-extender-interface - "The extender is a simple line at the baseline of the lyric -that helps show the length of a melissima (tied/slurred note)." - '( - word-space - height - right-trim-amount - )) - - - - (lily-interface - 'lyric-syllable-interface - "a single piece of lyrics" - '( - word-space - )) - - - - (lily-interface - 'mark-interface - "a rehearsal mark" - '( - )) +;;; todo: this is not typesetting info. Move to interpretation. +(ly-add-interface + 'tablature-interface + "tablature notes" + '()) - (lily-interface - 'multi-measure-rest-interface - "A rest that spans a whole number of measures. For typesetting the -numbers, fields from font-interface may be used. -padding is the space between number and rest. Measured in staffspace. +;; todo: figure out where to put this doco: " - '( columns expand-limit minimum-width padding)) - - - (lily-interface - 'paper-column-interface - "" - - '(column-space-strength before-musical-spacing-factor -stem-spacing-correction before-grace-spacing-factor when bounded-by-me -dir-list shortest-playing-duration shortest-starter-duration -contains-grace extra-space stretch-distance )) - - - - (lily-interface - 'porrectus-interface - "A porrectus ligature, joining two note heads into a single grob." - '( - )) - - - (lily-interface - 'spaceable-element-interface - "An grob (generally a Paper_column) that takes part in the -spacing problem. " - '( - minimum-distances - ideal-distances - dir-list - )) - - - (lily-interface - 'rest-collision-interface - "Move around ordinary rests (not multi-measure-rests) to avoid -conflicts." - '( - maximum-rest-count - minimum-distance - elements - )) - - - (lily-interface - 'script-interface - "" - '( - script-priority - )) - - - (lily-interface - 'script-column-interface - "An interface that sorts scripts according to their @code{script-priority}" - '( )) - - - - (lily-interface - 'spacing-spanner-interface - " SPACE = arithmetic_multiplier * ( C + log2 (TIME) )) -The space taken by a note is determined by the formula - - - -where TIME is the amount of time a note occupies. The value of C is -chosen such that the smallest space within a measure is -arithmetic_basicspace: - -C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) - -The smallest space is the one following the shortest note in the -measure, or the space following a hypothetical 1/8 note. Typically -arithmetic_basicspace is set to a value so that the shortest note -takes about two noteheads of space (ie, is followed by a notehead of -space): - -@example -2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) )) - -@{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @} -@{ assuming: SHORTEST <= 1/8 @} - -= arithmetic_multiplier * -( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) ) - -= arithmetic_multiplier * arithmetic_basicspace - -@{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @} - -= quartwidth * arithmetic_basicspace - -=> - -arithmetic_basicspace = 2/1 = 2 - - -If you want to space your music wider, use something like: - -arithmetic_basicspace = 4.; - -@end example" - '( - maximum-duration-for-spacing - arithmetic-basicspace - arithmetic-multiplier - - )) - - - (lily-interface - 'staff-symbol-referencer-interface - - "Object whose Y position is meaning with reference to a staff -symbol. Objects that have this interface should include -Staff_symbol_referencer::callback in their Y-offset-callback. +Grob properties form a name space where you can set variables per +object. Each object however, may have multiple functions. For +example, consider a dynamic symbol, such @code{\ff} (fortissimo). It +is printed above or below the staff, it is a dynamic sign, and it is a +kind of text. + +To reflect this different functions of a grob, procedures and variables +are grouped into so-called interfaces. The dynamic text for example +supports the following interfaces: +@table @code +@item font-interface + The glyph is built from characters from a font, hence the +@code{font-interface}. For objects supporting @code{font-interface}, you +can select alternate fonts by setting @code{font-style}, +@code{font-point-size}, etc. + +@item dynamic-interface + Dynamic interface is not associated with any variable or function in +particular, but this makes it possible to distinguish this grob from +other similar grobs (like @code{TextScript}), that have no meaning of +dynamics. + +@item text-interface + This interface is for texts that are to be set using special routines +to stack text into lines, using kerning, etc. + +@item general-grob-interface + This interface is supported by all grob types. +@end table " - '( - staff-symbol - staff-position - )) - - - (lily-interface - 'staff-symbol-interface - "This spanner draws the lines of a staff. The middle line is -position 0." - '( - staff-space - line-count - invisible-staff - )) - - - (lily-interface - 'stem-tremolo-interface - "" - '( stem beam-width beam-thickness beam-space-function - )) - - - (lily-interface - 'separation-item-interface - "Item that computes widths to generate spacing rods. - -Calc dimensions for the Separating_group_spanner; this has to be -an item to get dependencies correct. It can't be an grob_group -since these usually are in a different X_group -" - '( - elements - )) - - - (lily-interface - 'sustain-pedal-interface - "" - '( - )) - - (lily-interface - 'system-start-delimiter-interface - "#'style can be bar-line, bracket or brace" - '(bar-line-collapse-height brace-collapse-height bracket-collapse-height - thickness arch-height arch-angle arch-thick - arch-width bracket-thick glyph )) - - - (lily-interface - 'text-spanner-interface - "generic text spanner" - '( - dash-period - dash-length - line-thickness - edge-height - edge-text - type -)) - - - (lily-interface - 'tie-interface - "A tie connecting two noteheads. -direction = Forced direction for all ties" - - '( - staffline-clearance - control-points - heads - details - thickness - x-gap - direction - minimum-length - )) - - - - - (lily-interface - 'tie-column-interface - "that sets tie directions in a tied chord" - '(direction - )) - -(lily-interface - 'percent-repeat-interface - "Repeats that look like percent signs" - '(slope thickness)) - -(lily-interface - 'volta-bracket-interface - "Volta bracket with number" - '( - bars - thickness - height - )) - - -(lily-interface - 'span-bar-interface - "A bar line that spans other barlines (typically used to get cross-staff barlines." - '( - )) - - -(primitive-eval (cons - 'begin - (map (lambda (x) (list 'define (car x) (list 'quote (cdr x)))) - all-interfaces))) - - -(define (interface-names) (map (lambda (x) (symbol->string (car x))) all-interfaces)) - -