X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=scm%2Fdefine-grob-properties.scm;h=2ebb832433eb4a2496e08af9cb524e680d119c3b;hb=0b544cfb7332615ef809b71b57ab656741311ae1;hp=9afb49a0a32e4c3fb471df85f1ad3aea23f06ca4;hpb=a1aa03e96f21f72d8a5962f64f3938cc2823f67e;p=lilypond.git diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm index 9afb49a0a3..2ebb832433 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--2014 Han-Wen Nienhuys ;;;; Jan Nieuwenhuizen ;;;; ;;;; LilyPond is free software: you can redistribute it and/or modify @@ -31,9 +31,9 @@ (apply define-grob-property x)) `( -;; -;; a -;; +;;; +;;; a +;;; (add-stem-support ,boolean? "If set, the @code{Stem} object is included in this script's support.") (after-line-breaking ,boolean? "Dummy property, used to trigger @@ -79,9 +79,9 @@ and @code{around} behave like @code{ignore}.") grobs, this should contain only one number.") -;; -;; b -;; +;;; +;;; b +;;; (bar-extent ,number-pair? "The Y-extent of the actual bar line. This may differ from @code{Y-extent} because it does not include the dots in a repeat bar line.") @@ -108,7 +108,6 @@ default length of the beamlet to the right. The actual length of a beamlet is determined by taking either the default length or the length specified by @code{beamlet-max-length-proportion}, whichever is smaller.") - (beam-gap ,number-pair? "Size of a gap in a @code{Beam}.") (beamlet-max-length-proportion ,pair? "The maximum length of a beamlet, as a proportion of the distance between two adjacent stems.") (before-line-breaking ,boolean? "Dummy property, used to trigger @@ -168,27 +167,20 @@ stick out of its bounds?") (broken-bound-padding ,number? "The amount of padding to insert when a spanner is broken at a line break.") -;; -;; c -;; - (c0-position ,integer? "An integer indicating the position of -middle@tie{}C.") - (chord-dots ,boolean? "If set, remove dots which the -@code{DotColumn} algorithm would vertically position too far away from -note heads.") +;;; +;;; c +;;; + (chord-dots-limit ,integer? "Limits the column of dots +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).") (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.") @@ -208,9 +200,9 @@ this should list the control points of a third-order B@'ezier curve.") receives this number. The following measures are numbered in increments from this initial value.") -;; -;; d -;; +;;; +;;; d +;;; (damping ,number? "Amount of beam slope damping.") (dash-definition ,pair? "List of @code{dash-elements} defining the dash structure. Each @code{dash-element} has a starting t value, @@ -251,9 +243,9 @@ elements closer together.") i.e., @code{0} = whole note, @code{1} = half note, etc.") -;; -;; e -;; +;;; +;;; e +;;; (eccentricity ,number? "How asymmetrical to make a slur. Positive means move the center to the right.") (edge-height ,pair? "A pair of numbers specifying the heights of @@ -285,10 +277,14 @@ item). In order to make a grob take up no horizontal space at all, set this to @code{(+inf.0 . -inf.0)}.") -;; -;; f -;; +;;; +;;; f +;;; (flag-count ,number? "The number of tremolo beams.") + (flag-style ,symbol? "The style of the flag to be used with +@code{MetronomeMark}. Available are @code{'modern-straight-flag}, +@code{'old-straight-flag}, @code{flat-flag}, @code{mensural} and +@code{'default}") (flat-positions ,list? "Flats 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 @@ -426,9 +422,9 @@ read from the NonMusicalPaperColumn that begins the measure.") (full-size-change ,boolean? "Don't make a change clef smaller.") -;; -;; g -;; +;;; +;;; g +;;; (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 @@ -449,9 +445,9 @@ etc. are already taken.") (grow-direction ,ly:dir? "Crescendo or decrescendo?") -;; -;; h -;; +;;; +;;; h +;;; (hair-thickness ,number? "Thickness of the thin line in a bar line.") (harp-pedal-details ,list? "An alist of detailed grob properties @@ -502,9 +498,9 @@ of @code{NoteColumn}s for horizontal shifting. This is used by left and one to the right of this grob.") -;; -;; i -;; +;;; +;;; 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, @@ -521,9 +517,9 @@ configuration to this index, and print the respective scores.") slur quants to this position, and print the respective scores.") -;; -;; k -;; +;;; +;;; k +;;; (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 @@ -534,9 +530,9 @@ correction amount for kneed beams. Set between @code{0} for no correction and @code{1} for full correction.") -;; -;; l -;; +;;; +;;; l +;;; (labels ,list? "List of labels (symbols) placed on a column.") (layer ,integer? "An integer which determines the order of printing objects. Objects with the lowest value of layer are drawn first, then @@ -575,14 +571,16 @@ contour.") (long-text ,markup? "Text markup. See @ruser{Formatting text}.") -;; -;; m -;; +;;; +;;; m +;;; (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.") (measure-count ,integer? "The number of measures for a multi-measure rest.") (measure-length ,ly:moment? "Length of a measure. Used in some @@ -618,9 +616,9 @@ X@tie{}dimension, measured in @code{staff-space} units.") Y@tie{}dimension, measured in @code{staff-space} units.") -;; -;; n -;; +;;; +;;; n +;;; (neutral-direction ,ly:dir? "Which direction to take in the center of the staff.") (neutral-position ,number? "Position (in half staff spaces) where @@ -671,16 +669,17 @@ between 0 and 1.") easy-notation note heads.") -;; -;; o -;; +;;; +;;; o +;;; (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 is raised so that it is not so close to its neighbor.") (outside-staff-padding ,number? "The padding to place between -this grob and the staff when spacing according to -@code{outside-staff-priority}.") +grobs when spacing according to @code{outside-staff-priority}. +Two grobs with different @code{outside-staff-padding} values have +the larger value of padding between them.") (outside-staff-placement-directive ,symbol? "One of four directives telling how outside staff objects should be placed. @itemize @bullet @@ -705,9 +704,9 @@ of a potential collision, the grob with the smaller @code{outside-staff-priority} is closer to the staff.") -;; -;; p -;; +;;; +;;; p +;;; (packed-spacing ,boolean? "If set, the notes are spaced as tightly as possible.") (padding ,ly:dimension? "Add this much extra space between @@ -737,10 +736,12 @@ positions are requested, the closest one is taken.") (prefer-dotted-right ,boolean? "For note collisions, prefer to shift dotted up-note to the right, rather than shifting just the dot.") + (protrusion ,number? "In an arpeggio bracket, the length of the +horizontal edges.") -;; -;; r -;; +;;; +;;; r +;;; (ratio ,number? "Parameter for slur shape. The higher this number, the quicker the slur attains its @code{height-limit}.") (remove-empty ,boolean? "If set, remove group if it contains no @@ -768,9 +769,9 @@ rest when the length of a measure is between two values of in a 3/2 measure.") -;; -;; s -;; +;;; +;;; s +;;; (same-direction-correction ,number? "Optical correction amount for stems that are placed in tight configurations. This amount is used for stems with the same direction to compensate for note head to @@ -796,9 +797,8 @@ 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 + (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.") @@ -830,6 +830,8 @@ slashes in percent repeat glyphs. Larger values bring the two elements closer together.") (slope ,number? "The slope of this object.") (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} @@ -841,8 +843,8 @@ 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. @@ -944,11 +946,11 @@ typeset. Valid choices depend on the @code{stencil} callback reading this property.") -;; -;; t -;; +;;; +;;; t +;;; (text ,markup? "Text markup. See @ruser{Formatting text}.") -;;FIXME -- Should both be the same? + ;;FIXME -- Should both be the same? (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}.") @@ -960,8 +962,8 @@ should use @code{LEFT}.") (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 -space and @var{dir} indicates the direction of the tie -(@code{1}=>up, @w{@code{-1}}=>down, @code{0}=>center). A non-pair entry +space and @var{dir} indicates the direction of the tie (@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 @@ -974,12 +976,12 @@ possible.") (transparent ,boolean? "This makes the grob invisible.") -;; -;; u -;; +;;; +;;; 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 @@ -987,15 +989,15 @@ can be used in typesetting the grob.") (use-skylines ,boolean? "Should skylines be used for side positioning?") -;; -;; v -;; +;;; +;;; v +;;; (vertical-skylines ,ly:skyline-pair? "Two skylines, one above and one below this grob.") -;; -;; w -;; +;;; +;;; w +;;; (when ,ly:moment? "Global time step associated with this column happen?") (whiteout ,boolean? "If true, the grob is printed over a white @@ -1007,10 +1009,11 @@ space.") texts.") -;; -;; x -;; - (X-extent ,number-pair? "Hard coded extent in X@tie{}direction.") +;;; +;;; x +;;; + (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 @@ -1018,16 +1021,17 @@ 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.") -;; -;; y -;; - (Y-extent ,number-pair? "Hard coded extent in Y@tie{}direction.") +;;; +;;; y +;;; + (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.") -;; -;; z -;; +;;; +;;; z +;;; (zigzag-length ,ly:dimension? "The length of the lines of a zigzag, relative to @code{zigzag-width}. A value of@tie{}@code{1} gives 60-degree zigzags.") @@ -1063,7 +1067,6 @@ constructed from a whole number of squiggles.") dynamic spanners.") (all-elements ,ly:grob-array? "An array of all grobs in this line. Its function is to protect objects from being garbage collected.") - (arpeggio ,ly:grob? "A pointer to an @code{Arpeggio} object.") (axis-group-parent-X ,ly:grob? "Containing X@tie{}axis group.") (axis-group-parent-Y ,ly:grob? "Containing Y@tie{}axis group.") @@ -1077,6 +1080,8 @@ column as start/@/begin point. Only columns that have grobs or act as bounds are spaced.") (bracket ,ly:grob? "The bracket for a number.") + (c0-position ,integer? "An integer indicating the position of +middle@tie{}C.") (columns ,ly:grob-array? "An array of grobs, typically containing @code{PaperColumn} or @code{NoteColumn} objects.") (concurrent-hairpins ,ly:grob-array? "All concurrent hairpins.") @@ -1138,8 +1143,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 @@ -1186,10 +1189,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}.") @@ -1205,8 +1204,15 @@ chord changes.") (cause ,scheme? "Any kind of causation objects (i.e., music, or perhaps translator) that was the cause for this grob.") - (cross-staff ,boolean? "For a beam or a stem, this is true if we -depend on inter-staff spacing.") + (cross-staff ,boolean? "True for grobs whose @code{Y-extent} depends on +inter-staff spacing. The extent is measured relative to the grobs's parent +staff (more generally, its @code{VerticalAxisGroup}) so this boolean flags +grobs that are not rigidly fixed to their parent staff. +Beams that join notes from two staves are @code{cross-staff}. +Grobs that are positioned around such beams are also @code{cross-staff}. +Grobs that are grouping objects, however, like @code{VerticalAxisGroups} +will not in general be marked @code{cross-staff} when some of the members +of the group are @code{cross-staff}.") (delta-position ,number? "The vertical position difference.")