X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=scm%2Fdefine-grob-properties.scm;h=0acc741f1cb93ad13ffa151b8fafc745df9037f0;hb=8cf69a467ad7650f5ca9da6fe2dfd4c7c088b239;hp=8fae43bcd121026770270c4b411ce3e2ffc289a4;hpb=25ec4326eff24ced1d02aa1abea83bae155f02fd;p=lilypond.git diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm index 8fae43bcd1..0acc741f1c 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--2012 Han-Wen Nienhuys +;;;; Copyright (C) 1998--2015 Han-Wen Nienhuys ;;;; Jan Nieuwenhuizen ;;;; ;;;; LilyPond is free software: you can redistribute it and/or modify @@ -125,43 +125,47 @@ visibility of the tuplet bracket. Setting it to false prevents printing of the bracket. Setting the property to @code{if-no-beam} makes it print only if there is no beam associated with this tuplet bracket.") - (break-align-anchor ,number? "Grobs aligned to this break-align -grob will have their X-offsets shifted by this number. In bar lines, + (break-align-anchor ,number? "Grobs aligned to this breakable +item will have their X-offsets shifted by this number. In bar lines, for example, this is used to position grobs relative to the (visual) center of the bar line.") (break-align-anchor-alignment ,number? "Read by @code{ly:break-aligned-interface::calc-extent-aligned-anchor} for aligning an anchor to a grob's extent.") - (break-align-orders ,vector? "Defines the order in which -prefatory matter (clefs, key signatures) appears. The format is a -vector of length@tie{}3, where each element is one order for -end-of-line, middle of line, and start-of-line, respectively. An -order is a list of symbols. + (break-align-orders ,vector? "This is a vector of 3@tie{}lists: +@w{@code{#(@var{end-of-line} @var{unbroken} @var{start-of-line}}}). +Each list contains @w{@emph{break-align symbols}} that specify an +order of breakable items (see @rinternals{break-alignment-interface}). -For example, clefs are put after key signatures by setting +For example, this places time signatures before clefs: @example -\\override Score.BreakAlignment #'break-align-orders = - #(make-vector 3 '(span-bar +\\override Score.BreakAlignment.break-align-orders = + #(make-vector 3 '(left-edge + cue-end-clef + ambitus breathing-sign - staff-bar - key + time-signature clef - time-signature)) + cue-clef + staff-bar + key-cancellation + key-signature + custos)) @end example") - (break-align-symbol ,symbol? "This key is used for aligning and -spacing breakable items.") - (break-align-symbols ,list? "A list of symbols that determine -which break-aligned grobs to align this to. If the grob selected by -the first symbol in the list is invisible due to break-visibility, we -will align to the next grob (and so on). Choices are @code{left-edge}, -@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{staff-bar}, -@code{key-cancellation}, @code{key-signature}, @code{time-signature}, -and @code{custos}.") + (break-align-symbol ,symbol? "This key is used for aligning, +ordering, and spacing breakable items. See +@rinternals{break-alignment-interface}.") + (break-align-symbols ,list? "A list of +@w{@emph{break-align symbols}} that determines which breakable +items to align this to. If the grob selected by the first symbol +in the list is invisible due to @w{@code{break-visibility}}, we +will align to the next grob (and so on). Choices are listed in +@rinternals{break-alignment-interface}.") (break-overshoot ,number-pair? "How much does a broken spanner stick out of its bounds?") (break-visibility ,vector? "A vector of 3@tie{}booleans, -@code{#(@var{end-of-line} @var{unbroken} @var{begin-of-line})}. +@w{@code{#(@var{end-of-line} @var{unbroken} @var{begin-of-line})}}. @code{#t} means visible, @code{#f} means killed.") (breakable ,boolean? "Allow breaks here.") (broken-bound-padding ,number? "The amount of padding to insert @@ -175,17 +179,14 @@ on each chord to the height of the chord plus @code{chord-dots-limit} staff-positions.") (circled-tip ,boolean? "Put a circle at start/@/end of hairpins (al/@/del niente).") + (clef-alignments ,list? "An alist of parent-alignments +that should be used for clef modifiers with various clefs") (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.") - (collision-bias ,number? "Number determining how much to favor the -left (negative) or right (positive). Larger absolute values in either -direction will push a collision in this direction.") (collision-interfaces ,list? "A list of interfaces for which automatic beam-collision resolution is run.") - (collision-padding ,number? "Amount of padding to apply after -a collision is detected via the self-alignment-interface.") (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.") @@ -198,7 +199,7 @@ 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.") - (control-points ,list? "List of offsets (number pairs) that form + (control-points ,number-pair-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.") (count-from ,integer? "The first measure in a measure count @@ -213,8 +214,9 @@ increments from this initial value.") dash structure. Each @code{dash-element} has a starting t value, an ending t-value, a @code{dash-fraction}, and a @code{dash-period}.") (dash-fraction ,number? "Size of the dashes, relative to -@code{dash-period}. Should be between @code{0.0} (no line) and -@code{1.0} (continuous line).") +@code{dash-period}. Should be between @code{0.1} and +@code{1.0} (continuous line). If set to @code{0.0}, a dotted line is +produced") (dash-period ,number? "The length of one dash together with whitespace. If negative, no line is drawn at all.") (default-direction ,ly:dir? "Direction determined by note head @@ -244,6 +246,11 @@ elements closer together.") (dot-placement-list ,list? "List consisting of @code{(@var{description} @var{string-number} @var{fret-number} @var{finger-number})} entries used to define fret diagrams.") + (double-stem-separation ,number? "The distance between the two +stems of a half note in tablature when using @code{\\tabFullNotation}, +not counting the width of the stems themselves, expressed as a multiple +of the default height of a staff-space in the traditional five-line +staff.") (duration-log ,integer? "The 2-log of the note head duration, i.e., @code{0} = whole note, @code{1} = half note, etc.") @@ -317,7 +324,10 @@ include @code{upright}, @code{italic}, @code{caps}.") @q{normal}@tie{}size. @code{0}@tie{}is style-sheet's normal size, @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.") +larger. If the context property @code{fontSize} is set, its value is +added to this before the glyph is printed. Fractional values are +allowed.") + (font-features ,list? "Opentype features.") (footnote ,boolean? "Should this be a footnote or in-note?") (footnote-music ,ly:music? "Music creating a footnote.") (footnote-text ,markup? "A footnote for the grob.") @@ -363,6 +373,9 @@ 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-distance} -- Multiplier to adjust the distance between frets. +Default@tie{}1.0. +@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\". @@ -374,6 +387,13 @@ label the lowest fret number. Default@tie{}0.5. the center of the fret in direction parallel to strings. Default@tie{}0. @item +@code{fret-label-horizontal-offset} -- The offset of the fret label from +the center of the fret in direction orthogonal to strings. +Default@tie{}0. +@item +@code{paren-padding} -- The padding for the parenthesis. +Default@tie{}0.05. +@item @code{label-dir} -- Side to which the fret label is attached. @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}. @@ -396,6 +416,9 @@ Default @code{normal}. @item @code{string-count} -- The number of strings. Default@tie{}6. @item +@code{string-distance} -- Multiplier to adjust the distance between strings. +Default@tie{}1.0. +@item @code{string-label-font-mag} -- The magnification of the font used to label fingerings at the string, rather than in the dot. Default value 0.6 for @code{normal} orientation, 0.5 for @code{landscape} and @@ -454,7 +477,9 @@ etc. are already taken.") ;;; h ;;; (hair-thickness ,number? "Thickness of the thin line in a bar -line.") +line, expressed as a multiple of the default staff-line +thickness (i.e. the visual output is @emph{not} influenced by changes +to @code{@var{Staff}.StaffSymbol.thickness}).") (harp-pedal-details ,list? "An alist of detailed grob properties for harp pedal diagrams. Each alist entry consists of a @code{(@var{property} . @var{value})} pair. The properties which can @@ -506,13 +531,9 @@ left and one to the right of this grob.") ;;; ;;; i ;;; - (id ,string? "An id string for the grob. Depending on the typestting -backend being used, this id will be assigned to a group containing all of -the stencils that comprise a given grob. For example, in the svg backend, -the string will be assigned to the @code{id} attribute of a group () -that encloses the stencils that comprise the grob. In the Postscript -backend, as there is no way to group items, the setting of the id property -will have no effect.") + (id ,string? "An id string for the grob.") + (ignore-ambitus ,boolean? "If set, don't consider this notehead +for ambitus calculation.") (ignore-collision ,boolean? "If set, don't do note collision resolution on this @code{NoteColumn}.") (implicit ,boolean? "Is this an implicit bass figure?") @@ -527,12 +548,17 @@ slur quants to this position, and print the respective scores.") ;;; (keep-inside-line ,boolean? "If set, this column cannot have objects sticking into the margin.") - (kern ,ly:dimension? "Amount of extra white space to add. For -bar lines, this is the amount of space after a thick line.") + (kern ,ly:dimension? "The space between individual elements +in any compound bar line, expressed as a multiple of the default +staff-line thickness (i.e. the visual output is @emph{not} +influenced by changes to +@code{@var{Staff}.StaffSymbol.thickness}).") (knee ,boolean? "Is this beam kneed?") (knee-spacing-correction ,number? "Factor for the optical correction amount for kneed beams. Set between @code{0} for no correction and @code{1} for full correction.") + (knee-to-beam ,boolean? "Determines whether a tuplet number +will be positioned next to a kneed beam.") ;;; @@ -550,8 +576,13 @@ lines for.") 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.") + (ledger-positions ,list? "Vertical positions of ledger lines. +When set on a @code{StaffSymbol} grob it defines a repeating +pattern of ledger lines and any parenthesized groups will always be +shown together.") + (ledger-positions-function ,scheme? "A quoted Scheme procedure that +takes a @code{StaffSymbol} grob and the vertical position of a note head +as arguments and returns a list of ledger line positions.") (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 @@ -571,8 +602,12 @@ whether to put a line break at this column. Can be @code{force} or if this column is the start of a system.") (line-count ,integer? "The number of staff lines.") (line-positions ,list? "Vertical positions of staff lines.") - (line-thickness ,number? "The thickness of the tie or slur -contour.") + (line-thickness ,number? "For slurs and ties, this is the +diameter of the virtual @qq{pen} that draws the two arcs of the +curve's outline, which intersect at the endpoints. This property is +expressed as a multiple of the current staff-line thickness (i.e. the +visual output is influenced by changes to +@code{@var{Staff}.StaffSymbol.thickness}).") (long-text ,markup? "Text markup. See @ruser{Formatting text}.") @@ -581,11 +616,10 @@ contour.") ;;; (max-beam-connect ,integer? "Maximum number of beams to connect to beams from this stem. Further beams are typeset as beamlets.") - (max-stretch ,number? "The maximum amount that this -@code{VerticalAxisGroup} can be vertically stretched (for example, in -order to better fill a page).") (maximum-gap ,number? "Maximum value allowed for @code{gap} property.") + (max-symbol-separation ,number? "The maximum distance between +symbols making up a church rest.") (measure-count ,integer? "The number of measures for a multi-measure rest.") (measure-length ,ly:moment? "Length of a measure. Used in some @@ -611,6 +645,11 @@ this long, normally in the horizontal direction. This requires an appropriate callback for the @code{springs-and-rods} property. If added to a @code{Tie}, this sets the minimum distance between noteheads.") + (minimum-length-after-break ,ly:dimension? "If set, try to make +a broken spanner starting a line this long. This requires an +appropriate callback for the @code{springs-and-rods} property. If +added to a @code{Tie}, this sets the minimum distance to the +notehead.") (minimum-length-fraction ,number? "Minimum length of ledger line as fraction of note head size.") (minimum-space ,ly:dimension? "Minimum distance that the victim @@ -639,7 +678,7 @@ object.") get stems extending to the middle staff line.") (non-break-align-symbols ,list? "A list of symbols that determine which NON-break-aligned interfaces to align this to.") - (non-default ,boolean? "Set for manually specified clefs.") + (non-default ,boolean? "Set for manually specified clefs and keys.") (non-musical ,boolean? "True if the grob belongs to a @code{NonMusicalPaperColumn}.") (nonstaff-nonstaff-spacing ,list? "The spacing alist @@ -672,11 +711,26 @@ 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.") + (note-collision-threshold ,ly:dimension? "Simultaneous notes that +are this close or closer in units of @code{staff-space} will be +identified as vertically colliding. Used by @code{Stem} grobs for notes +in the same voice, and @code{NoteCollision} grobs for notes in +different voices. Default value@tie{}1.") + (number-type ,symbol? "Numbering style. Choices include +@code{roman-lower}, @code{roman-upper} and @code{arabic}.") ;;; ;;; o ;;; + (output-attributes ,list? "An alist of attributes for the grob, to +be included in output files. When the SVG typesetting backend is used, +the attributes are assigned to a group () containing all of the +stencils that comprise a given grob. For example, +@code{'((id . 123) (class . foo) (data-whatever . @qq{bar}))} will produce +@code{ @dots{} }. +In the Postscript backend, where there is no way to group items, the +setting of the output-attributes property will have no effect.") (outside-staff-horizontal-padding ,number? "By default, an outside-staff-object can be placed so that is it very close to another grob horizontally. If this property is set, the outside-staff-object @@ -732,6 +786,19 @@ at a column with a negative penalty.") (page-turn-permission ,symbol? "Instructs the page breaker on whether to put a page turn at this column. Can be @code{force} or @code{allow}.") + (parent-alignment-X ,number? "Specify on which point +of the parent the object is aligned. The value @w{@code{-1}} means +aligned on parent's left edge, @code{0}@tie{}on@tie{}center, and +@code{1}@tie{}right edge, in X@tie{}direction. Other numerical +values may also be specified - the unit is half the parent's width. +If unset, the value from @code{self-alignment-X} property will be +used.") + (parent-alignment-Y ,number? "Like @code{parent-alignment-X} +but for the Y@tie{}axis.") + (parenthesis-friends ,list? "A list of Grob types, as symbols. +When parentheses enclose a Grob that has 'parenthesis-friends, the +parentheses widen to include any child Grobs with type among +'parenthesis-friends.") (parenthesized ,boolean? "Parenthesize this grob.") (positions ,number-pair? "Pair of staff coordinates @code{(@var{left} . @var{right})}, where both @var{left} and @@ -753,6 +820,16 @@ number, the quicker the slur attains its @code{height-limit}.") interesting items.") (remove-first ,boolean? "Remove the first staff of an orchestral score?") + (remove-layer ,key? "When set as a positive integer, the +@code{Keep_alive_together_engraver} removes all +@code{VerticalAxisGroup} grobs with a @code{remove-layer} larger than +the smallest retained @code{remove-layer}. Set to @code{#f} to make a +layer independent of the @code{Keep_alive_together_engraver}. Set to +@code{'()}, the layer does not participate in the layering decisions. +The property can also be set as a symbol for common behaviors: +@code{#'any} to keep the layer alive with any other layer in the +group; @code{#'above} or @code{#'below} to keep the layer alive with +the context immediately before or after it, respectively.") (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.") @@ -785,12 +862,20 @@ stem distance.") scripts in a stack, by being added to the position of the script in the user input, the sum being the overall priority. Smaller means closer to the head.") + (segno-kern ,number? "The space between the two thin lines +of the segno bar line symbol, expressed as a multiple of the +default staff-line thickness (i.e. the visual output is @emph{not} +influenced by changes to +@code{@var{Staff}.StaffSymbol.thickness}).") (self-alignment-X ,number? "Specify alignment of an object. The 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.") +values may also be specified - the unit is half the object width.") (self-alignment-Y ,number? "Like @code{self-alignment-X} but for the Y@tie{}axis.") + (shape ,symbol? "This setting determines what shape a grob +has. Valid choices depend on the @code{stencil} callback reading +this property.") (sharp-positions ,list? "Sharps in key signatures are placed within the specified ranges of staff-positions. The general form is a list of pairs, with one pair for each type of clef, in order @@ -799,12 +884,12 @@ of the staff-position at which each clef places C: If the list contains a single element it applies for all clefs. A single number in place of a pair sets accidentals within the octave ending at that staff-position.") - (shorten-pair ,number-pair? "The lengths to shorten a -text-spanner on both sides, for example a pedal bracket. Positive -values shorten the text-spanner, while negative values lengthen it.") - (shortest-duration-space ,ly:dimension? "Start with this much -space for the shortest duration. This is expressed in -@code{spacing-increment} as unit. See also + (shorten-pair ,number-pair? "The lengths to shorten on both sides +a hairpin or text-spanner such as a pedal bracket. Positive values +shorten the hairpin or text-spanner, while negative values lengthen +it.") + (shortest-duration-space ,number? "Start with this multiple of +@code{spacing-increment} space for the shortest duration. See also @rinternals{spacing-spanner-interface}.") (shortest-playing-duration ,ly:moment? "The duration of the shortest note playing here.") @@ -819,7 +904,8 @@ placed vertically.") 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.") + (size ,number? "The ratio of the size of the object to its default +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 @@ -838,19 +924,78 @@ elements closer together.") (slur-padding ,number? "Extra distance between slur and script.") (snap-radius ,number? "The maximum distance between two objects that will cause them to snap to alignment along an axis.") - (space-alist ,list? "A table that specifies distances between -prefatory items, like clef and time-signature. The format is an alist -of spacing tuples: @code{(@var{break-align-symbol} @var{type} -. @var{distance})}, where @var{type} can be the symbols -@code{minimum-space} or @code{extra-space}.") + (space-alist ,list? "An alist that specifies distances from this +grob to other breakable items, using the format: + +@example +'((@var{break-align-symbol} . (@var{spacing-style} . @var{space})) + (@var{break-align-symbol} . (@var{spacing-style} . @var{space})) + ...) +@end example + +Standard choices for @w{@code{@var{break-align-symbol}}} are listed in +@rinternals{break-alignment-interface}. Additionally, three special +@w{break-align} symbols available to @w{@code{space-alist}} are: + +@quotation +@table @code +@item first-note +used when the grob is just left of the first note on a line + +@item next-note +used when the grob is just left of any other note; +if not set, the value of @code{first-note} gets used + +@item right-edge +used when the grob is the last item on the line (only compatible with +the @w{@code{extra-space}} spacing style) +@end table +@end quotation + +Choices for @code{@var{spacing-style}} are: + +@quotation +@table @code +@item extra-space +Put this much space between the two grobs. The space is stretchable +when paired with @w{@code{first-note}} or @w{@code{next-note}}; +otherwise it is fixed. + +@item minimum-space +Put at least this much space between the left sides of both grobs, +without allowing them to collide. The space is stretchable when paired +with @w{@code{first-note}} or @w{@code{next-note}}; otherwise it +is fixed. Not compatible with @w{@code{right-edge}}. + +@item fixed-space +Only compatible with @w{@code{first-note}} and +@w{@code{next-note}}. Put this much fixed space between the grob +and the note. + +@item minimum-fixed-space +Only compatible with @w{@code{first-note}} and +@w{@code{next-note}}. Put at least this much fixed space between +the left side of the grob and the left side of the note, without +allowing them to collide. + +@item semi-fixed-space +Only compatible with @w{@code{first-note}} and +@w{@code{next-note}}. Put this much space between the grob and +the note, such that half of the space is fixed and half is +stretchable. +@end table +@end quotation + +Rules for this spacing are much more complicated than this. +See [Wanske] page 126--134, [Ross] page 143--147.") (space-to-barline ,boolean? "If set, the distance between a note and the following non-musical column will be measured to the bar line instead of to the beginning of the non-musical column. If there is a clef change followed by a bar line, for example, this means that we will try to space the non-musical column as though the clef is not there.") - (spacing-increment ,number? "Add this much space for a doubled -duration. Typically, the width of a note head. See also + (spacing-increment ,ly:dimension? "The unit of length for +note-spacing. Typically, the width of a note head. See also @rinternals{spacing-spanner-interface}.") (spacing-pair ,pair? "A pair of alignment symbols which set an object's spacing relative to its left and right @code{BreakAlignment}s. @@ -863,7 +1008,7 @@ override: \\override MultiMeasureRest #'spacing-pair = #'(staff-bar . staff-bar) @end example") - (spanner-id ,string? "An identifier to distinguish concurrent spanners.") + (spanner-id ,key? "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?") @@ -960,11 +1105,17 @@ this property.") (text-direction ,ly:dir? "This controls the ordering of the words. The default @code{RIGHT} is for roman text. Arabic or Hebrew should use @code{LEFT}.") - (thick-thickness ,number? "Bar line thickness, measured in -@code{line-thickness}.") - (thickness ,number? "Line thickness, generally measured in -@code{line-thickness}.") - (thin-kern ,number? "The space after a hair-line in a bar line.") + (thick-thickness ,number? "Thickness of the thick line in a +bar line, expressed as a multiple of the default staff-line +thickness (i.e. the visual output is @emph{not} influenced by +changes to @code{@var{Staff}.StaffSymbol.thickness}).") + (thickness ,number? "For grobs made up of lines, this is the +thickness of the line. For slurs and ties, this is the distance +between the two arcs of the curve's outline at its thickest point, +not counting the diameter of the virtual @qq{pen} that draws the +arcs. This property is expressed as a multiple of the current +staff-line thickness (i.e. the visual output is influenced by +changes to @code{@var{Staff}.StaffSymbol.thickness}).") (tie-configuration ,list? "List of @code{(@var{position} . @var{dir})} pairs, indicating the desired tie configuration, where @var{position} is the offset from the center of the staff in staff @@ -976,9 +1127,15 @@ automatically.") line just before it would otherwise stop.") (toward-stem-shift ,number? "Amount by which scripts are shifted toward the stem if their direction coincides with the stem direction. -@code{0.0} means keep the default position (centered on the note -head), @code{1.0} means centered on the stem. Interpolated values are -possible.") +@code{0.0} means centered on the note head (the default position of +most scripts); @code{1.0} means centered on the stem. Interpolated +values are possible.") + (toward-stem-shift-in-column ,number? "Amount by which a script +is shifted toward the stem if its direction coincides with the stem +direction and it is associated with a @code{ScriptColumn} object. +@code{0.0} means centered on the note head (the default position of +most scripts); @code{1.0} means centered on the stem. Interpolated +values are possible.") (transparent ,boolean? "This makes the grob invisible.") @@ -986,8 +1143,8 @@ possible.") ;;; u ;;; (uniform-stretching ,boolean? "If set, items stretch -proportionally to their durations. This looks better in complex -polyphonic patterns.") +proportionally to their natural separation based on 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 @@ -1000,15 +1157,26 @@ positioning?") ;;; (vertical-skylines ,ly:skyline-pair? "Two skylines, one above and one below this grob.") + (voiced-position ,number? "The staff-position of a voiced +@code{Rest}, negative if the rest has @code{direction} @code{DOWN}.") ;;; ;;; w ;;; - (when ,ly:moment? "Global time step associated with this column -happen?") - (whiteout ,boolean? "If true, the grob is printed over a white -background to white-out underlying material, if the grob is visible. - Usually #f by default.") + (when ,ly:moment? "Global time step associated with this column.") + (whiteout ,boolean-or-number? "If a number or true, the grob is +printed over a white background to white-out underlying material, if +the grob is visible. A number indicates how far the white background +extends beyond the bounding box of the grob as a multiple of the +staff-line thickness. The @code{LyricHyphen} grob uses a special +implementation of whiteout: A positive number indicates how far the +white background extends beyond the bounding box in multiples of +@code{line-thickness}. The shape of the background is determined by +@code{whiteout-style}. Usually @code{#f} by default. ") + (whiteout-style ,symbol? "Determines the shape of the +@code{whiteout} background. Available are @code{'outline}, +@code{'rounded-box}, and the default @code{'box}. There is one +exception: Use @code{'special} for @code{LyricHyphen}.") (width ,ly:dimension? "The width of a grob measured in staff space.") (word-space ,ly:dimension? "Space to insert between words in @@ -1018,7 +1186,10 @@ texts.") ;;; ;;; x ;;; - (X-extent ,number-pair? "Hard coded extent in X@tie{}direction.") + (X-align-on-main-noteheads ,boolean? "If true, this grob will +ignore suspended noteheads when aligning itself on NoteColumn.") + (X-extent ,number-pair? "Extent (size) in the X@tie{}direction, +measured in staff-space units, relative to object's reference point.") (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 @@ -1029,7 +1200,8 @@ in the form @code{(@var{left} . @var{right})}, where both @var{left} and ;;; ;;; y ;;; - (Y-extent ,number-pair? "Hard coded extent in Y@tie{}direction.") + (Y-extent ,number-pair? "Extent (size) in the Y@tie{}direction, +measured in staff-space units, relative to object's reference point.") (Y-offset ,number? "The vertical amount that this object is moved relative to its Y-parent.") @@ -1083,6 +1255,7 @@ for positioning elements that align with a column.") column as start/@/begin point. Only columns that have grobs or act as bounds are spaced.") (bracket ,ly:grob? "The bracket for a number.") + (bracket-text ,ly:grob? "The text for an analysis bracket.") (c0-position ,integer? "An integer indicating the position of middle@tie{}C.") @@ -1130,10 +1303,13 @@ empty in a particular staff, then that staff is erased.") (keep-alive-with ,ly:grob-array? "An array of other @code{VerticalAxisGroup}s. If any of them are alive, then we will stay alive.") - (left-items ,ly:grob-array? "DOCME") + (left-items ,ly:grob-array? "Grobs organized on the left by a spacing +object.") (left-neighbor ,ly:grob? "The right-most column that has a spacing-wish for this column.") + (make-dead-when ,ly:grob-array? "An array of other +@code{VerticalAxisGroup}s. If any of them are alive, then we will turn dead.") (melody-spanner ,ly:grob? "The @code{MelodyItem} object for a stem.") (minimum-translations-alist ,list? "An list of translations for a given start and end point.") @@ -1147,8 +1323,6 @@ pure-from-neighbor-interface to determine various grob heights.") (note-heads ,ly:grob-array? "An array of note head grobs.") (pedal-text ,ly:grob? "A pointer to the text of a mixed-style piano pedal.") - (potential-X-colliding-grobs ,ly:grob-array? "Grobs that can potentially -collide with a self-aligned grob on the X-axis.") (pure-relevant-grobs ,ly:grob-array? "All the grobs (items and spanners) that are relevant for finding the @code{pure-Y-extent}") (pure-relevant-items ,ly:grob-array? "A subset of elements that are @@ -1161,13 +1335,18 @@ relevant for finding the @code{pure-Y-extent}.") (rest ,ly:grob? "A pointer to a @code{Rest} object.") (rest-collision ,ly:grob? "A rest collision that a rest is in.") (rests ,ly:grob-array? "An array of rest objects.") - (right-items ,ly:grob-array? "DOCME") + (right-items ,ly:grob-array? "Grobs organized on the right by +a spacing object.") (right-neighbor ,ly:grob? "See @code{left-neighbor}.") + (scripts ,ly:grob-array? "An array of @code{Script} objects.") (side-support-elements ,ly:grob-array? "The side support, an array of grobs.") (slur ,ly:grob? "A pointer to a @code{Slur} object.") (spacing ,ly:grob? "The spacing spanner governing this section.") + (space-increment ,ly:dimension? "The amount by which the total duration +of a multimeasure rest affects horizontal spacing. Each doubling of the +duration adds @code{space-increment} to the length of the bar.") (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?") @@ -1195,10 +1374,6 @@ results, use @code{LEFT} and @code{RIGHT}.") (vertical-skyline-elements ,ly:grob-array? "An array of grobs used to create vertical skylines.") - (X-colliding-grobs ,ly:grob-array? "Grobs that can collide -with a self-aligned grob on the X-axis.") - (Y-colliding-grobs ,ly:grob-array? "Grobs that can collide -with a self-aligned grob on the Y-axis.") (X-common ,ly:grob? "Common reference point for axis group.") (Y-common ,ly:grob? "See @code{X-common}.") @@ -1262,7 +1437,8 @@ to be within staff spaces.") (quantized-positions ,number-pair? "The beam positions after quanting.") - + (script-column ,ly:grob? "A @code{ScriptColumn} associated with a +@code{Script} object.") (script-stencil ,pair? "A pair @code{(@var{type} . @var{arg})} which acts as an index for looking up a @code{Stencil} object.") (shorten ,ly:dimension? "The amount of space that a stem is shortened.