X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=scm%2Fdefine-grob-properties.scm;h=497f8f08af0798485d535eca88a5201735cbe39d;hb=0d864ca56704009bda2a872cefd7038ca1d94ada;hp=98eb2c022c31f21b82af2c3ff7f7d481c33df53a;hpb=794dcbdb52faf4292036cd1b0270a956cf4316a3;p=lilypond.git diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm index 98eb2c022c..497f8f08af 100644 --- a/scm/define-grob-properties.scm +++ b/scm/define-grob-properties.scm @@ -1,9 +1,20 @@ -;;;; define-grob-properties.scm -- part of generated backend documentation +;;;; This file is part of LilyPond, the GNU music typesetter. ;;;; -;;;; source file of the GNU LilyPond music typesetter -;;;; -;;;; (c) 1998--2009 Han-Wen Nienhuys +;;;; Copyright (C) 1998--2010 Han-Wen Nienhuys ;;;; Jan Nieuwenhuizen +;;;; +;;;; LilyPond is free software: you can redistribute it and/or modify +;;;; it under the terms of the GNU General Public License as published by +;;;; the Free Software Foundation, either version 3 of the License, or +;;;; (at your option) any later version. +;;;; +;;;; LilyPond is distributed in the hope that it will be useful, +;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;;; GNU General Public License for more details. +;;;; +;;;; You should have received a copy of the GNU General Public License +;;;; along with LilyPond. If not, see . (define (define-grob-property symbol type? description) (if (not (equal? (object-property symbol 'backend-doc) #f)) @@ -27,10 +38,6 @@ ;; (add-stem-support ,boolean? "If set, the @code{Stem} object is included in this script's support.") - (after-last-staff-spacing ,list? "An alist of spacing variables -that controls the spacing after the last staff in this staff group. -See @var{next-staff-spacing} for a description of the elements of -this alist.") (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, @@ -99,10 +106,6 @@ beamlet, as a proportion of the distance between two adjacent stems.") (before-line-breaking ,boolean? "Dummy property, used to trigger a callback function.") (between-cols ,pair? "Where to attach a loose column to.") - (between-staff-spacing ,list? "An alist of spacing variables -that controls the spacing between staves within this staff group. -See @var{next-staff-spacing} for a description of the elements of -this alist.") (bound-details ,list? "An alist of properties for determining attachments of spanners to edges.") (bound-padding ,number? "The amount of padding to insert around @@ -196,10 +199,11 @@ an ending t-value, a @code{dash-fraction}, and a @code{dash-period}.") whitespace. If negative, no line is drawn at all.") (default-direction ,ly:dir? "Direction determined by note head positions.") - (default-next-staff-spacing ,list? "An alist of spacing variables -that controls the spacing between this staff and the next. -See @var{next-staff-spacing} for a description of the elements of -this alist.") + (default-staff-staff-spacing ,list? "The settings to use for +@code{staff-staff-spacing} when it is unset, for ungrouped staves +and for grouped staves that do not have the relevant +@code{StaffGrouper} property set (@code{staff-staff-spacing} or +@code{staffgroup-staff-spacing}).") (details ,list? "Alist of parameters for detailed grob behavior. More information on the allowed parameters for a grob can be found by looking at the top of the Internals Reference page for each interface @@ -274,9 +278,9 @@ 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 and Aybabtu) are using this property. Available -values are @code{fetaMusic} (Emmentaler), @code{fetaBraces} (Aybabtu), -@code{fetaNumber} (Emmentaler), and @code{fetaDynamic} (Emmentaler).") +fonts (Emmentaler) are using this property. Available +values are @code{fetaMusic} (Emmentaler), @code{fetaBraces}, +@code{fetaText} (Emmentaler).") (font-family ,symbol? "The font family is the broadest category for selecting text fonts. Options include: @code{sans}, @code{roman}.") @@ -400,6 +404,7 @@ typeset. Valid choices depend on the function that is reading this property.") (glyph-name ,string? "The glyph name within the font.") (glyph-name-alist ,list? "An alist of key-string pairs.") + (graphical ,boolean? "Display in graphical (vs. text) form.") (grow-direction ,ly:dir? "Crescendo or decrescendo?") @@ -463,21 +468,11 @@ resolution on this @code{NoteColumn}.") configuration to this index, and print the respective scores.") (inspect-quants ,number-pair? "If debugging is set, set beam and slur quants to this position, and print the respective scores.") - (inter-loose-line-spacing ,list? "Specifies how to vertically -position a non-spaced line relative to the other non-spaced lines -around it. See @var{next-staff-spacing} for the format of this list.") - (inter-staff-spacing ,list? "Specifies how to vertically -position a non-spaced line relative to the staff for which it -has affinity. See @var{next-staff-spacing} for the format of this list.") - ;; ;; k ;; - (keep-fixed-while-stretching ,boolean? "A grob with this property -set to true is fixed relative to the staff above it when systems are -stretched.") (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 @@ -492,9 +487,11 @@ correction and @code{1} for full correction.") ;; l ;; (labels ,list? "List of labels (symbols) placed on a column.") - (layer ,integer? "The output layer (a value between 0 -and@tie{}2): Layers define the order of printing objects. Objects in -lower layers are overprinted by objects in higher layers.") + (layer ,integer? "An integer which determines the order of printing +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-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 @@ -502,7 +499,7 @@ are added.") (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 -left to an object (e.g., a group of accidentals).") +left to an object (e.g., a lyric extender).") (length ,ly:dimension? "User override for the stem length of unbeamed stems.") (length-fraction ,number? "Multiplier for lengths. Used for @@ -575,25 +572,6 @@ center of the staff.") to flip the direction of custos stem.") (next ,ly:grob? "Object that is next relation (e.g., the lyric syllable following an extender).") - (next-staff-spacing ,list? "An alist of properties used to position -the next staff in the system. The symbols that can be defined in the alist -are -@itemize @bullet -@item @var{space} -- the amount of stretchable space between the center -of this staff and the center of the next staff; -@item @var{padding} -- the minimum amount of whitespace that must be -present between this staff and the next staff; -@item @var{stretchability} -- the ease with which the stretchable -space increases when the system to which this staff belongs is stretched. -If this is zero, the distance to the next staff will be fixed either at -@var{space} or at @var{padding} plus the minimum distance to ensure -there is no overlap, whichever is larger; -@item @var{minimum-distance} -- the minimum distance to place between -the center of this staff and the center of the next. This differs -from @var{padding} in that the height of a staff has no effect on -the application of @var{minimum-distance} (whereas the height of a -staff is crucial for @var{padding}). -@end itemize") (no-alignment ,boolean? "If set, don't place this grob in a @code{VerticalAlignment}; rather, place it using its own @code{Y-offset} callback.") @@ -601,9 +579,36 @@ staff is crucial for @var{padding}). object.") (no-stem-extend ,boolean? "If set, notes with ledger lines do not 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-musical ,boolean? "True if the grob belongs to a @code{NonMusicalPaperColumn}.") + (nonstaff-nonstaff-spacing ,list? "The spacing alist +controlling the distance between the current non-staff line and +the next non-staff line in the direction of @code{staff-affinity}, +if both are on the same side of the related staff, and +@code{staff-affinity} is either @code{UP} or @code{DOWN}. See +@code{staff-staff-spacing} for a description of the alist +structure.") + (nonstaff-relatedstaff-spacing ,list? "The spacing alist +controlling the distance between the current non-staff line and +the nearest staff in the direction of @code{staff-affinity}, if +there are no non-staff lines between the two, and +@code{staff-affinity} is either @code{UP} or @code{DOWN}. If +@code{staff-affinity} is @code{CENTER}, then +@code{nonstaff-relatedstaff-spacing} is used for the nearest +staves on @emph{both} sides, even if other non-staff lines appear +between the current one and either of the staves. See +@code{staff-staff-spacing} for a description of the alist +structure.") + (nonstaff-unrelatedstaff-spacing ,list? "The spacing alist +controlling the distance between the current non-staff line and +the nearest staff in the opposite direction from +@code{staff-affinity}, if there are no other non-staff lines +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.") (note-names ,vector? "Vector of strings containing names for easy-notation note heads.") @@ -738,11 +743,27 @@ there.") (spacing-increment ,number? "Add this much space for a doubled duration. 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. + +For example, a @code{MultiMeasureRest} will ignore prefatory items at its +bounds (i.e., clefs, key signatures and time signatures) using the following +override: + +@example +\\override MultiMeasureRest #'spacing-pair = #'(staff-bar . staff-bar) +@end example") (springs-and-rods ,boolean? "Dummy variable for triggering spacing routines.") (stacking-dir ,ly:dir? "Stack objects in which direction?") - (staff-affinity ,ly:dir? "The direction of the staff to which this -line should stick.") + (staff-affinity ,ly:dir? "The direction of the staff to use +for spacing the current non-staff line. Choices are @code{UP}, +@code{DOWN}, and @code{CENTER}. If @code{CENTER}, the non-staff +line will be placed equidistant between the two nearest staves on +either side, unless collisions or other spacing constraints +prevent this. Setting @code{staff-affinity} for a staff causes it +to be treated as a non-staff line. Setting @code{staff-affinity} +to @code{#f} causes a non-staff line to be treated as a staff.") (staff-padding ,ly:dimension? "Maintain this much space between reference points and the staff. Its effect is to align objects of differing sizes (like the dynamics @b{p} and @b{f}) on their @@ -751,6 +772,38 @@ baselines.") staff spaces, counted from the middle line.") (staff-space ,ly:dimension? "Amount of space between staff lines, expressed in global @code{staff-space}.") + (staff-staff-spacing ,list? "When applied to a staff-group's +@code{StaffGrouper} grob, this spacing alist controls the distance +between consecutive staves within the staff-group. When applied +to a staff's @code{VerticalAxisGroup} grob, it controls the +distance between the staff and the nearest staff below it in the +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{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 +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). +@end itemize") + (staffgroup-staff-spacing ,list? "The spacing alist +controlling the distance between the last staff of the current +staff-group and the staff just below it in the same system, even +if one or more non-staff lines exist between the two staves. If +the @code{staff-staff-spacing} property of the staff's +@code{VerticalAxisGroup} grob is set, that is used instead. See +@code{staff-staff-spacing} for a description of the alist +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 @@ -791,8 +844,6 @@ should use @code{LEFT}.") (thickness ,number? "Line thickness, generally measured in @code{line-thickness}.") (thin-kern ,number? "The space after a hair-line in a bar line.") - (threshold ,number-pair? "@code{(@var{min} . @var{max})}, where -@var{min} and @var{max} are dimensions in staff space.") (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 @@ -832,6 +883,9 @@ one below this grob.") ;; (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.") (width ,ly:dimension? "The width of a grob measured in staff space.") (word-space ,ly:dimension? "Space to insert between words in @@ -887,8 +941,8 @@ constructed from a whole number of squiggles.") (accidental-grob ,ly:grob? "The accidental for this note.") (accidental-grobs ,list? "An alist with @code{(@var{notename} . @var{groblist})} entries.") - (adjacent-hairpins ,ly:grob-array? "An array of directly neighboring -hairpins.") + (adjacent-spanners ,ly:grob-array? "An array of directly neighboring +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.") @@ -908,6 +962,7 @@ bounds are spaced.") (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.") @@ -925,12 +980,12 @@ in addition to notes and stems.") (items-worth-living ,ly:grob-array? "An array of interesting items. If empty in a particular staff, then that staff is erased.") - (left-items ,ly:grob-array? "DOCME") - (left-neighbors ,ly:grob-array? "An array of @code{spacing-wishes} grobs -that are close to the current column. + (keep-alive-with ,ly:grob-array? "An array of other +@code{VerticalAxisGroup}s. If any of them are alive, then we will stay alive.") -The closest @code{spacing-wishes} determine the actual distances between the -columns.") + (left-items ,ly:grob-array? "DOCME") + (left-neighbor ,ly:grob? "The right-most column that has a spacing-wish +for this column.") (normal-stems ,ly:grob-array? "An array of visible stems.") (note-columns ,ly:grob-array? "An array of @code{NoteColumn} grobs.") @@ -938,6 +993,8 @@ columns.") (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.") + (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 relevant for finding the @code{pure-Y-extent}.") (pure-relevant-spanners ,ly:grob-array? "A subset of elements that are @@ -949,18 +1006,15 @@ relevant for finding the @code{pure-Y-extent}.") (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-neighbors ,ly:grob-array? "See @code{left-neighbors}.") + (right-neighbor ,ly:grob? "See @code{left-neighbor}.") - (separation-item ,ly:grob? "A pointer to a @code{SeparationItem} -object.") (side-support-elements ,ly:grob-array? "The side support, an array of grobs.") (slur ,ly:grob? "A pointer to a @code{Slur} object.") - (spaceable-staves ,ly:grob-array? "Objects to be spaced during page -layout.") (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?") (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.") @@ -978,7 +1032,7 @@ objects.") (adjacent-pure-heights ,pair? "A pair of vectors. Used by a @code{VerticalAxisGroup} to cache the @code{Y-extent}s of different column ranges.") - + (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.") @@ -1007,6 +1061,8 @@ supported by this object. It is initialized from the @code{meta} field.") (least-squares-dy ,number? "The ideal beam slope, without damping.") + (maybe-loose ,boolean? "Used to mark a breakable column that is +loose if and only if it is in the middle of a line.") (meta ,list? "Provide meta information. It is an alist with the entries @code{name} and @code{interfaces}.") (minimum-distances ,list? "A list of rods that have the format @@ -1029,9 +1085,9 @@ quanting.") acts as an index for looking up a @code{Stencil} object.") (shorten ,ly:dimension? "The amount of space that a stem is shortened. Internally used to distribute beam shortening over stems.") - (skyline-distance ,number? "The distance between this staff and the -next one, as determined by a skyline algorithm.") (stem-info ,pair? "A cache of stem parameters.") + (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.") @@ -1074,8 +1130,6 @@ ligature grob in (in @code{staff-space} units).") (inclinatum ,boolean? "Is this neume an inclinatum?") - (join-heads ,boolean? "Whether to join the note heads of an ambitus -grob with a vertical line.") (join-right-amount ,number? "A length used for calculating the Y-extent of mensural ligatures.")