X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=scm%2Fdefine-grob-properties.scm;h=acda4c25c3c7a787712fae306b685c2c637bde5f;hb=f1bb461ca8037b12343479b22d56bf96abe238b6;hp=25519bca80bda4f7bafa7b45a0ae7b78c88b1b45;hpb=a396a31d3d8df664dbadef65f0e807759d6b355e;p=lilypond.git diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm index 25519bca80..acda4c25c3 100644 --- a/scm/define-grob-properties.scm +++ b/scm/define-grob-properties.scm @@ -1,6 +1,6 @@ ;;;; This file is part of LilyPond, the GNU music typesetter. ;;;; -;;;; Copyright (C) 1998--2010 Han-Wen Nienhuys +;;;; Copyright (C) 1998--2011 Han-Wen Nienhuys ;;;; Jan Nieuwenhuizen ;;;; ;;;; LilyPond is free software: you can redistribute it and/or modify @@ -25,9 +25,7 @@ symbol) ;; put this in an alist? -(define-public - all-user-grob-properties - +(define-public all-user-grob-properties (map (lambda (x) (apply define-grob-property x)) @@ -40,7 +38,7 @@ included in this script's support.") (after-line-breaking ,boolean? "Dummy property, used to trigger callback for @code{after-line-breaking}.") - (align-dir ,ly:dir? "Which side to align? @code{-1}: left side, + (align-dir ,ly:dir? "Which side to align? @w{@code{-1}}: left side, @code{0}: around center of width, @code{1}: right side.") (allow-loose-spacing ,boolean? "If set, column can be detached from main spacing.") @@ -50,6 +48,9 @@ be created below this bar line.") (alteration-alist ,list? "List of @code{(@var{pitch} . @var{accidental})} pairs for key signature.") (annotation ,string? "Annotate a grob for debug purposes.") + (annotation-balloon ,boolean? "Print the balloon around an annotation.") + (annotation-line ,boolean? "Print the line from an annotation to the +grob that it annotates.") (arpeggio-direction ,ly:dir? "If set, put an arrow on the arpeggio squiggly line.") (arrow-length ,number? "Arrow length.") @@ -57,6 +58,8 @@ arpeggio squiggly line.") (auto-knee-gap ,ly:dimension? "If a gap is found between note heads where a horizontal beam fits that is larger than this number, make a kneed beam.") + (automatically-numbered ,boolean? "Should a footnote be automatically +numbered?") (average-spacing-wishes ,boolean? "If set, the spacing wishes are averaged over staves.") (avoid-note-head ,boolean? "If set, the stem of a chord does not @@ -77,7 +80,6 @@ grobs, this should contain only one number.") ;; ;; b ;; - (bar-size ,ly:dimension? "The size of a bar line.") (base-shortest-duration ,ly:moment? "Spacing is based on the shortest notes in a piece. Normally, pieces are spaced as if notes at least as short as this are present.") @@ -164,12 +166,16 @@ stick out of its bounds?") ;; (c0-position ,integer? "An integer indicating the position of middle@tie{}C.") - (circled-tip ,boolean? "Put a circle at start/end of -hairpins (al/del niente).") + (circled-tip ,boolean? "Put a circle at start/@/end of +hairpins (al/@/del niente).") (clip-edges ,boolean? "Allow outward pointing beamlets at the edges of beams?") (collapse-height ,ly:dimension? "Minimum height of system start -delimiter. If equal or smaller, the bracket/brace/line is removed.") +delimiter. If equal or smaller, the bracket/@/brace/@/line is removed.") + (collision-interfaces ,list? "A list of interfaces for which +automatic beam-collision resolution is run.") + (collision-voice-only ,boolean? "Does automatic beam collsion apply +only to the voice in which the beam was created?") (color ,color? "The color of this grob.") (common-shortest-duration ,ly:moment? "The most common shortest note length. This is used in spacing. Enlarging this sets the score @@ -180,11 +186,12 @@ measure of the closeness of the inner stems. It is used for damping the slope of the beam.") (connect-to-neighbor ,pair? "Pair of booleans, indicating whether this grob looks as a continued break.") + (consistent-broken-slope ,boolean? "Keep a beam's slope across line +breaks.") (control-points ,list? "List of offsets (number pairs) that form control points for the tie, slur, or bracket shape. For B@'eziers, this should list the control points of a third-order B@'ezier curve.") - ;; ;; d ;; @@ -210,13 +217,13 @@ looking at the top of the Internals Reference page for each interface having a @code{details} property.") (digit-names ,vector? "Names for string finger digits.") (direction ,ly:dir? "If @code{side-axis} is @code{0} (or -@code{#X}), then this property determines whether the object is placed -@code{#LEFT}, @code{#CENTER} or @code{#RIGHT} with respect to the +@code{X}), then this property determines whether the object is placed +@code{LEFT}, @code{CENTER} or @code{RIGHT} with respect to the other object. Otherwise, it determines whether the object is placed -@code{#UP}, @code{#CENTER} or @code{#DOWN}. Numerical values may also -be used: @code{#UP}=@code{1}, @code{#DOWN}=@code{-1}, -@code{#LEFT}=@code{-1}, @code{#RIGHT}=@code{1}, -@code{#CENTER}=@code{0}.") +@code{UP}, @code{CENTER} or @code{DOWN}. Numerical values may also +be used: @code{UP}=@code{1}, @code{DOWN}=@w{@code{-1}}, +@code{LEFT}=@w{@code{-1}}, @code{RIGHT}=@code{1}, +@code{CENTER}=@code{0}.") (dot-count ,integer? "The number of dots.") (dot-negative-kern ,number? "The space to remove between a dot and a slash in percent repeat glyphs. Larger values bring the two @@ -237,6 +244,11 @@ Positive means move the center to the right.") the vertical edges: @code{(@var{left-height} . @var{right-height})}.") (edge-text ,pair? "A pair specifying the texts to be set at the edges: @code{(@var{left-text} . @var{right-text})}.") + (elements-filtered ,boolean? "Callback to filter an element list.") + (round-up-exceptions ,list? "A list of pairs where car is the numerator +and cdr the denominator of a moment. Each pair in this list means that +the multi-measure rests of the corresponding length will be rounded up to +the longer rest. See @var{round-up-to-longer-rest}.") (expand-limit ,integer? "Maximum number of measures expanded in church rests.") ;; remove me? @@ -265,17 +277,7 @@ Y@tie{}dimension by this much.") ;; ;; f ;; - (flag ,ly:stencil? "A function returning the full flag stencil -for the @code{Stem}, which is passed to the function as the only -argument. The default ly:stem::calc-stencil function uses the -@code{flag-style} property to determine the correct glyph for the -flag. By providing your own function, you can create arbitrary -flags.") (flag-count ,number? "The number of tremolo beams.") - (flag-style ,symbol? "A symbol determining what style of flag -glyph is typeset on a @code{Stem}. Valid options include @code{'()} -for standard flags, @code{'mensural} and @code{'no-flag}, which -switches off the flag.") (font-encoding ,symbol? "The font encoding is the broadest category for selecting a font. Currently, only lilypond's system fonts (Emmentaler) are using this property. Available @@ -293,9 +295,10 @@ include @code{medium}, @code{bold}, @code{bold-narrow}, etc.") include @code{upright}, @code{italic}, @code{caps}.") (font-size ,number? "The font size, compared to the @q{normal}@tie{}size. @code{0}@tie{}is style-sheet's normal size, -@code{-1} is smaller, @code{+1} is bigger. Each step of@tie{}1 is +@w{@code{-1}} is smaller, @code{+1} is bigger. Each step of@tie{}1 is approximately 12% larger; 6@tie{}steps are exactly a factor@tie{}2 larger. Fractional values are allowed.") + (footnote-text ,markup? "A footnote for the grob.") (force-hshift ,number? "This specifies a manual shift for notes in collisions. The unit is the note head width of the first voice note. This is used by @rinternals{note-collision-interface}.") @@ -336,6 +339,10 @@ Default @code{none} for markup fret diagrams, @code{below-string} for @item @code{fret-count} -- The number of frets. Default@tie{}4. @item +@code{fret-label-custom-format} -- The format string to be used label +the lowest fret number, when @code{number-type} equals to +@code{custom}. Default@tie{}\"~a\". +@item @code{fret-label-font-mag} -- The magnification of the font used to label the lowest fret number. Default@tie{}0.5. @item @@ -344,14 +351,16 @@ the center of the fret in direction parallel to strings. Default@tie{}0. @item @code{label-dir} -- Side to which the fret label is attached. -@code{-1}, @code{#LEFT}, or @code{#DOWN} for left or down; @code{1}, -@code{#RIGHT}, or @code{#UP} for right or up. Default @code{#RIGHT}. +@w{@code{-1}}, @code{LEFT}, or @code{DOWN} for left or down; @code{1}, +@code{RIGHT}, or @code{UP} for right or up. Default @code{RIGHT}. @item @code{mute-string} -- Character string to be used to indicate muted string. Default @code{\"x\"}. @item @code{number-type} -- Type of numbers to use in fret label. Choices -include @code{roman-lower}, @code{roman-upper}, and @code{arabic}. +include @code{roman-lower}, @code{roman-upper}, @code{arabic} and +@code{custom}. In the later case, the format string is supplied by +the @code{fret-label-custom-format} property. Default @code{roman-lower}. @item @code{open-string} -- Character string to be used to indicate open @@ -399,6 +408,8 @@ read from the NonMusicalPaperColumn that begins the measure.") ;; (gap ,ly:dimension? "Size of a gap in a variable symbol.") (gap-count ,integer? "Number of gapped beams for tremolo.") + (glissando-skip ,boolean? "Should this @code{NoteHead} be skipped +by glissandi?") (glyph ,string? "A string determining what @q{style} of glyph is typeset. Valid choices depend on the function that is reading this property.") @@ -420,8 +431,8 @@ be included in harp-pedal-details include the following: @itemize @bullet @item -@code{box-offset} -- Vertical shift of the center of flat/sharp pedal -boxes above/below the horizontal line. Default value@tie{}0.8. +@code{box-offset} -- Vertical shift of the center of flat/@/sharp pedal +boxes above/@/below the horizontal line. Default value@tie{}0.8. @item @code{box-width} -- Width of each pedal box. Default value@tie{}0.4. @item @@ -492,10 +503,14 @@ objects. Objects with the lowest value of layer are drawn first, then objects with progressively higher values are drawn, so objects with higher values overwrite objects with lower values. By default most objects are assigned a layer value of 1.") + (ledger-extra ,ly:dimension? "Extra distance from staff line to draw ledger +lines for.") (ledger-line-thickness ,number-pair? "The thickness of ledger lines. It is the sum of 2@tie{}numbers: The first is the factor for line thickness, and the second for staff space. Both contributions are added.") + (ledger-positions ,list? "Repeating pattern for the vertical positions +of ledger lines. Bracketed groups are always shown together.") (left-bound-info ,list? "An alist of properties for determining attachments of spanners to edges.") (left-padding ,ly:dimension? "The amount of space that is put @@ -609,6 +624,9 @@ the nearest staff in the opposite direction from between the two, and @code{staff-affinity} is either @code{UP} or @code{DOWN}. See @code{staff-staff-spacing} for a description of the alist structure.") + (normalized-endpoints ,pair? "Represents left and right placement +over the total spanner, where the width of the spanner is normalized +between 0 and 1.") (note-names ,vector? "Vector of strings containing names for easy-notation note heads.") @@ -672,6 +690,9 @@ number, the quicker the slur attains its @code{height-limit}.") interesting items.") (remove-first ,boolean? "Remove the first staff of an orchestral score?") + (replacement-alist ,list? "Alist of strings. +The key is a string of the pattern to be replaced. The value is a +string of what should be displayed. Useful for ligatures.") (restore-first ,boolean? "Print a natural before the accidental.") (rhythmic-location ,rhythmic-location? "Where (bar number, @@ -681,8 +702,12 @@ attachments of spanners to edges.") (right-padding ,ly:dimension? "Space to insert on the right side of an object (e.g., between note and its accidentals).") (rotation ,list? "Number of degrees to rotate this object, and -what point to rotate around. For example, @code{#'(45 0 0)} rotates +what point to rotate around. For example, @code{'(45 0 0)} rotates by 45 degrees around the center of this object.") + (round-up-to-longer-rest ,boolean? "Displays the longer multi-measure +rest when the length of a measure is between two values of +@code{usable-duration-logs}. For example, displays a breve instead of a whole +in a 3/2 measure.") ;; @@ -695,7 +720,7 @@ stem distance.") (script-priority ,number? "A sorting key that determines in what order a script is within a stack of scripts.") (self-alignment-X ,number? "Specify alignment of an object. The -value @code{-1} means left aligned, @code{0}@tie{}centered, and +value @w{@code{-1}} means left aligned, @code{0}@tie{}centered, and @code{1}@tie{}right-aligned in X@tie{}direction. Other numerical values may also be specified.") (self-alignment-Y ,number? "Like @code{self-alignment-X} but for @@ -711,19 +736,27 @@ space for the shortest duration. This is expressed in shortest note playing here.") (shortest-starter-duration ,ly:moment? "The duration of the shortest note that starts here.") - (side-axis ,number? "If the value is @code{#X} (or + (side-axis ,number? "If the value is @code{X} (or equivalently@tie{}@code{0}), the object is placed horizontally next to -the other object. If the value is @code{#Y} or@tie{}@code{1}, it is +the other object. If the value is @code{Y} or@tie{}@code{1}, it is placed vertically.") (side-relative-direction ,ly:dir? "Multiply direction of @code{direction-source} with this to get the direction of this object.") + (simple-Y ,boolean? "Should the Y placement of a spanner +disregard changes in system heights?") (size ,number? "Size of object, relative to standard size.") + (skip-quanting ,boolean? "Should beam quanting be skipped?") (skyline-horizontal-padding ,number? "For determining the vertical distance between two staves, it is possible to have a configuration which would result in a tight interleaving of grobs from the top staff and the bottom staff. The larger this parameter is, the farther apart the staves are placed in such a configuration.") + (skyline-vertical-padding ,number? "The amount by which the left +and right skylines of a column are padded vertically, beyond the +@code{Y-extent}s and @code{extra-spacing-height}s of the constituent +grobs in the column. Increase this to prevent interleaving of grobs +from adjacent columns.") (slash-negative-kern ,number? "The space to remove between slashes in percent repeat glyphs. Larger values bring the two elements closer together.") @@ -751,8 +784,10 @@ bounds (i.e., clefs, key signatures and time signatures) using the following override: @example -\\override MultiMeasureRest #'spacing-pair = #'(staff-bar . staff-bar) +\\override MultiMeasureRest + #'spacing-pair = #'(staff-bar . staff-bar) @end example") + (spanner-id ,string? "An identifier to distinguish concurrent spanners.") (springs-and-rods ,boolean? "Dummy variable for triggering spacing routines.") (stacking-dir ,ly:dir? "Stack objects in which direction?") @@ -781,20 +816,30 @@ same system, replacing any settings inherited from the @code{StaffGrouper} grob of the containing staff-group, if there is one. This property remains in effect even when non-staff lines appear between staves. The alist can contain the following keys: + @itemize -@item @code{padding} -- the minimum required amount of -unobstructed vertical whitespace between the two items, measured -in staff-spaces. -@item @code{space} -- the vertical distance, measured in + +@item +@code{basic-distance} -- the vertical distance, measured in staff-spaces, between the reference points of the two items when no collisions would result, and no stretching or compressing is in effect. -@item @code{minimum-distance} -- the smallest allowable vertical + +@item +@code{minimum-distance} -- the smallest allowable vertical distance, measured in staff-spaces, between the reference points of the two items, when compressing is in effect. -@item @code{stretchability} -- a unitless measure of the -dimension's relative propensity to stretch. If zero, the distance -will not stretch (unless collisions would result). + +@item +@code{padding} -- the minimum required amount of unobstructed +vertical whitespace between the bounding boxes (or skylines) of +the two items, measured in staff-spaces. + +@item +@code{stretchability} -- a unitless measure of the dimension's +relative propensity to stretch. If zero, the distance will not +stretch (unless collisions would result). + @end itemize") (staffgroup-staff-spacing ,list? "The spacing alist controlling the distance between the last staff of the current @@ -806,8 +851,8 @@ the @code{staff-staff-spacing} property of the staff's structure.") (stem-attachment ,number-pair? "An @code{(@var{x} . @var{y})} pair where the stem attaches to the notehead.") - (stem-end-position ,number? "Where does the stem end (the end is -opposite to the support-head)?") + (stem-begin-position ,number? "User override for the +begin position of a stem.") ;;[TODO: doco] (stem-spacing-correction ,number? "Optical correction amount for stems that are placed in tight configurations. For opposite @@ -848,7 +893,7 @@ should use @code{LEFT}.") @var{dir})} pairs, indicating the desired tie configuration, where @var{position} is the offset from the center of the staff in staff space and @var{dir} indicates the direction of the tie -(@code{1}=>up, @code{-1}=>down, @code{0}=>center). A non-pair entry +(@code{1}=>up, @w{@code{-1}}=>down, @code{0}=>center). A non-pair entry in the list causes the corresponding tie to be formatted automatically.") (to-barline ,boolean? "If true, the spanner will stop at the bar @@ -869,7 +914,10 @@ proportionally to their durations. This looks better in complex polyphonic patterns.") (used ,boolean? "If set, this spacing column is kept in the spacing problem.") - + (usable-duration-logs ,list? "List of @code{duration-log}s that +can be used in typesetting the grob.") + (use-skylines ,boolean? "Should skylines be used for side +positioning?") ;; ;; v @@ -898,6 +946,9 @@ texts.") (X-extent ,number-pair? "Hard coded extent in X@tie{}direction.") (X-offset ,number? "The horizontal amount that this object is moved relative to its X-parent.") + (X-positions ,number-pair? "Pair of X staff coordinates of a spanner +in the form @code{(@var{left} . @var{right})}, where both @var{left} and +@var{right} are in @code{staff-space} units of the current staff.") ;; @@ -951,17 +1002,22 @@ function is to protect objects from being garbage collected.") (bars ,ly:grob-array? "An array of bar line pointers.") (beam ,ly:grob? "A pointer to the beam, if applicable.") + (bound-alignment-interfaces ,list "Interfaces to be used +for positioning elements that align with a column.") (bounded-by-me ,ly:grob-array? "An array of spanners that have this -column as start/begin point. Only columns that have grobs or act as +column as start/@/begin point. Only columns that have grobs or act as bounds are spaced.") (bracket ,ly:grob? "The bracket for a number.") (columns ,ly:grob-array? "An array of grobs, typically containing @code{PaperColumn} or @code{NoteColumn} objects.") (conditional-elements ,ly:grob-array? "Internal use only.") + (covered-grobs ,ly:grob-array? "Grobs that could potentially collide +with a beam.") (direction-source ,ly:grob? "In case @code{side-relative-direction} is set, which grob to get the direction from.") + (display-cautionary ,boolean? "Should the grob be displayed as a cautionary grob?") (dot ,ly:grob? "A reference to a @code{Dots} object.") (dots ,ly:grob-array? "Multiple @code{Dots} objects.") @@ -971,7 +1027,10 @@ the grob where this is set in.") in addition to notes and stems.") (figures ,ly:grob-array? "Figured bass objects for continuation line.") + (flag ,ly:grob? "A pointer to a @code{Flag} object.") + (glissando-index ,integer? "The index of a glissando in its note +column.") (grace-spacing ,ly:grob? "A run of grace notes.") (heads ,ly:grob-array? "An array of note heads.") @@ -1013,6 +1072,15 @@ grobs.") (spacing ,ly:grob? "The spacing spanner governing this section.") (spacing-wishes ,ly:grob-array? "An array of note spacing or staff spacing objects.") + (span-start ,boolean? "Is the note head at the start of a spanner?") + (spanner-broken ,boolean? "Indicates whether spanner +alignment should be broken after the current spanner.") + (spanner-placement ,ly:dir? "The place of an annotation on a spanner. +@code{LEFT} is for the first spanner, and @code{RIGHT} is for the last. +@code{CENTER} will place it on the broken spanner that falls closest to the +center of the length of the entire spanner, although this behavior is +unpredictable in situations with lots of rhythmic diversity. For predictable +results, use @code{LEFT} and @code{RIGHT}.") (staff-grouper ,ly:grob? "The staff grouper we belong to.") (staff-symbol ,ly:grob? "The staff symbol grob that we are in.") (stem ,ly:grob? "A pointer to a @code{Stem} object.") @@ -1071,9 +1139,6 @@ did its job. This ensures that a positioning is only done once.") (pure-Y-extent ,number-pair? "The estimated height of a system.") (pure-Y-offset-in-progress ,boolean? "A debugging aid for catching cyclic dependencies.") - - (quant-score ,string? "The beam quanting score; stored for -debugging.") (quantize-position ,boolean? "If set, a vertical alignment is aligned to be within staff spaces.") (quantized-positions ,number-pair? "The beam positions after @@ -1087,8 +1152,6 @@ Internally used to distribute beam shortening over stems.") (system-Y-offset ,number? "The Y-offset (relative to the bottom of the top-margin of the page) of the system to which this staff belongs.") - (use-breve-rest ,boolean? "Use breve rests for measures longer -than a whole rest.") ;;;;;;;;;;;;;;;; ;; ancient notation @@ -1114,7 +1177,7 @@ an additional stem on the right side?") (cavum ,boolean? "Is this neume outlined?") (context-info ,integer? "Within a ligature, the final glyph or shape of -a head may be affected by the left and/or right neighbour head. +a head may be affected by the left and/@/or right neighbour head. @code{context-info} holds for each head such information about the left and right neighbour, encoded as a bit mask.") @@ -1123,13 +1186,15 @@ right neighbour, encoded as a bit mask.") (flexa-height ,ly:dimension? "The height of a flexa shape in a ligature grob (in @code{staff-space} units).") + (flexa-interval ,integer? "The interval spanned by the two notes of a +flexa shape (1 is a second, 7 is an octave).") (flexa-width ,ly:dimension? "The width of a flexa shape in a ligature grob in (in @code{staff-space} units).") + (ligature-flexa ,boolean? "request joining note to the previous one +in a flexa.") (inclinatum ,boolean? "Is this neume an inclinatum?") - (join-right-amount ,number? "A length used for calculating the -Y-extent of mensural ligatures.") (linea ,boolean? "Attach vertical lines to this neume?")