[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 Graphical Object Interfaces

3.2.1 accidental-interface  
3.2.2 accidental-placement-interface  
3.2.3 accidental-suggestion-interface  
3.2.4 align-interface  
3.2.5 ambitus-interface  
3.2.6 arpeggio-interface  
3.2.7 axis-group-interface  
3.2.8 balloon-interface  
3.2.9 bar-line-interface  
3.2.10 bass-figure-alignment-interface  
3.2.11 bass-figure-interface  
3.2.12 beam-interface  
3.2.13 bend-after-interface  
3.2.14 break-alignable-interface  
3.2.15 break-aligned-interface  
3.2.16 break-alignment-interface  
3.2.17 breathing-sign-interface  
3.2.18 chord-name-interface  
3.2.19 clef-interface  
3.2.20 clef-modifier-interface  
3.2.21 cluster-beacon-interface  
3.2.22 cluster-interface  
3.2.23 custos-interface  
3.2.24 dot-column-interface  
3.2.25 dots-interface  
3.2.26 dynamic-interface  
3.2.27 dynamic-line-spanner-interface  
3.2.28 dynamic-text-interface  
3.2.29 dynamic-text-spanner-interface  
3.2.30 enclosing-bracket-interface  
3.2.31 episema-interface  
3.2.32 figured-bass-continuation-interface  
3.2.33 finger-interface  
3.2.34 fingering-column-interface  
3.2.35 flag-interface  
3.2.36 font-interface  
3.2.37 footnote-interface  
3.2.38 footnote-spanner-interface  
3.2.39 fret-diagram-interface  
3.2.40 glissando-interface  
3.2.41 grace-spacing-interface  
3.2.42 gregorian-ligature-interface  
3.2.43 grid-line-interface  
3.2.44 grid-point-interface  
3.2.45 grob-interface  
3.2.46 hairpin-interface  
3.2.47 hara-kiri-group-spanner-interface  
3.2.48 horizontal-bracket-interface  
3.2.49 horizontal-bracket-text-interface  
3.2.50 inline-accidental-interface  
3.2.51 instrument-specific-markup-interface  
3.2.52 item-interface  
3.2.53 key-cancellation-interface  
3.2.54 key-signature-interface  
3.2.55 kievan-ligature-interface  
3.2.56 ledger-line-spanner-interface  
3.2.57 ledgered-interface  
3.2.58 ligature-bracket-interface  
3.2.59 ligature-head-interface  
3.2.60 ligature-interface  
3.2.61 line-interface  
3.2.62 line-spanner-interface  
3.2.63 lyric-extender-interface  
3.2.64 lyric-hyphen-interface  
3.2.65 lyric-interface  
3.2.66 lyric-syllable-interface  
3.2.67 mark-interface  
3.2.68 measure-counter-interface  
3.2.69 measure-grouping-interface  
3.2.70 measure-spanner-interface  
3.2.71 melody-spanner-interface  
3.2.72 mensural-ligature-interface  
3.2.73 metronome-mark-interface  
3.2.74 multi-measure-interface  
3.2.75 multi-measure-rest-interface  
3.2.76 note-collision-interface  
3.2.77 note-column-interface  
3.2.78 note-head-interface  
3.2.79 note-name-interface  
3.2.80 note-spacing-interface  
3.2.81 number-interface  
3.2.82 only-prebreak-interface  
3.2.83 ottava-bracket-interface  
3.2.84 outside-staff-axis-group-interface  
3.2.85 outside-staff-interface  
3.2.86 paper-column-interface  
3.2.87 parentheses-interface  
3.2.88 percent-repeat-interface  
3.2.89 percent-repeat-item-interface  
3.2.90 piano-pedal-bracket-interface  
3.2.91 piano-pedal-interface  
3.2.92 piano-pedal-script-interface  
3.2.93 pitched-trill-interface  
3.2.94 pure-from-neighbor-interface  
3.2.95 rest-collision-interface  
3.2.96 rest-interface  
3.2.97 rhythmic-grob-interface  
3.2.98 rhythmic-head-interface  
3.2.99 script-column-interface  
3.2.100 script-interface  
3.2.101 self-alignment-interface  
3.2.102 semi-tie-column-interface  
3.2.103 semi-tie-interface  
3.2.104 separation-item-interface  
3.2.105 side-position-interface  
3.2.106 slur-interface  
3.2.107 spaceable-grob-interface  
3.2.108 spacing-interface  
3.2.109 spacing-options-interface  
3.2.110 spacing-spanner-interface  
3.2.111 span-bar-interface  
3.2.112 spanner-interface  
3.2.113 staff-grouper-interface  
3.2.114 staff-spacing-interface  
3.2.115 staff-symbol-interface  
3.2.116 staff-symbol-referencer-interface  
3.2.117 stanza-number-interface  
3.2.118 stem-interface  
3.2.119 stem-tremolo-interface  
3.2.120 string-number-interface  
3.2.121 stroke-finger-interface  
3.2.122 system-interface  
3.2.123 system-start-delimiter-interface  
3.2.124 system-start-text-interface  
3.2.125 tab-note-head-interface  
3.2.126 text-interface  
3.2.127 text-script-interface  
3.2.128 tie-column-interface  
3.2.129 tie-interface  
3.2.130 time-signature-interface  
3.2.131 trill-pitch-accidental-interface  
3.2.132 trill-spanner-interface  
3.2.133 tuplet-bracket-interface  
3.2.134 tuplet-number-interface  
3.2.135 unbreakable-spanner-interface  
3.2.136 vaticana-ligature-interface  
3.2.137 volta-bracket-interface  
3.2.138 volta-interface  
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.1 accidental-interface

A single accidental.

User settable properties:

alteration (number)

Alteration numbers for accidental.

avoid-slur (symbol)

Method of handling slur collisions. Choices are inside, outside, around, and ignore. inside adjusts the slur if needed to keep the grob inside the slur. outside moves the grob vertically to the outside of the slur. around moves the grob vertically to the outside of the slur only if there is a collision. ignore does not move either. In grobs whose notational significance depends on vertical position (such as accidentals, clefs, etc.), outside and around behave like ignore.

glyph-name (string)

The glyph name within the font.

In the context of (span) bar lines, glyph-name represents a processed form of glyph, where decisions about line breaking etc. are already taken.

glyph-name-alist (list)

An alist of key-string pairs.

hide-tied-accidental-after-break (boolean)

If set, an accidental that appears on a tied note after a line break will not be displayed.

parenthesized (boolean)

Parenthesize this grob.

restore-first (boolean)

Print a natural before the accidental.

Internal properties:

forced (boolean)

Manually forced accidental.

tie (graphical (layout) object)

A pointer to a Tie object.

This grob interface is used in the following graphical object(s): Accidental, AccidentalCautionary, AccidentalSuggestion, AmbitusAccidental and TrillPitchAccidental.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.2 accidental-placement-interface

Resolve accidental collisions.

User settable properties:

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

right-padding (dimension, in staff space)

Space to insert on the right side of an object (e.g., between note and its accidentals).

script-priority (number)

A key for determining the order of 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.

Internal properties:

accidental-grobs (list)

An alist with (notename . groblist) entries.

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

This grob interface is used in the following graphical object(s): AccidentalPlacement.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.3 accidental-suggestion-interface

An accidental, printed as a suggestion (typically: vertically over a note).

This grob interface is used in the following graphical object(s): AccidentalSuggestion.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.4 align-interface

Order grobs from top to bottom, left to right, right to left or bottom to top. For vertical alignments of staves, the line-break-system-details of the left (internals)NonMusicalPaperColumn section ‘NonMusicalPaperColumn’ in Internals Reference may be set to tune vertical spacing.

User settable properties:

align-dir (direction)

Which side to align? -1: left side, 0: around center of width, 1: right side.

axes (list)

List of axis numbers. In the case of alignment grobs, this should contain only one number.

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

stacking-dir (direction)

Stack objects in which direction?

Internal properties:

elements (array of grobs)

An array of grobs; the type is depending on the grob where this is set in.

minimum-translations-alist (list)

An list of translations for a given start and end point.

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

This grob interface is used in the following graphical object(s): BassFigureAlignment and VerticalAlignment.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.5 ambitus-interface

The line between note heads for a pitch range.

User settable properties:

gap (dimension, in staff space)

Size of a gap in a variable symbol.

length-fraction (number)

Multiplier for lengths. Used for determining ledger lines and stem lengths.

maximum-gap (number)

Maximum value allowed for gap property.

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

note-heads (array of grobs)

An array of note head grobs.

This grob interface is used in the following graphical object(s): Ambitus, AmbitusLine and AmbitusNoteHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.6 arpeggio-interface

Functions and settings for drawing an arpeggio symbol.

User settable properties:

arpeggio-direction (direction)

If set, put an arrow on the arpeggio squiggly line.

dash-definition (pair)

List of dash-elements defining the dash structure. Each dash-element has a starting t value, an ending t-value, a dash-fraction, and a dash-period.

line-thickness (number)

For slurs and ties, this is the diameter of the virtual “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 Staff.StaffSymbol.thickness).

positions (pair of numbers)

Pair of staff coordinates (left . right), where both left and right are in staff-space units of the current staff. For slurs, this value selects which slur candidate to use; if extreme positions are requested, the closest one is taken.

protrusion (number)

In an arpeggio bracket, the length of the horizontal edges.

script-priority (number)

A key for determining the order of 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.

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

stems (array of grobs)

An array of stem objects.

This grob interface is used in the following graphical object(s): Arpeggio.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.7 axis-group-interface

An object that groups other layout objects.

User settable properties:

axes (list)

List of axis numbers. In the case of alignment grobs, this should contain only one number.

default-staff-staff-spacing (list)

The settings to use for staff-staff-spacing when it is unset, for ungrouped staves and for grouped staves that do not have the relevant StaffGrouper property set (staff-staff-spacing or staffgroup-staff-spacing).

no-alignment (boolean)

If set, don’t place this grob in a VerticalAlignment; rather, place it using its own Y-offset callback.

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 staff-affinity, if both are on the same side of the related staff, and staff-affinity is either UP or DOWN. See 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 staff-affinity, if there are no non-staff lines between the two, and staff-affinity is either UP or DOWN. If staff-affinity is CENTER, then nonstaff-relatedstaff-spacing is used for the nearest staves on both sides, even if other non-staff lines appear between the current one and either of the staves. See 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 staff-affinity, if there are no other non-staff lines between the two, and staff-affinity is either UP or DOWN. See staff-staff-spacing for a description of the alist structure.

staff-affinity (direction)

The direction of the staff to use for spacing the current non-staff line. Choices are UP, DOWN, and CENTER. If 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 staff-affinity for a staff causes it to be treated as a non-staff line. Setting staff-affinity to #f causes a non-staff line to be treated as a staff.

staff-staff-spacing (list)

When applied to a staff-group’s StaffGrouper grob, this spacing alist controls the distance between consecutive staves within the staff-group. When applied to a staff’s 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 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:

  • 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.
  • minimum-distance – the smallest allowable vertical distance, measured in staff-spaces, between the reference points of the two items, when compressing is in effect.
  • padding – the minimum required amount of unobstructed vertical whitespace between the bounding boxes (or skylines) of the two items, measured in staff-spaces.
  • stretchability – a unitless measure of the dimension’s relative propensity to stretch. If zero, the distance will not stretch (unless collisions would result).

Internal properties:

adjacent-pure-heights (pair)

A pair of vectors. Used by a VerticalAxisGroup to cache the Y-extents of different column ranges.

bound-alignment-interfaces (list)

Interfaces to be used for positioning elements that align with a column.

elements (array of grobs)

An array of grobs; the type is depending on the grob where this is set in.

pure-relevant-grobs (array of grobs)

All the grobs (items and spanners) that are relevant for finding the pure-Y-extent

pure-relevant-items (array of grobs)

A subset of elements that are relevant for finding the pure-Y-extent.

pure-relevant-spanners (array of grobs)

A subset of elements that are relevant for finding the pure-Y-extent.

pure-Y-common (graphical (layout) object)

A cache of the common_refpoint_of_array of the elements grob set.

staff-grouper (graphical (layout) object)

The staff grouper we belong to.

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.

X-common (graphical (layout) object)

Common reference point for axis group.

Y-common (graphical (layout) object)

See X-common.

This grob interface is used in the following graphical object(s): Ambitus, BassFigureAlignment, BassFigureAlignmentPositioning, BassFigureLine, BreakAlignGroup, BreakAlignment, DotColumn, DynamicLineSpanner, NonMusicalPaperColumn, NoteCollision, NoteColumn, PaperColumn, SostenutoPedalLineSpanner, SustainPedalLineSpanner, System, TrillPitchGroup, UnaCordaPedalLineSpanner, VerticalAlignment, VerticalAxisGroup and VoltaBracketSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.8 balloon-interface

A collection of routines to put text balloons around an object.

User settable properties:

annotation-balloon (boolean)

Print the balloon around an annotation.

annotation-line (boolean)

Print the line from an annotation to the grob that it annotates.

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

text (markup)

Text markup. See (notation)Formatting text section ‘Formatting text’ in Notation Reference.

Internal properties:

spanner-placement (direction)

The place of an annotation on a spanner. LEFT is for the first spanner, and RIGHT is for the last. 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 LEFT and RIGHT.

This grob interface is used in the following graphical object(s): BalloonTextItem, BalloonTextSpanner, FootnoteItem and FootnoteSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.9 bar-line-interface

Print a special bar symbol. It replaces the regular bar symbol with a special symbol. The argument bartype is a string which specifies the kind of bar line to print.

The list of allowed glyphs and predefined bar lines can be found in ‘scm/bar-line.scm’.

gap is used for the gaps in dashed bar lines.

User settable properties:

allow-span-bar (boolean)

If false, no inter-staff bar line will be created below this bar line.

bar-extent (pair of numbers)

The Y-extent of the actual bar line. This may differ from Y-extent because it does not include the dots in a repeat bar line.

gap (dimension, in staff space)

Size of a gap in a variable symbol.

glyph (string)

A string determining what ‘style’ of glyph is typeset. Valid choices depend on the function that is reading this property.

In combination with (span) bar lines, it is a string resembling the bar line appearance in ASCII form.

glyph-name (string)

The glyph name within the font.

In the context of (span) bar lines, glyph-name represents a processed form of glyph, where decisions about line breaking etc. are already taken.

hair-thickness (number)

Thickness of the thin line in a bar line, expressed as a multiple of the default staff-line thickness (i.e. the visual output is not influenced by changes to Staff.StaffSymbol.thickness).

kern (dimension, in staff space)

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 not influenced by changes to Staff.StaffSymbol.thickness).

rounded (boolean)

Decide whether lines should be drawn rounded or not.

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 not influenced by changes to Staff.StaffSymbol.thickness).

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 not influenced by changes to Staff.StaffSymbol.thickness).

Internal properties:

has-span-bar (pair)

A pair of grobs containing the span bars to be drawn below and above the staff. If no span bar is in a position, the respective element is set to #f.

This grob interface is used in the following graphical object(s): BarLine and SpanBar.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.10 bass-figure-alignment-interface

Align a bass figure.

This grob interface is used in the following graphical object(s): BassFigureAlignment.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.11 bass-figure-interface

A bass figure text.

User settable properties:

implicit (boolean)

Is this an implicit bass figure?

This grob interface is used in the following graphical object(s): BassFigure.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.12 beam-interface

A beam.

The beam-thickness property is the weight of beams, measured in staffspace. The direction property is not user-serviceable. Use the direction property of Stem instead. The following properties may be set in the details list.

stem-length-demerit-factor

Demerit factor used for inappropriate stem lengths.

secondary-beam-demerit

Demerit used in quanting calculations for multiple beams.

region-size

Size of region for checking quant scores.

beam-eps

Epsilon for beam quant code to check for presence in gap.

stem-length-limit-penalty

Penalty for differences in stem lengths on a beam.

damping-direction-penalty

Demerit penalty applied when beam direction is different from damping direction.

hint-direction-penalty

Demerit penalty applied when beam direction is different from damping direction, but damping slope is <= round-to-zero-slope.

musical-direction-factor

Demerit scaling factor for difference between beam slope and music slope.

ideal-slope-factor

Demerit scaling factor for difference between beam slope and damping slope.

round-to-zero-slope

Damping slope which is considered zero for purposes of calculating direction penalties.

User settable properties:

annotation (string)

Annotate a grob for debug purposes.

auto-knee-gap (dimension, in staff space)

If a gap is found between note heads where a horizontal beam fits and it is larger than this number, make a kneed beam.

beam-thickness (dimension, in staff space)

Beam thickness, measured in staff-space units.

beamed-stem-shorten (list)

How much to shorten beamed stems, when their direction is forced. It is a list, since the value is different depending on the number of flags and beams.

beaming (pair)

Pair of number lists. Each number list specifies which beams to make. 0 is the central beam, 1 is the next beam toward the note, etc. This information is used to determine how to connect the beaming patterns from stem to stem inside a beam.

break-overshoot (pair of numbers)

How much does a broken spanner stick out of its bounds?

clip-edges (boolean)

Allow outward pointing beamlets at the edges of beams?

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?

concaveness (number)

A beam is concave if its inner stems are closer to the beam than the two outside stems. This number is a measure of the closeness of the inner stems. It is used for damping the slope of the beam.

damping (number)

Amount of beam slope damping.

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 having a details property.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

gap (dimension, in staff space)

Size of a gap in a variable symbol.

gap-count (integer)

Number of gapped beams for tremolo.

grow-direction (direction)

Crescendo or decrescendo?

inspect-quants (pair of numbers)

If debugging is set, set beam and slur position to a (quantized) position that is as close as possible to this value, and print the demerits for the inspected position in the output.

knee (boolean)

Is this beam kneed?

length-fraction (number)

Multiplier for lengths. Used for determining ledger lines and stem lengths.

neutral-direction (direction)

Which direction to take in the center of the staff.

positions (pair of numbers)

Pair of staff coordinates (left . right), where both left and right are in staff-space units of the current staff. For slurs, this value selects which slur candidate to use; if extreme positions are requested, the closest one is taken.

skip-quanting (boolean)

Should beam quanting be skipped?

X-positions (pair of numbers)

Pair of X staff coordinates of a spanner in the form (left . right), where both left and right are in staff-space units of the current staff.

Internal properties:

beam-segments (list)

Internal representation of beam segments.

covered-grobs (array of grobs)

Grobs that could potentially collide with a beam.

least-squares-dy (number)

The ideal beam slope, without damping.

normal-stems (array of grobs)

An array of visible stems.

quantized-positions (pair of numbers)

The beam positions after quanting.

shorten (dimension, in staff space)

The amount of space that a stem is shortened. Internally used to distribute beam shortening over stems.

stems (array of grobs)

An array of stem objects.

This grob interface is used in the following graphical object(s): Beam.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.13 bend-after-interface

A doit or drop.

User settable properties:

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

delta-position (number)

The vertical position difference.

This grob interface is used in the following graphical object(s): BendAfter.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.14 break-alignable-interface

Object that is aligned on a break alignment.

User settable properties:

break-align-symbols (list)

A list of 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 break-visibility, we will align to the next grob (and so on). Choices are listed in (internals)break-alignment-interface section ‘break-alignment-interface’ in Internals Reference.

non-break-align-symbols (list)

A list of symbols that determine which NON-break-aligned interfaces to align this to.

This grob interface is used in the following graphical object(s): BarNumber, MetronomeMark and RehearsalMark.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.15 break-aligned-interface

Breakable items.

User settable properties:

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 ly:break-aligned-interface::calc-extent-aligned-anchor for aligning an anchor to a grob’s extent.

break-align-symbol (symbol)

This key is used for aligning, ordering, and spacing breakable items. See (internals)break-alignment-interface section ‘break-alignment-interface’ in Internals Reference.

space-alist (list)

An alist that specifies distances from this grob to other breakable items, using the format:

 
'((break-align-symbol . (spacing-style . space))
  (break-align-symbol . (spacing-style . space))
  ...)

Standard choices for break-align-symbol are listed in (internals)break-alignment-interface section ‘break-alignment-interface’ in Internals Reference. Additionally, three special break-align symbols available to space-alist are:

first-note

used when the grob is just left of the first note on a line

next-note

used when the grob is just left of any other note; if not set, the value of first-note gets used

right-edge

used when the grob is the last item on the line (only compatible with the extra-space spacing style)

Choices for spacing-style are:

extra-space

Put this much space between the two grobs. The space is stretchable when paired with first-note or next-note; otherwise it is fixed.

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 first-note or next-note; otherwise it is fixed. Not compatible with right-edge.

fixed-space

Only compatible with first-note and next-note. Put this much fixed space between the grob and the note.

minimum-fixed-space

Only compatible with first-note and 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.

semi-fixed-space

Only compatible with first-note and next-note. Put this much space between the grob and the note, such that half of the space is fixed and half is stretchable.

Rules for this spacing are much more complicated than this. See [Wanske] page 126–134, [Ross] page 143–147.

This grob interface is used in the following graphical object(s): Ambitus, AmbitusAccidental, BarLine, BreakAlignGroup, BreathingSign, Clef, CueClef, CueEndClef, Custos, DoublePercentRepeat, KeyCancellation, KeySignature, LeftEdge and TimeSignature.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.16 break-alignment-interface

The object that performs break alignment.

Three interfaces deal specifically with break alignment:

  1. break-alignment-interface (this one),
  2. break-alignable-interface, and
  3. break-aligned-interface.

Each of these interfaces supports grob properties that use break-align symbols, which are Scheme symbols that are used to specify the alignment, ordering, and spacing of certain notational elements (‘breakable’ items).

Available break-align symbols:

 
ambitus
breathing-sign
clef
cue-clef
cue-end-clef
custos
key-cancellation
key-signature
left-edge
staff-bar
time-signature

User settable properties:

break-align-orders (vector)

This is a vector of 3 lists: #(end-of-line unbroken start-of-line). Each list contains break-align symbols that specify an order of breakable items (see (internals)break-alignment-interface section ‘break-alignment-interface’ in Internals Reference).

For example, this places time signatures before clefs:

 
\override Score.BreakAlignment.break-align-orders =
  #(make-vector 3 '(left-edge
                    cue-end-clef
                    ambitus
                    breathing-sign
                    time-signature
                    clef
                    cue-clef
                    staff-bar
                    key-cancellation
                    key-signature
                    custos))

Internal properties:

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

This grob interface is used in the following graphical object(s): BreakAlignment.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.17 breathing-sign-interface

A breathing sign.

User settable properties:

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

This grob interface is used in the following graphical object(s): BreathingSign.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.18 chord-name-interface

A chord label (name or fretboard).

Internal properties:

begin-of-line-visible (boolean)

Set to make ChordName or FretBoard be visible only at beginning of line or at chord changes.

This grob interface is used in the following graphical object(s): ChordName and FretBoard.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.19 clef-interface

A clef sign.

User settable properties:

full-size-change (boolean)

Don’t make a change clef smaller.

glyph (string)

A string determining what ‘style’ of glyph is typeset. Valid choices depend on the function that is reading this property.

In combination with (span) bar lines, it is a string resembling the bar line appearance in ASCII form.

glyph-name (string)

The glyph name within the font.

In the context of (span) bar lines, glyph-name represents a processed form of glyph, where decisions about line breaking etc. are already taken.

non-default (boolean)

Set for manually specified clefs and keys.

This grob interface is used in the following graphical object(s): Clef, CueClef and CueEndClef.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.20 clef-modifier-interface

The number describing transposition of the clef, placed below or above clef sign. Usually this is 8 (octave transposition) or 15 (two octaves), but LilyPond allows any integer here.

User settable properties:

clef-alignments (list)

An alist of parent-alignments that should be used for clef modifiers with various clefs

This grob interface is used in the following graphical object(s): ClefModifier.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.21 cluster-beacon-interface

A place holder for the cluster spanner to determine the vertical extents of a cluster spanner at this X position.

User settable properties:

positions (pair of numbers)

Pair of staff coordinates (left . right), where both left and right are in staff-space units of the current staff. For slurs, this value selects which slur candidate to use; if extreme positions are requested, the closest one is taken.

This grob interface is used in the following graphical object(s): ClusterSpannerBeacon.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.22 cluster-interface

A graphically drawn musical cluster.

padding adds to the vertical extent of the shape (top and bottom).

The property style controls the shape of cluster segments. Valid values include leftsided-stairs, rightsided-stairs, centered-stairs, and ramp.

User settable properties:

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

Internal properties:

columns (array of grobs)

An array of grobs, typically containing PaperColumn or NoteColumn objects.

This grob interface is used in the following graphical object(s): ClusterSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.23 custos-interface

A custos object. style can have four valid values: mensural, vaticana, medicaea, and hufnagel. mensural is the default style.

User settable properties:

neutral-direction (direction)

Which direction to take in the center of the staff.

neutral-position (number)

Position (in half staff spaces) where to flip the direction of custos stem.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

This grob interface is used in the following graphical object(s): Custos.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.24 dot-column-interface

Group dot objects so they form a column, and position dots so they do not clash with staff lines.

User settable properties:

chord-dots-limit (integer)

Limits the column of dots on each chord to the height of the chord plus chord-dots-limit staff-positions.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

Internal properties:

dots (array of grobs)

Multiple Dots objects.

note-collision (graphical (layout) object)

The NoteCollision object of a dot column.

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

This grob interface is used in the following graphical object(s): DotColumn.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.25 dots-interface

The dots to go with a notehead or rest. direction sets the preferred direction to move in case of staff line collisions. style defaults to undefined, which is normal 19th/20th century traditional style. Set style to vaticana for ancient type dots.

User settable properties:

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

dot-count (integer)

The number of dots.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

This grob interface is used in the following graphical object(s): Dots.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.26 dynamic-interface

Any kind of loudness sign.

This grob interface is used in the following graphical object(s): DynamicLineSpanner, DynamicText, DynamicTextSpanner and Hairpin.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.27 dynamic-line-spanner-interface

Dynamic line spanner.

User settable properties:

avoid-slur (symbol)

Method of handling slur collisions. Choices are inside, outside, around, and ignore. inside adjusts the slur if needed to keep the grob inside the slur. outside moves the grob vertically to the outside of the slur. around moves the grob vertically to the outside of the slur only if there is a collision. ignore does not move either. In grobs whose notational significance depends on vertical position (such as accidentals, clefs, etc.), outside and around behave like ignore.

This grob interface is used in the following graphical object(s): DynamicLineSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.28 dynamic-text-interface

An absolute text dynamic.

User settable properties:

right-padding (dimension, in staff space)

Space to insert on the right side of an object (e.g., between note and its accidentals).

This grob interface is used in the following graphical object(s): DynamicText.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.29 dynamic-text-spanner-interface

Dynamic text spanner.

User settable properties:

text (markup)

Text markup. See (notation)Formatting text section ‘Formatting text’ in Notation Reference.

This grob interface is used in the following graphical object(s): DynamicTextSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.30 enclosing-bracket-interface

Brackets alongside bass figures.

User settable properties:

bracket-flare (pair of numbers)

A pair of numbers specifying how much edges of brackets should slant outward. Value 0.0 means straight edges.

dashed-edge (boolean)

If set, the bracket edges are dashed like the rest of the bracket.

edge-height (pair)

A pair of numbers specifying the heights of the vertical edges: (left-height . right-height).

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

shorten-pair (pair of numbers)

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.

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

elements (array of grobs)

An array of grobs; the type is depending on the grob where this is set in.

This grob interface is used in the following graphical object(s): BassFigureBracket.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.31 episema-interface

An episema line.

This grob interface is used in the following graphical object(s): Episema.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.32 figured-bass-continuation-interface

Simple extender line between bounds.

User settable properties:

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

figures (array of grobs)

Figured bass objects for continuation line.

This grob interface is used in the following graphical object(s): BassFigureContinuation.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.33 finger-interface

A fingering instruction.

This grob interface is used in the following graphical object(s): Fingering.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.34 fingering-column-interface

Makes sure that fingerings placed laterally do not collide and that they are flush if necessary.

User settable properties:

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

snap-radius (number)

The maximum distance between two objects that will cause them to snap to alignment along an axis.

Internal properties:

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

This grob interface is used in the following graphical object(s): FingeringColumn.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.35 flag-interface

A flag that gets attached to a stem.The style property is symbol determining what style of flag glyph is typeset on a Stem. Valid options include '() for standard flags, 'mensural and 'no-flag, which switches off the flag.

User settable properties:

glyph-name (string)

The glyph name within the font.

In the context of (span) bar lines, glyph-name represents a processed form of glyph, where decisions about line breaking etc. are already taken.

stroke-style (string)

Set to "grace" to turn stroke through flag on.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

This grob interface is used in the following graphical object(s): Flag.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.36 font-interface

Any symbol that is typeset through fixed sets of glyphs, (i.e., fonts).

User settable properties:

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 values are fetaMusic (Emmentaler), fetaBraces, fetaText (Emmentaler).

font-family (symbol)

The font family is the broadest category for selecting text fonts. Options include: sans, roman.

font-features (list)

Opentype features.

font-name (string)

Specifies a file name (without extension) of the font to load. This setting overrides selection using font-family, font-series and font-shape.

font-series (symbol)

Select the series of a font. Choices include medium, bold, bold-narrow, etc.

font-shape (symbol)

Select the shape of a font. Choices include upright, italic, caps.

font-size (number)

The font size, compared to the ‘normal’ size. 0 is style-sheet’s normal size, -1 is smaller, +1 is bigger. Each step of 1 is approximately 12% larger; 6 steps are exactly a factor 2 larger. If the context property fontSize is set, its value is added to this before the glyph is printed. Fractional values are allowed.

Internal properties:

font (font metric)

A cached font metric object.

This grob interface is used in the following graphical object(s): Accidental, AccidentalCautionary, AccidentalSuggestion, AmbitusAccidental, AmbitusLine, AmbitusNoteHead, Arpeggio, BalloonTextItem, BalloonTextSpanner, BarLine, BarNumber, BassFigure, Beam, BreathingSign, ChordName, Clef, ClefModifier, CombineTextScript, CueClef, CueEndClef, Custos, Dots, DoublePercentRepeat, DoublePercentRepeatCounter, DoubleRepeatSlash, DynamicText, DynamicTextSpanner, Episema, Fingering, Flag, FootnoteItem, FootnoteSpanner, FretBoard, HorizontalBracketText, InstrumentName, InstrumentSwitch, KeyCancellation, KeySignature, KievanLigature, LyricHyphen, LyricText, MeasureCounter, MeasureSpanner, MensuralLigature, MetronomeMark, MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestScript, MultiMeasureRestText, NonMusicalPaperColumn, NoteHead, NoteName, OttavaBracket, PaperColumn, ParenthesesItem, PercentRepeat, PercentRepeatCounter, RehearsalMark, Rest, Script, SostenutoPedal, SpanBar, StanzaNumber, StringNumber, StrokeFinger, SustainPedal, SystemStartBrace, SystemStartBracket, SystemStartSquare, TabNoteHead, TextScript, TextSpanner, TimeSignature, TrillPitchAccidental, TrillPitchGroup, TrillPitchHead, TrillSpanner, TupletNumber, UnaCordaPedal, VaticanaLigature and VoltaBracket.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.37 footnote-interface

Make a footnote.

User settable properties:

automatically-numbered (boolean)

If set, footnotes are automatically numbered.

footnote (boolean)

Should this be a footnote or in-note?

footnote-text (markup)

A footnote for the grob.

Internal properties:

numbering-assertion-function (any type)

The function used to assert that footnotes are receiving correct automatic numbers.

This grob interface is used in the following graphical object(s): FootnoteItem and FootnoteSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.38 footnote-spanner-interface

Make a footnote spanner.

User settable properties:

footnote-text (markup)

A footnote for the grob.

Internal properties:

spanner-placement (direction)

The place of an annotation on a spanner. LEFT is for the first spanner, and RIGHT is for the last. 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 LEFT and RIGHT.

This grob interface is used in the following graphical object(s): FootnoteSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.39 fret-diagram-interface

A fret diagram

User settable properties:

align-dir (direction)

Which side to align? -1: left side, 0: around center of width, 1: right side.

dot-placement-list (list)

List consisting of (description string-number fret-number finger-number) entries used to define fret diagrams.

fret-diagram-details (list)

An alist of detailed grob properties for fret diagrams. Each alist entry consists of a (property . value) pair. The properties which can be included in fret-diagram-details include the following:

  • barre-type – Type of barre indication used. Choices include curved, straight, and none. Default curved.
  • capo-thickness – Thickness of capo indicator, in multiples of fret-space. Default value 0.5.
  • dot-color – Color of dots. Options include black and white. Default black.
  • dot-label-font-mag – Magnification for font used to label fret dots. Default value 1.
  • dot-position – Location of dot in fret space. Default 0.6 for dots without labels, 0.95-dot-radius for dots with labels.
  • dot-radius – Radius of dots, in terms of fret spaces. Default value 0.425 for labeled dots, 0.25 for unlabeled dots.
  • finger-code – Code for the type of fingering indication used. Options include none, in-dot, and below-string. Default none for markup fret diagrams, below-string for FretBoards fret diagrams.
  • fret-count – The number of frets. Default 4.
  • fret-distance – Multiplier to adjust the distance between frets. Default 1.0.
  • fret-label-custom-format – The format string to be used label the lowest fret number, when number-type equals to custom. Default "~a".
  • fret-label-font-mag – The magnification of the font used to label the lowest fret number. Default 0.5.
  • fret-label-vertical-offset – The offset of the fret label from the center of the fret in direction parallel to strings. Default 0.
  • fret-label-horizontal-offset – The offset of the fret label from the center of the fret in direction orthogonal to strings. Default 0.
  • handedness – Print the fret-diagram left- or right-handed. -1, LEFT for left ; 1, RIGHT for right. Default RIGHT.
  • paren-padding – The padding for the parenthesis. Default 0.05.
  • label-dir – Side to which the fret label is attached. -1, LEFT, or DOWN for left or down; 1, RIGHT, or UP for right or up. Default RIGHT.
  • mute-string – Character string to be used to indicate muted string. Default "x".
  • number-type – Type of numbers to use in fret label. Choices include roman-lower, roman-upper, arabic and custom. In the later case, the format string is supplied by the fret-label-custom-format property. Default roman-lower.
  • open-string – Character string to be used to indicate open string. Default "o".
  • orientation – Orientation of fret-diagram. Options include normal, landscape, and opposing-landscape. Default normal.
  • string-count – The number of strings. Default 6.
  • string-distance – Multiplier to adjust the distance between strings. Default 1.0.
  • 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 normal orientation, 0.5 for landscape and opposing-landscape.
  • string-thickness-factor – Factor for changing thickness of each string in the fret diagram. Thickness of string k is given by thickness * (1+string-thickness-factor) ^ (k-1). Default 0.
  • top-fret-thickness – The thickness of the top fret line, as a multiple of the standard thickness. Default value 3.
  • xo-font-magnification – Magnification used for mute and open string indicators. Default value 0.5.
  • xo-padding – Padding for open and mute indicators from top fret. Default value 0.25.
size (number)

The ratio of the size of the object to its default size.

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 “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 Staff.StaffSymbol.thickness).

This grob interface is used in the following graphical object(s): FretBoard.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.40 glissando-interface

A glissando.

Internal properties:

glissando-index (integer)

The index of a glissando in its note column.

This grob interface is used in the following graphical object(s): Glissando.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.41 grace-spacing-interface

Keep track of durations in a run of grace notes.

User settable properties:

common-shortest-duration (moment)

The most common shortest note length. This is used in spacing. Enlarging this sets the score tighter.

Internal properties:

columns (array of grobs)

An array of grobs, typically containing PaperColumn or NoteColumn objects.

This grob interface is used in the following graphical object(s): GraceSpacing.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.42 gregorian-ligature-interface

A gregorian ligature.

Internal properties:

ascendens (boolean)

Is this neume of ascending type?

auctum (boolean)

Is this neume liquescentically augmented?

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. context-info holds for each head such information about the left and right neighbour, encoded as a bit mask.

deminutum (boolean)

Is this neume deminished?

descendens (boolean)

Is this neume of descendent type?

inclinatum (boolean)

Is this neume an inclinatum?

linea (boolean)

Attach vertical lines to this neume?

oriscus (boolean)

Is this neume an oriscus?

pes-or-flexa (boolean)

Shall this neume be joined with the previous head?

prefix-set (number)

A bit mask that holds all Gregorian head prefixes, such as \virga or \quilisma.

quilisma (boolean)

Is this neume a quilisma?

stropha (boolean)

Is this neume a stropha?

virga (boolean)

Is this neume a virga?

This grob interface is used in the following graphical object(s): NoteHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.43 grid-line-interface

A line that is spanned between grid-points.

User settable properties:

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

elements (array of grobs)

An array of grobs; the type is depending on the grob where this is set in.

This grob interface is used in the following graphical object(s): GridLine.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.44 grid-point-interface

A spanning point for grid lines.

This grob interface is used in the following graphical object(s): GridPoint.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.45 grob-interface

A grob represents a piece of music notation.

All grobs have an X and Y position on the page. These X and Y positions are stored in a relative format, thus they can easily be combined by stacking them, hanging one grob to the side of another, or coupling them into grouping objects.

Each grob has a reference point (a.k.a. parent): The position of a grob is stored relative to that reference point. For example, the X reference point of a staccato dot usually is the note head that it applies to. When the note head is moved, the staccato dot moves along automatically.

A grob is often associated with a symbol, but some grobs do not print any symbols. They take care of grouping objects. For example, there is a separate grob that stacks staves vertically. The NoteCollision object is also an abstract grob: It only moves around chords, but doesn’t print anything.

Grobs have properties (Scheme variables) that can be read and set. Two types of them exist: immutable and mutable. Immutable variables define the default style and behavior. They are shared between many objects. They can be changed using \override and \revert. Mutable properties are variables that are specific to one grob. Typically, lists of other objects, or results from computations are stored in mutable properties. In particular, every call to ly:grob-set-property! (or its C++ equivalent) sets a mutable property.

The properties after-line-breaking and before-line-breaking are dummies that are not user-serviceable.

User settable properties:

after-line-breaking (boolean)

Dummy property, used to trigger callback for after-line-breaking.

avoid-slur (symbol)

Method of handling slur collisions. Choices are inside, outside, around, and ignore. inside adjusts the slur if needed to keep the grob inside the slur. outside moves the grob vertically to the outside of the slur. around moves the grob vertically to the outside of the slur only if there is a collision. ignore does not move either. In grobs whose notational significance depends on vertical position (such as accidentals, clefs, etc.), outside and around behave like ignore.

before-line-breaking (boolean)

Dummy property, used to trigger a callback function.

color (color)

The color of this grob.

extra-offset (pair of numbers)

A pair representing an offset. This offset is added just before outputting the symbol, so the typesetting engine is completely oblivious to it. The values are measured in staff-space units of the staff’s StaffSymbol.

footnote-music (music)

Music creating a footnote.

forced-spacing (number)

Spacing forced between grobs, used in various ligature engravers.

horizontal-skylines (pair of skylines)

Two skylines, one to the left and one to the right of this grob.

id (string)

An id string for the grob.

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.

minimum-X-extent (pair of numbers)

Minimum size of an object in X dimension, measured in staff-space units.

minimum-Y-extent (pair of numbers)

Minimum size of an object in Y dimension, measured in staff-space units.

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 (<g>) containing all of the stencils that comprise a given grob. For example, '((id . 123) (class . foo) (data-whatever . “bar”)) will produce <g id=“123” class=“foo” data-whatever=“bar”> … </g>. In the Postscript backend, where there is no way to group items, the setting of the output-attributes property will have no effect.

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.

rotation (list)

Number of degrees to rotate this object, and what point to rotate around. For example, '(45 0 0) rotates by 45 degrees around the center of this object.

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.

springs-and-rods (boolean)

Dummy variable for triggering spacing routines.

stencil (stencil)

The symbol to print.

transparent (boolean)

This makes the grob invisible.

vertical-skylines (pair of skylines)

Two skylines, one above and one below this grob.

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 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 line-thickness. The shape of the background is determined by whiteout-style. Usually #f by default.

whiteout-style (symbol)

Determines the shape of the whiteout background. Available are 'outline, 'rounded-box, and the default 'box. There is one exception: Use 'special for LyricHyphen.

X-extent (pair of numbers)

Extent (size) in the X 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.

Y-extent (pair of numbers)

Extent (size) in the Y 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.

Internal properties:

axis-group-parent-X (graphical (layout) object)

Containing X axis group.

axis-group-parent-Y (graphical (layout) object)

Containing Y axis group.

cause (any type)

Any kind of causation objects (i.e., music, or perhaps translator) that was the cause for this grob.

cross-staff (boolean)

True for grobs whose Y-extent depends on inter-staff spacing. The extent is measured relative to the grobs’s parent staff (more generally, its VerticalAxisGroup) so this boolean flags grobs that are not rigidly fixed to their parent staff. Beams that join notes from two staves are cross-staff. Grobs that are positioned around such beams are also cross-staff. Grobs that are grouping objects, however, like VerticalAxisGroups will not in general be marked cross-staff when some of the members of the group are cross-staff.

interfaces (list)

A list of symbols indicating the interfaces supported by this object. It is initialized from the meta field.

meta (list)

Provide meta information. It is an alist with the entries name and interfaces.

pure-Y-offset-in-progress (boolean)

A debugging aid for catching cyclic dependencies.

staff-symbol (graphical (layout) object)

The staff symbol grob that we are in.

This grob interface is used in the following graphical object(s): Accidental, AccidentalCautionary, AccidentalPlacement, AccidentalSuggestion, Ambitus, AmbitusAccidental, AmbitusLine, AmbitusNoteHead, Arpeggio, BalloonTextItem, BalloonTextSpanner, BarLine, BarNumber, BassFigure, BassFigureAlignment, BassFigureAlignmentPositioning, BassFigureBracket, BassFigureContinuation, BassFigureLine, Beam, BendAfter, BreakAlignGroup, BreakAlignment, BreathingSign, ChordName, Clef, ClefModifier, ClusterSpanner, ClusterSpannerBeacon, CombineTextScript, CueClef, CueEndClef, Custos, DotColumn, Dots, DoublePercentRepeat, DoublePercentRepeatCounter, DoubleRepeatSlash, DynamicLineSpanner, DynamicText, DynamicTextSpanner, Episema, Fingering, FingeringColumn, Flag, FootnoteItem, FootnoteSpanner, FretBoard, Glissando, GraceSpacing, GridLine, GridPoint, Hairpin, HorizontalBracket, HorizontalBracketText, InstrumentName, InstrumentSwitch, KeyCancellation, KeySignature, KievanLigature, LaissezVibrerTie, LaissezVibrerTieColumn, LedgerLineSpanner, LeftEdge, LigatureBracket, LyricExtender, LyricHyphen, LyricSpace, LyricText, MeasureCounter, MeasureGrouping, MeasureSpanner, MelodyItem, MensuralLigature, MetronomeMark, MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestScript, MultiMeasureRestText, NonMusicalPaperColumn, NoteCollision, NoteColumn, NoteHead, NoteName, NoteSpacing, OttavaBracket, PaperColumn, ParenthesesItem, PercentRepeat, PercentRepeatCounter, PhrasingSlur, PianoPedalBracket, RehearsalMark, RepeatSlash, RepeatTie, RepeatTieColumn, Rest, RestCollision, Script, ScriptColumn, ScriptRow, Slur, SostenutoPedal, SostenutoPedalLineSpanner, SpacingSpanner, SpanBar, SpanBarStub, StaffGrouper, StaffSpacing, StaffSymbol, StanzaNumber, Stem, StemStub, StemTremolo, StringNumber, StrokeFinger, SustainPedal, SustainPedalLineSpanner, System, SystemStartBar, SystemStartBrace, SystemStartBracket, SystemStartSquare, TabNoteHead, TextScript, TextSpanner, Tie, TieColumn, TimeSignature, TrillPitchAccidental, TrillPitchGroup, TrillPitchHead, TrillSpanner, TupletBracket, TupletNumber, UnaCordaPedal, UnaCordaPedalLineSpanner, VaticanaLigature, VerticalAlignment, VerticalAxisGroup, VoiceFollower, VoltaBracket, VoltaBracketSpanner and VowelTransition.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.46 hairpin-interface

A hairpin crescendo or decrescendo.

User settable properties:

bound-padding (number)

The amount of padding to insert around spanner bounds.

broken-bound-padding (number)

The amount of padding to insert when a spanner is broken at a line break.

circled-tip (boolean)

Put a circle at start/end of hairpins (al/del niente).

grow-direction (direction)

Crescendo or decrescendo?

height (dimension, in staff space)

Height of an object in staff-space units.

shorten-pair (pair of numbers)

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.

Internal properties:

adjacent-spanners (array of grobs)

An array of directly neighboring dynamic spanners.

concurrent-hairpins (array of grobs)

All concurrent hairpins.

This grob interface is used in the following graphical object(s): Hairpin.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.47 hara-kiri-group-spanner-interface

A group spanner that keeps track of interesting items. If it doesn’t contain any after line breaking, it removes itself and all its children. Greater control can be exercised via remove-layer which can prioritize layers so only the lowest-numbered non-empty layer is retained; make the layer independent of the group; or make it dependent on any other member of the group

User settable properties:

remove-empty (boolean)

If set, remove group if it contains no interesting items.

remove-first (boolean)

Remove the first staff of an orchestral score?

remove-layer (index or symbol)

When set as a positive integer, the Keep_alive_together_engraver removes all VerticalAxisGroup grobs with a remove-layer larger than the smallest retained remove-layer. Set to #f to make a layer independent of the Keep_alive_together_engraver. Set to '(), the layer does not participate in the layering decisions. The property can also be set as a symbol for common behaviors: #'any to keep the layer alive with any other layer in the group; #'above or #'below to keep the layer alive with the context immediately before or after it, respectively.

Internal properties:

important-column-ranks (vector)

A cache of columns that contain items-worth-living data.

items-worth-living (array of grobs)

An array of interesting items. If empty in a particular staff, then that staff is erased.

keep-alive-with (array of grobs)

An array of other VerticalAxisGroups. If any of them are alive, then we will stay alive.

make-dead-when (array of grobs)

An array of other VerticalAxisGroups. If any of them are alive, then we will turn dead.

This grob interface is used in the following graphical object(s): VerticalAxisGroup.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.48 horizontal-bracket-interface

A horizontal bracket encompassing notes.

User settable properties:

bracket-flare (pair of numbers)

A pair of numbers specifying how much edges of brackets should slant outward. Value 0.0 means straight edges.

connect-to-neighbor (pair)

Pair of booleans, indicating whether this grob looks as a continued break.

dashed-edge (boolean)

If set, the bracket edges are dashed like the rest of the bracket.

edge-height (pair)

A pair of numbers specifying the heights of the vertical edges: (left-height . right-height).

shorten-pair (pair of numbers)

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.

Internal properties:

bracket-text (graphical (layout) object)

The text for an analysis bracket.

columns (array of grobs)

An array of grobs, typically containing PaperColumn or NoteColumn objects.

This grob interface is used in the following graphical object(s): HorizontalBracket, OttavaBracket and VoltaBracket.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.49 horizontal-bracket-text-interface

Label for an analysis bracket.

Internal properties:

bracket (graphical (layout) object)

The bracket for a number.

columns (array of grobs)

An array of grobs, typically containing PaperColumn or NoteColumn objects.

This grob interface is used in the following graphical object(s): HorizontalBracketText.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.50 inline-accidental-interface

An inlined accidental (i.e. normal accidentals, cautionary accidentals).

This grob interface is used in the following graphical object(s): Accidental, AccidentalCautionary and TrillPitchAccidental.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.51 instrument-specific-markup-interface

Instrument-specific markup (like fret boards or harp pedal diagrams).

User settable properties:

fret-diagram-details (list)

An alist of detailed grob properties for fret diagrams. Each alist entry consists of a (property . value) pair. The properties which can be included in fret-diagram-details include the following:

  • barre-type – Type of barre indication used. Choices include curved, straight, and none. Default curved.
  • capo-thickness – Thickness of capo indicator, in multiples of fret-space. Default value 0.5.
  • dot-color – Color of dots. Options include black and white. Default black.
  • dot-label-font-mag – Magnification for font used to label fret dots. Default value 1.
  • dot-position – Location of dot in fret space. Default 0.6 for dots without labels, 0.95-dot-radius for dots with labels.
  • dot-radius – Radius of dots, in terms of fret spaces. Default value 0.425 for labeled dots, 0.25 for unlabeled dots.
  • finger-code – Code for the type of fingering indication used. Options include none, in-dot, and below-string. Default none for markup fret diagrams, below-string for FretBoards fret diagrams.
  • fret-count – The number of frets. Default 4.
  • fret-distance – Multiplier to adjust the distance between frets. Default 1.0.
  • fret-label-custom-format – The format string to be used label the lowest fret number, when number-type equals to custom. Default "~a".
  • fret-label-font-mag – The magnification of the font used to label the lowest fret number. Default 0.5.
  • fret-label-vertical-offset – The offset of the fret label from the center of the fret in direction parallel to strings. Default 0.
  • fret-label-horizontal-offset – The offset of the fret label from the center of the fret in direction orthogonal to strings. Default 0.
  • handedness – Print the fret-diagram left- or right-handed. -1, LEFT for left ; 1, RIGHT for right. Default RIGHT.
  • paren-padding – The padding for the parenthesis. Default 0.05.
  • label-dir – Side to which the fret label is attached. -1, LEFT, or DOWN for left or down; 1, RIGHT, or UP for right or up. Default RIGHT.
  • mute-string – Character string to be used to indicate muted string. Default "x".
  • number-type – Type of numbers to use in fret label. Choices include roman-lower, roman-upper, arabic and custom. In the later case, the format string is supplied by the fret-label-custom-format property. Default roman-lower.
  • open-string – Character string to be used to indicate open string. Default "o".
  • orientation – Orientation of fret-diagram. Options include normal, landscape, and opposing-landscape. Default normal.
  • string-count – The number of strings. Default 6.
  • string-distance – Multiplier to adjust the distance between strings. Default 1.0.
  • 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 normal orientation, 0.5 for landscape and opposing-landscape.
  • string-thickness-factor – Factor for changing thickness of each string in the fret diagram. Thickness of string k is given by thickness * (1+string-thickness-factor) ^ (k-1). Default 0.
  • top-fret-thickness – The thickness of the top fret line, as a multiple of the standard thickness. Default value 3.
  • xo-font-magnification – Magnification used for mute and open string indicators. Default value 0.5.
  • xo-padding – Padding for open and mute indicators from top fret. Default value 0.25.
graphical (boolean)

Display in graphical (vs. text) form.

harp-pedal-details (list)

An alist of detailed grob properties for harp pedal diagrams. Each alist entry consists of a (property . value) pair. The properties which can be included in harp-pedal-details include the following:

  • box-offset – Vertical shift of the center of flat/sharp pedal boxes above/below the horizontal line. Default value 0.8.
  • box-width – Width of each pedal box. Default value 0.4.
  • box-height – Height of each pedal box. Default value 1.0.
  • space-before-divider – Space between boxes before the first divider (so that the diagram can be made symmetric). Default value 0.8.
  • space-after-divider – Space between boxes after the first divider. Default value 0.8.
  • circle-thickness – Thickness (in unit of the line-thickness) of the ellipse around circled pedals. Default value 0.5.
  • circle-x-padding – Padding in X direction of the ellipse around circled pedals. Default value 0.15.
  • circle-y-padding – Padding in Y direction of the ellipse around circled pedals. Default value 0.2.
size (number)

The ratio of the size of the object to its default size.

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 “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 Staff.StaffSymbol.thickness).

This grob interface is used in the following graphical object(s): TextScript.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.52 item-interface

Grobs can be distinguished in their role in the horizontal spacing. Many grobs define constraints on the spacing by their sizes, for example, note heads, clefs, stems, and all other symbols with a fixed shape. These grobs form a subtype called Item.

Some items need special treatment for line breaking. For example, a clef is normally only printed at the start of a line (i.e., after a line break). To model this, ‘breakable’ items (clef, key signature, bar lines, etc.) are copied twice. Then we have three versions of each breakable item: one version if there is no line break, one version that is printed before the line break (at the end of a system), and one version that is printed after the line break.

Whether these versions are visible and take up space is determined by the outcome of the break-visibility grob property, which is a function taking a direction (-1, 0 or 1) as an argument. It returns a cons of booleans, signifying whether this grob should be transparent and have no extent.

The following variables for break-visibility are predefined:

 
           grob will show:   before  no     after
                             break   break  break
  all-invisible              no      no     no
  begin-of-line-visible      no      no     yes
  end-of-line-visible        yes     no     no
  all-visible                yes     yes    yes
  begin-of-line-invisible    yes     yes    no
  end-of-line-invisible      no      yes    yes
  center-invisible           yes      no    yes

User settable properties:

break-visibility (vector)

A vector of 3 booleans, #(end-of-line unbroken begin-of-line). #t means visible, #f means killed.

extra-spacing-height (pair of numbers)

In the horizontal spacing problem, we increase the height of each item by this amount (by adding the ‘car’ to the bottom of the item and adding the ‘cdr’ to the top of the item). In order to make a grob infinitely high (to prevent the horizontal spacing problem from placing any other grobs above or below this grob), set this to (-inf.0 . +inf.0).

extra-spacing-width (pair of numbers)

In the horizontal spacing problem, we pad each item by this amount (by adding the ‘car’ on the left side of the item and adding the ‘cdr’ on the right side of the item). In order to make a grob take up no horizontal space at all, set this to (+inf.0 . -inf.0).

non-musical (boolean)

True if the grob belongs to a NonMusicalPaperColumn.

This grob interface is used in the following graphical object(s): Accidental, AccidentalCautionary, AccidentalPlacement, AccidentalSuggestion, Ambitus, AmbitusAccidental, AmbitusLine, AmbitusNoteHead, Arpeggio, BalloonTextItem, BarLine, BarNumber, BassFigure, BassFigureBracket, BreakAlignGroup, BreakAlignment, BreathingSign, ChordName, Clef, ClefModifier, ClusterSpannerBeacon, CombineTextScript, CueClef, CueEndClef, Custos, DotColumn, Dots, DoublePercentRepeat, DoublePercentRepeatCounter, DoubleRepeatSlash, DynamicText, Fingering, FingeringColumn, Flag, FootnoteItem, FretBoard, GridLine, GridPoint, InstrumentSwitch, KeyCancellation, KeySignature, LaissezVibrerTie, LaissezVibrerTieColumn, LeftEdge, LyricText, MelodyItem, MetronomeMark, NonMusicalPaperColumn, NoteCollision, NoteColumn, NoteHead, NoteName, NoteSpacing, PaperColumn, ParenthesesItem, RehearsalMark, RepeatSlash, RepeatTie, RepeatTieColumn, Rest, RestCollision, Script, ScriptColumn, ScriptRow, SostenutoPedal, SpanBar, SpanBarStub, StaffSpacing, StanzaNumber, Stem, StemStub, StemTremolo, StringNumber, StrokeFinger, SustainPedal, TabNoteHead, TextScript, TimeSignature, TrillPitchAccidental, TrillPitchGroup, TrillPitchHead and UnaCordaPedal.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.53 key-cancellation-interface

A key cancellation.

This grob interface is used in the following graphical object(s): KeyCancellation.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.54 key-signature-interface

A group of accidentals, to be printed as signature sign.

User settable properties:

alteration-alist (list)

List of (pitch . accidental) pairs for key signature.

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 of the staff-position at which each clef places C: (alto treble tenor soprano baritone mezzosoprano bass). 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.

glyph-name-alist (list)

An alist of key-string pairs.

non-default (boolean)

Set for manually specified clefs and keys.

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

padding-pairs (list)

An alist mapping (name . name) to distances.

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 of the staff-position at which each clef places C: (alto treble tenor soprano baritone mezzosoprano bass). 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.

Internal properties:

c0-position (integer)

An integer indicating the position of middle C.

This grob interface is used in the following graphical object(s): KeyCancellation and KeySignature.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.55 kievan-ligature-interface

A kievan ligature.

User settable properties:

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

Internal properties:

primitive (integer)

A pointer to a ligature primitive, i.e., an item similar to a note head that is part of a ligature.

This grob interface is used in the following graphical object(s): KievanLigature.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.56 ledger-line-spanner-interface

This spanner draws the ledger lines of a staff. This is a separate grob because it has to process all potential collisions between all note heads. The thickness of ledger lines is controlled by the ledger-line-thickness property of the StaffSymbol grob.

User settable properties:

gap (dimension, in staff space)

Size of a gap in a variable symbol.

length-fraction (number)

Multiplier for lengths. Used for determining ledger lines and stem lengths.

minimum-length-fraction (number)

Minimum length of ledger line as fraction of note head size.

Internal properties:

note-heads (array of grobs)

An array of note head grobs.

This grob interface is used in the following graphical object(s): LedgerLineSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.57 ledgered-interface

Objects that need ledger lines, typically note heads. See also ledger-line-spanner-interface.

User settable properties:

no-ledgers (boolean)

If set, don’t draw ledger lines on this object.

This grob interface is used in the following graphical object(s): AmbitusNoteHead, NoteHead and TrillPitchHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.58 ligature-bracket-interface

A bracket indicating a ligature in the original edition.

User settable properties:

height (dimension, in staff space)

Height of an object in staff-space units.

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 “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 Staff.StaffSymbol.thickness).

width (dimension, in staff space)

The width of a grob measured in staff space.

This grob interface is not used in any graphical object.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.59 ligature-head-interface

A note head that can become part of a ligature.

This grob interface is used in the following graphical object(s): NoteHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.60 ligature-interface

A ligature.

This grob interface is not used in any graphical object.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.61 line-interface

Generic line objects. Any object using lines supports this. The property style can be line, dashed-line, trill, dotted-line, zigzag or none (a transparent line).

For dashed-line, the length of the dashes is tuned with dash-fraction. If the latter is set to 0, a dotted line is produced.

User settable properties:

arrow-length (number)

Arrow length.

arrow-width (number)

Arrow width.

dash-fraction (number)

Size of the dashes, relative to dash-period. Should be between 0.1 and 1.0 (continuous line). If set to 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.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

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 “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 Staff.StaffSymbol.thickness).

zigzag-length (dimension, in staff space)

The length of the lines of a zigzag, relative to zigzag-width. A value of 1 gives 60-degree zigzags.

zigzag-width (dimension, in staff space)

The width of one zigzag squiggle. This number is adjusted slightly so that the glissando line can be constructed from a whole number of squiggles.

This grob interface is used in the following graphical object(s): DynamicTextSpanner, Episema, Glissando, Hairpin, HorizontalBracket, LigatureBracket, MeasureSpanner, OttavaBracket, PianoPedalBracket, TextSpanner, TrillSpanner, TupletBracket, VoiceFollower, VoltaBracket and VowelTransition.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.62 line-spanner-interface

Generic line drawn between two objects, e.g., for use with glissandi.

bound-details is a nested alist. It’s possible to specify settings for the sub-properties: left, left-broken, right and right-broken.

Values for the following keys may be set:

Y

Sets the Y coordinate of the end point, in staff-spaces offset from the staff center line. By default, it is the center of the bound object, so a glissando points to the vertical center of the note head. For horizontal spanners, such as text spanners and trill spanners, it is hardcoded to 0.

attach-dir

Determines where the line starts and ends in the X direction, relative to the bound object. So, a value of -1 (or LEFT) makes the line start/end at the left side of the note head it is attached to.

X

This is the absolute X coordinate of the end point. Usually computed on the fly.

stencil

Line spanners may have symbols at the beginning or end, which is contained in this sub-property. For internal use.

text

This is a markup that is evaluated to yield the stencil.

stencil-align-dir-y
stencil-offset

Without setting one of these, the stencil is simply put at the end-point, centered on the line, as defined by the X and Y sub-properties. Setting stencil-align-dir-y moves the symbol at the edge vertically relative to the end point of the line. With stencil-offset, expecting a number pair, the stencil is moved along the X axis according to the first value, the second value moves the stencil along the Y axis.

arrow

Produces an arrowhead at the end-points of the line.

padding

Controls the space between the specified end point of the line and the actual end. Without padding, a glissando would start and end in the center of each note head.

User settable properties:

bound-details (list)

An alist of properties for determining attachments of spanners to edges.

extra-dy (number)

Slope glissandi this much extra.

gap (dimension, in staff space)

Size of a gap in a variable symbol.

left-bound-info (list)

An alist of properties for determining attachments of spanners to edges.

right-bound-info (list)

An alist of properties for determining attachments of spanners to edges.

simple-Y (boolean)

Should the Y placement of a spanner disregard changes in system heights?

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 “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 Staff.StaffSymbol.thickness).

to-barline (boolean)

If true, the spanner will stop at the bar line just before it would otherwise stop.

Internal properties:

note-columns (array of grobs)

An array of NoteColumn grobs.

This grob interface is used in the following graphical object(s): DynamicTextSpanner, Episema, Glissando, TextSpanner, TrillSpanner, VoiceFollower and VowelTransition.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.63 lyric-extender-interface

The extender is a simple line at the baseline of the lyric that helps show the length of a melisma (a tied or slurred note).

User settable properties:

left-padding (dimension, in staff space)

The amount of space that is put left to an object (e.g., a lyric extender).

next (graphical (layout) object)

Object that is next relation (e.g., the lyric syllable following an extender).

right-padding (dimension, in staff space)

Space to insert on the right side of an object (e.g., between note and its accidentals).

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

heads (array of grobs)

An array of note heads.

This grob interface is used in the following graphical object(s): LyricExtender.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.64 lyric-hyphen-interface

A centered hyphen is simply a line between lyrics used to divide syllables.

User settable properties:

dash-period (number)

The length of one dash together with whitespace. If negative, no line is drawn at all.

height (dimension, in staff space)

Height of an object in staff-space units.

length (dimension, in staff space)

User override for the stem length of unbeamed stems (each unit represents half a staff-space).

minimum-distance (dimension, in staff space)

Minimum distance between rest and notes or beam.

minimum-length (dimension, in staff space)

Try to make a spanner at least this long, normally in the horizontal direction. This requires an appropriate callback for the springs-and-rods property. If added to a Tie, this sets the minimum distance between noteheads.

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

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 “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 Staff.StaffSymbol.thickness).

This grob interface is used in the following graphical object(s): LyricHyphen and LyricSpace.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.65 lyric-interface

Any object that is related to lyrics.

This grob interface is used in the following graphical object(s): LyricExtender, LyricHyphen and VowelTransition.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.66 lyric-syllable-interface

A single piece of lyrics.

This grob interface is used in the following graphical object(s): LyricText.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.67 mark-interface

A rehearsal mark.

This grob interface is used in the following graphical object(s): RehearsalMark.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.68 measure-counter-interface

A counter for numbering measures.

User settable properties:

count-from (integer)

The first measure in a measure count receives this number. The following measures are numbered in increments from this initial value.

spacing-pair (pair)

A pair of alignment symbols which set an object’s spacing relative to its left and right BreakAlignments.

For example, a MultiMeasureRest will ignore prefatory items at its bounds (i.e., clefs, key signatures and time signatures) using the following override:

 
\override MultiMeasureRest.spacing-pair = #'(staff-bar . staff-bar)

Internal properties:

columns (array of grobs)

An array of grobs, typically containing PaperColumn or NoteColumn objects.

This grob interface is used in the following graphical object(s): MeasureCounter.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.69 measure-grouping-interface

This object indicates groups of beats. Valid choices for style are bracket and triangle.

User settable properties:

height (dimension, in staff space)

Height of an object in staff-space units.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

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 “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 Staff.StaffSymbol.thickness).

This grob interface is used in the following graphical object(s): MeasureGrouping.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.70 measure-spanner-interface

A bracket aligned to a measure or measures.

User settable properties:

bracket-flare (pair of numbers)

A pair of numbers specifying how much edges of brackets should slant outward. Value 0.0 means straight edges.

bracket-visibility (boolean or symbol)

This controls the visibility of the tuplet bracket. Setting it to false prevents printing of the bracket. Setting the property to if-no-beam makes it print only if there is no beam associated with this tuplet bracket.

connect-to-neighbor (pair)

Pair of booleans, indicating whether this grob looks as a continued break.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

edge-height (pair)

A pair of numbers specifying the heights of the vertical edges: (left-height . right-height).

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

shorten-pair (pair of numbers)

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.

spacing-pair (pair)

A pair of alignment symbols which set an object’s spacing relative to its left and right BreakAlignments.

For example, a MultiMeasureRest will ignore prefatory items at its bounds (i.e., clefs, key signatures and time signatures) using the following override:

 
\override MultiMeasureRest.spacing-pair = #'(staff-bar . staff-bar)
staff-padding (dimension, in staff space)

Maintain this much space between reference points and the staff. Its effect is to align objects of differing sizes (like the dynamics p and f) on their baselines.

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 “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 Staff.StaffSymbol.thickness).

This grob interface is used in the following graphical object(s): MeasureSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.71 melody-spanner-interface

Context dependent typesetting decisions.

User settable properties:

neutral-direction (direction)

Which direction to take in the center of the staff.

Internal properties:

stems (array of grobs)

An array of stem objects.

This grob interface is used in the following graphical object(s): MelodyItem.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.72 mensural-ligature-interface

A mensural ligature.

User settable properties:

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

add-join (boolean)

Is this ligature head-joined with the next one by a vertical line?

delta-position (number)

The vertical position difference.

flexa-interval (integer)

The interval spanned by the two notes of a flexa shape (1 is a second, 7 is an octave).

head-width (dimension, in staff space)

The width of this ligature head.

ligature-flexa (boolean)

request joining note to the previous one in a flexa.

primitive (integer)

A pointer to a ligature primitive, i.e., an item similar to a note head that is part of a ligature.

This grob interface is used in the following graphical object(s): MensuralLigature and NoteHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.73 metronome-mark-interface

A metronome mark.

This grob interface is used in the following graphical object(s): MetronomeMark.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.74 multi-measure-interface

Multi measure rest, and the text or number that is printed over it.

User settable properties:

bound-padding (number)

The amount of padding to insert around spanner bounds.

This grob interface is used in the following graphical object(s): MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestScript and MultiMeasureRestText.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.75 multi-measure-rest-interface

A rest that spans a whole number of measures.

User settable properties:

bound-padding (number)

The amount of padding to insert around spanner bounds.

expand-limit (integer)

Maximum number of measures expanded in church rests.

hair-thickness (number)

Thickness of the thin line in a bar line, expressed as a multiple of the default staff-line thickness (i.e. the visual output is not influenced by changes to Staff.StaffSymbol.thickness).

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.

minimum-length (dimension, in staff space)

Try to make a spanner at least this long, normally in the horizontal direction. This requires an appropriate callback for the springs-and-rods property. If added to a Tie, this sets the minimum distance between noteheads.

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 round-up-to-longer-rest.

round-up-to-longer-rest (boolean)

Displays the longer multi-measure rest when the length of a measure is between two values of usable-duration-logs. For example, displays a breve instead of a whole in a 3/2 measure.

spacing-pair (pair)

A pair of alignment symbols which set an object’s spacing relative to its left and right BreakAlignments.

For example, a MultiMeasureRest will ignore prefatory items at its bounds (i.e., clefs, key signatures and time signatures) using the following override:

 
\override MultiMeasureRest.spacing-pair = #'(staff-bar . staff-bar)
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 not influenced by changes to Staff.StaffSymbol.thickness).

usable-duration-logs (list)

List of duration-logs that can be used in typesetting the grob.

Internal properties:

space-increment (dimension, in staff space)

The amount by which the total duration of a multimeasure rest affects horizontal spacing. Each doubling of the duration adds space-increment to the length of the bar.

This grob interface is used in the following graphical object(s): MultiMeasureRest and PercentRepeat.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.76 note-collision-interface

An object that handles collisions between notes with different stem directions and horizontal shifts. Most of the interesting properties are to be set in note-column-interface: these are force-hshift and horizontal-shift.

User settable properties:

merge-differently-dotted (boolean)

Merge note heads in collisions, even if they have a different number of dots. This is normal notation for some types of polyphonic music.

merge-differently-dotted only applies to opposing stem directions (i.e., voice 1 & 2).

merge-differently-headed (boolean)

Merge note heads in collisions, even if they have different note heads. The smaller of the two heads is rendered invisible. This is used in polyphonic guitar notation. The value of this setting is used by (internals)note-collision-interface section ‘note-collision-interface’ in Internals Reference.

merge-differently-headed only applies to opposing stem directions (i.e., voice 1 & 2).

note-collision-threshold (dimension, in staff space)

Simultaneous notes that are this close or closer in units of staff-space will be identified as vertically colliding. Used by Stem grobs for notes in the same voice, and NoteCollision grobs for notes in different voices. Default value 1.

prefer-dotted-right (boolean)

For note collisions, prefer to shift dotted up-note to the right, rather than shifting just the dot.

Internal properties:

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

This grob interface is used in the following graphical object(s): NoteCollision.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.77 note-column-interface

Stem and noteheads combined.

User settable properties:

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 (internals)note-collision-interface section ‘note-collision-interface’ in Internals Reference.

glissando-skip (boolean)

Should this NoteHead be skipped by glissandi?

horizontal-shift (integer)

An integer that identifies ranking of NoteColumns for horizontal shifting. This is used by (internals)note-collision-interface section ‘note-collision-interface’ in Internals Reference.

ignore-collision (boolean)

If set, don’t do note collision resolution on this NoteColumn.

Internal properties:

note-heads (array of grobs)

An array of note head grobs.

rest (graphical (layout) object)

A pointer to a Rest object.

rest-collision (graphical (layout) object)

A rest collision that a rest is in.

stem (graphical (layout) object)

A pointer to a Stem object.

This grob interface is used in the following graphical object(s): NoteColumn.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.78 note-head-interface

A note head. There are many possible values for style. For a complete list, see (notation)Note head styles section ‘Note head styles’ in Notation Reference.

User settable properties:

duration-log (integer)

The 2-log of the note head duration, i.e., 0 = whole note, 1 = half note, etc.

glyph-name (string)

The glyph name within the font.

In the context of (span) bar lines, glyph-name represents a processed form of glyph, where decisions about line breaking etc. are already taken.

ignore-ambitus (boolean)

If set, don’t consider this notehead for ambitus calculation.

ledger-positions (list)

Vertical positions of ledger lines. When set on a StaffSymbol grob it defines a repeating pattern of ledger lines and any parenthesized groups will always be shown together.

note-names (vector)

Vector of strings containing names for easy-notation note heads.

stem-attachment (pair of numbers)

An (x . y) pair where the stem attaches to the notehead.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

Internal properties:

accidental-grob (graphical (layout) object)

The accidental for this note.

This grob interface is used in the following graphical object(s): AmbitusNoteHead, NoteHead, TabNoteHead and TrillPitchGroup.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.79 note-name-interface

Note names.

This grob interface is used in the following graphical object(s): NoteName.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.80 note-spacing-interface

This object calculates spacing wishes for individual voices.

User settable properties:

knee-spacing-correction (number)

Factor for the optical correction amount for kneed beams. Set between 0 for no correction and 1 for full correction.

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 stem distance.

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.

stem-spacing-correction (number)

Optical correction amount for stems that are placed in tight configurations. For opposite directions, this amount is the correction for two normal sized stems that overlap completely.

Internal properties:

left-items (array of grobs)

Grobs organized on the left by a spacing object.

right-items (array of grobs)

Grobs organized on the right by a spacing object.

This grob interface is used in the following graphical object(s): NoteSpacing.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.81 number-interface

Numbers.

User settable properties:

number-type (symbol)

Numbering style. Choices include roman-lower, roman-upper and arabic.

This grob interface is used in the following graphical object(s): StringNumber.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.82 only-prebreak-interface

Kill this grob after the line breaking process.

This grob interface is not used in any graphical object.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.83 ottava-bracket-interface

An ottava bracket.

User settable properties:

bracket-flare (pair of numbers)

A pair of numbers specifying how much edges of brackets should slant outward. Value 0.0 means straight edges.

dashed-edge (boolean)

If set, the bracket edges are dashed like the rest of the bracket.

edge-height (pair)

A pair of numbers specifying the heights of the vertical edges: (left-height . right-height).

minimum-length (dimension, in staff space)

Try to make a spanner at least this long, normally in the horizontal direction. This requires an appropriate callback for the springs-and-rods property. If added to a Tie, this sets the minimum distance between noteheads.

shorten-pair (pair of numbers)

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.

This grob interface is used in the following graphical object(s): OttavaBracket.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.84 outside-staff-axis-group-interface

A vertical axis group on which outside-staff skyline calculations are done.

User settable properties:

outside-staff-placement-directive (symbol)

One of four directives telling how outside staff objects should be placed.

  • left-to-right-greedy – Place each successive grob from left to right.
  • left-to-right-polite – Place a grob from left to right only if it does not potentially overlap with another grob that has been placed on a pass through a grob array. If there is overlap, do another pass to determine placement.
  • right-to-left-greedy – Same as left-to-right-greedy, but from right to left.
  • right-to-left-polite – Same as left-to-right-polite, but from right to left.

Internal properties:

vertical-skyline-elements (array of grobs)

An array of grobs used to create vertical skylines.

This grob interface is used in the following graphical object(s): BassFigureLine, System and VerticalAxisGroup.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.85 outside-staff-interface

A grob that could be placed outside staff.

User settable properties:

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 grobs when spacing according to outside-staff-priority. Two grobs with different outside-staff-padding values have the larger value of padding between them.

outside-staff-priority (number)

If set, the grob is positioned outside the staff in such a way as to avoid all collisions. In case of a potential collision, the grob with the smaller outside-staff-priority is closer to the staff.

This grob interface is used in the following graphical object(s): AccidentalSuggestion, BarNumber, BassFigureAlignmentPositioning, BreathingSign, ChordName, ClefModifier, CombineTextScript, DoublePercentRepeatCounter, DoubleRepeatSlash, DynamicLineSpanner, DynamicText, Fingering, FretBoard, Hairpin, HorizontalBracket, HorizontalBracketText, InstrumentSwitch, MeasureCounter, MeasureGrouping, MeasureSpanner, MetronomeMark, MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestScript, MultiMeasureRestText, OttavaBracket, PercentRepeatCounter, PhrasingSlur, RehearsalMark, Script, Slur, SostenutoPedalLineSpanner, StringNumber, StrokeFinger, SustainPedalLineSpanner, TextScript, TextSpanner, TrillSpanner, TupletBracket, TupletNumber, UnaCordaPedalLineSpanner and VoltaBracketSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.86 paper-column-interface

Paper_column objects form the top-most X parents for items. There are two types of columns: musical and non-musical, to which musical and non-musical objects are attached respectively. The spacing engine determines the X positions of these objects.

They are numbered, the first (leftmost) is column 0. Numbering happens before line breaking, and columns are not renumbered after line breaking. Since many columns go unused, you should only use the rank field to get ordering information. Two adjacent columns may have non-adjacent numbers.

User settable properties:

between-cols (pair)

Where to attach a loose column to.

full-measure-extra-space (number)

Extra space that is allocated at the beginning of a measure with only one note. This property is read from the NonMusicalPaperColumn that begins the measure.

labels (list)

List of labels (symbols) placed on a column.

line-break-penalty (number)

Penalty for a line break at this column. This affects the choices of the line breaker; it avoids a line break at a column with a positive penalty and prefers a line break at a column with a negative penalty.

line-break-permission (symbol)

Instructs the line breaker on whether to put a line break at this column. Can be force or allow.

line-break-system-details (list)

An alist of properties to use if this column is the start of a system.

page-break-penalty (number)

Penalty for page break at this column. This affects the choices of the page breaker; it avoids a page break at a column with a positive penalty and prefers a page break at a column with a negative penalty.

page-break-permission (symbol)

Instructs the page breaker on whether to put a page break at this column. Can be force or allow.

page-turn-penalty (number)

Penalty for a page turn at this column. This affects the choices of the page breaker; it avoids a page turn at a column with a positive penalty and prefers a page turn 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 force or allow.

rhythmic-location (rhythmic location)

Where (bar number, measure position) in the score.

shortest-playing-duration (moment)

The duration of the shortest note playing here.

shortest-starter-duration (moment)

The duration of the shortest note that starts here.

used (boolean)

If set, this spacing column is kept in the spacing problem.

when (moment)

Global time step associated with this column.

Internal properties:

bounded-by-me (array of grobs)

An array of spanners that have this column as start/begin point. Only columns that have grobs or act as bounds are spaced.

grace-spacing (graphical (layout) object)

A run of grace notes.

maybe-loose (boolean)

Used to mark a breakable column that is loose if and only if it is in the middle of a line.

spacing (graphical (layout) object)

The spacing spanner governing this section.

This grob interface is used in the following graphical object(s): NonMusicalPaperColumn and PaperColumn.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.87 parentheses-interface

Parentheses for other objects.

User settable properties:

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

stencils (list)

Multiple stencils, used as intermediate value.

This grob interface is used in the following graphical object(s): ParenthesesItem and TrillPitchGroup.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.88 percent-repeat-interface

Beat, Double and single measure repeats.

User settable properties:

dot-negative-kern (number)

The space to remove between a dot and a slash in percent repeat glyphs. Larger values bring the two elements closer together.

slash-negative-kern (number)

The space to remove between slashes in percent repeat glyphs. Larger values bring the two elements closer together.

slope (number)

The slope of this object.

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 “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 Staff.StaffSymbol.thickness).

This grob interface is used in the following graphical object(s): DoublePercentRepeat, DoublePercentRepeatCounter, DoubleRepeatSlash, PercentRepeat, PercentRepeatCounter and RepeatSlash.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.89 percent-repeat-item-interface

Repeats that look like percent signs.

User settable properties:

dot-negative-kern (number)

The space to remove between a dot and a slash in percent repeat glyphs. Larger values bring the two elements closer together.

slash-negative-kern (number)

The space to remove between slashes in percent repeat glyphs. Larger values bring the two elements closer together.

slope (number)

The slope of this object.

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 “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 Staff.StaffSymbol.thickness).

This grob interface is used in the following graphical object(s): DoublePercentRepeat, DoublePercentRepeatCounter, DoubleRepeatSlash and RepeatSlash.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.90 piano-pedal-bracket-interface

The bracket of the piano pedal. It can be tuned through the regular bracket properties.

User settable properties:

bound-padding (number)

The amount of padding to insert around spanner bounds.

bracket-flare (pair of numbers)

A pair of numbers specifying how much edges of brackets should slant outward. Value 0.0 means straight edges.

dashed-edge (boolean)

If set, the bracket edges are dashed like the rest of the bracket.

edge-height (pair)

A pair of numbers specifying the heights of the vertical edges: (left-height . right-height).

shorten-pair (pair of numbers)

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.

Internal properties:

pedal-text (graphical (layout) object)

A pointer to the text of a mixed-style piano pedal.

This grob interface is used in the following graphical object(s): PianoPedalBracket.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.91 piano-pedal-interface

A piano pedal sign.

This grob interface is used in the following graphical object(s): PianoPedalBracket, SostenutoPedalLineSpanner, SustainPedal, SustainPedalLineSpanner and UnaCordaPedalLineSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.92 piano-pedal-script-interface

A piano pedal sign, fixed size.

This grob interface is used in the following graphical object(s): SostenutoPedal, SustainPedal and UnaCordaPedal.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.93 pitched-trill-interface

A note head to indicate trill pitches.

Internal properties:

accidental-grob (graphical (layout) object)

The accidental for this note.

This grob interface is used in the following graphical object(s): TrillPitchHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.94 pure-from-neighbor-interface

A collection of routines to allow for objects’ pure heights and heights to be calculated based on the heights of the objects’ neighbors.

Internal properties:

neighbors (array of grobs)

The X-axis neighbors of a grob. Used by the pure-from-neighbor-interface to determine various grob heights.

pure-relevant-grobs (array of grobs)

All the grobs (items and spanners) that are relevant for finding the pure-Y-extent

pure-Y-common (graphical (layout) object)

A cache of the common_refpoint_of_array of the elements grob set.

This grob interface is used in the following graphical object(s): BarLine, Clef, CueClef, CueEndClef, KeyCancellation, KeySignature, SpanBarStub and TimeSignature.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.95 rest-collision-interface

Move ordinary rests (not multi-measure nor pitched rests) to avoid conflicts.

User settable properties:

minimum-distance (dimension, in staff space)

Minimum distance between rest and notes or beam.

Internal properties:

elements (array of grobs)

An array of grobs; the type is depending on the grob where this is set in.

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

This grob interface is used in the following graphical object(s): RestCollision.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.96 rest-interface

A rest symbol. The property style can be default, mensural, neomensural or classical.

User settable properties:

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

minimum-distance (dimension, in staff space)

Minimum distance between rest and notes or beam.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

voiced-position (number)

The staff-position of a voiced Rest, negative if the rest has direction DOWN.

This grob interface is used in the following graphical object(s): MultiMeasureRest and Rest.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.97 rhythmic-grob-interface

Any object with a duration. Used to determine which grobs are interesting enough to maintain a hara-kiri staff.

This grob interface is used in the following graphical object(s): BassFigure, ChordName, ClusterSpannerBeacon, DoubleRepeatSlash, FretBoard, LyricText, NoteHead, RepeatSlash, Rest and TabNoteHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.98 rhythmic-head-interface

Note head or rest.

User settable properties:

duration-log (integer)

The 2-log of the note head duration, i.e., 0 = whole note, 1 = half note, etc.

glissando-skip (boolean)

Should this NoteHead be skipped by glissandi?

Internal properties:

dot (graphical (layout) object)

A reference to a Dots object.

stem (graphical (layout) object)

A pointer to a Stem object.

This grob interface is used in the following graphical object(s): AmbitusNoteHead, NoteHead, Rest, TabNoteHead and TrillPitchHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.99 script-column-interface

An interface that sorts scripts according to their script-priority and outside-staff-priority.

Internal properties:

scripts (array of grobs)

An array of Script objects.

This grob interface is used in the following graphical object(s): ScriptColumn and ScriptRow.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.100 script-interface

An object that is put above or below a note.

User settable properties:

avoid-slur (symbol)

Method of handling slur collisions. Choices are inside, outside, around, and ignore. inside adjusts the slur if needed to keep the grob inside the slur. outside moves the grob vertically to the outside of the slur. around moves the grob vertically to the outside of the slur only if there is a collision. ignore does not move either. In grobs whose notational significance depends on vertical position (such as accidentals, clefs, etc.), outside and around behave like ignore.

script-priority (number)

A key for determining the order of 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.

side-relative-direction (direction)

Multiply direction of direction-source with this to get the direction of this object.

slur-padding (number)

Extra distance between slur and script.

toward-stem-shift (number)

Amount by which scripts are shifted toward the stem if their direction coincides with the stem direction. 0.0 means centered on the note head (the default position of most scripts); 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 ScriptColumn object. 0.0 means centered on the note head (the default position of most scripts); 1.0 means centered on the stem. Interpolated values are possible.

Internal properties:

direction-source (graphical (layout) object)

In case side-relative-direction is set, which grob to get the direction from.

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

script-column (graphical (layout) object)

A ScriptColumn associated with a Script object.

script-stencil (pair)

A pair (type . arg) which acts as an index for looking up a Stencil object.

slur (graphical (layout) object)

A pointer to a Slur object.

This grob interface is used in the following graphical object(s): AccidentalSuggestion, DynamicText, MultiMeasureRestScript and Script.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.101 self-alignment-interface

Position this object on itself and/or on its parent. To this end, the following functions are provided:

Self_alignment_interface::[xy]_aligned_on_self

Align self on reference point, using self-alignment-X and self-alignment-Y.

Self_alignment_interface::aligned_on_[xy]_parent
Self_alignment_interface::centered_on_[xy]_parent

Shift the object so its own reference point is centered on the extent of the parent

User settable properties:

parent-alignment-X (number)

Specify on which point of the parent the object is aligned. The value -1 means aligned on parent’s left edge, 0 on center, and 1 right edge, in X direction. Other numerical values may also be specified - the unit is half the parent’s width. If unset, the value from self-alignment-X property will be used.

parent-alignment-Y (number)

Like parent-alignment-X but for the Y axis.

self-alignment-X (number)

Specify alignment of an object. The value -1 means left aligned, 0 centered, and 1 right-aligned in X direction. Other numerical values may also be specified - the unit is half the object width.

self-alignment-Y (number)

Like self-alignment-X but for the Y axis.

X-align-on-main-noteheads (boolean)

If true, this grob will ignore suspended noteheads when aligning itself on NoteColumn.

This grob interface is used in the following graphical object(s): AccidentalSuggestion, BarNumber, ClefModifier, CombineTextScript, DoublePercentRepeatCounter, DynamicText, Fingering, GridLine, Hairpin, HorizontalBracketText, InstrumentName, InstrumentSwitch, LyricText, MeasureCounter, MeasureSpanner, MetronomeMark, MultiMeasureRestNumber, MultiMeasureRestScript, MultiMeasureRestText, PercentRepeatCounter, RehearsalMark, Script, SostenutoPedal, StemTremolo, StringNumber, StrokeFinger, SustainPedal, TextScript and UnaCordaPedal.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.102 semi-tie-column-interface

The interface for a column of l.v. (laissez vibrer) ties.

User settable properties:

head-direction (direction)

Are the note heads left or right in a semitie?

tie-configuration (list)

List of (position . dir) pairs, indicating the desired tie configuration, where position is the offset from the center of the staff in staff space and dir indicates the direction of the tie (1=>up, -1=>down, 0=>center). A non-pair entry in the list causes the corresponding tie to be formatted automatically.

Internal properties:

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

ties (array of grobs)

A grob array of Tie objects.

This grob interface is used in the following graphical object(s): LaissezVibrerTieColumn and RepeatTieColumn.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.103 semi-tie-interface

A tie which is only connected to a note head on one side. The following properties may be set in the details list:

height-limit

Maximum tie height: The longer the tie, the closer it is to this height.

ratio

Parameter for tie shape. The higher this number, the quicker the tie attains its height-limit.

User settable properties:

control-points (list of number pairs)

List of offsets (number pairs) that form control points for the tie, slur, or bracket shape. For Béziers, this should list the control points of a third-order Bézier curve.

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 having a details property.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

head-direction (direction)

Are the note heads left or right in a semitie?

line-thickness (number)

For slurs and ties, this is the diameter of the virtual “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 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 “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 Staff.StaffSymbol.thickness).

Internal properties:

note-head (graphical (layout) object)

A single note head.

This grob interface is used in the following graphical object(s): LaissezVibrerTie and RepeatTie.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.104 separation-item-interface

Item that computes widths to generate spacing rods.

User settable properties:

horizontal-skylines (pair of skylines)

Two skylines, one to the left and one to the right of this grob.

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

skyline-vertical-padding (number)

The amount by which the left and right skylines of a column are padded vertically, beyond the Y-extents and extra-spacing-heights of the constituent grobs in the column. Increase this to prevent interleaving of grobs from adjacent columns.

X-extent (pair of numbers)

Extent (size) in the X direction, measured in staff-space units, relative to object’s reference point.

Internal properties:

conditional-elements (array of grobs)

Internal use only.

elements (array of grobs)

An array of grobs; the type is depending on the grob where this is set in.

This grob interface is used in the following graphical object(s): NonMusicalPaperColumn, NoteColumn and PaperColumn.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.105 side-position-interface

Position a victim object (this one) next to other objects (the support). The property direction signifies where to put the victim object relative to the support (left or right, up or down?)

The routine also takes the size of the staff into account if staff-padding is set. If undefined, the staff symbol is ignored.

User settable properties:

add-stem-support (boolean)

If set, the Stem object is included in this script’s support.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

horizon-padding (number)

The amount to pad the axis along which a Skyline is built for the side-position-interface.

minimum-space (dimension, in staff space)

Minimum distance that the victim should move (after padding).

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

side-axis (number)

If the value is X (or equivalently 0), the object is placed horizontally next to the other object. If the value is Y or 1, it is placed vertically.

slur-padding (number)

Extra distance between slur and script.

staff-padding (dimension, in staff space)

Maintain this much space between reference points and the staff. Its effect is to align objects of differing sizes (like the dynamics p and f) on their baselines.

use-skylines (boolean)

Should skylines be used for side positioning?

Internal properties:

quantize-position (boolean)

If set, a vertical alignment is aligned to be within staff spaces.

side-support-elements (array of grobs)

The side support, an array of grobs.

This grob interface is used in the following graphical object(s): AccidentalSuggestion, AmbitusAccidental, Arpeggio, BarNumber, BassFigureAlignmentPositioning, ClefModifier, CombineTextScript, DoublePercentRepeatCounter, DynamicLineSpanner, Episema, Fingering, HorizontalBracket, HorizontalBracketText, InstrumentName, InstrumentSwitch, MeasureCounter, MeasureGrouping, MeasureSpanner, MetronomeMark, MultiMeasureRestNumber, MultiMeasureRestScript, MultiMeasureRestText, OttavaBracket, PercentRepeatCounter, RehearsalMark, Script, SostenutoPedalLineSpanner, StanzaNumber, StringNumber, StrokeFinger, SustainPedalLineSpanner, SystemStartBar, SystemStartBrace, SystemStartBracket, SystemStartSquare, TextScript, TextSpanner, TrillPitchAccidental, TrillPitchGroup, TrillSpanner, UnaCordaPedalLineSpanner, VoltaBracket and VoltaBracketSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.106 slur-interface

A slur. Slurs are formatted by trying a number of combinations of left/right end point, and then picking the slur with the lowest demerit score. The combinations are generated by going from the base attachments (i.e., note heads) in the direction in half space increments until we have covered region-size staff spaces. The following properties may be set in the details list.

region-size

Size of region (in staff spaces) for determining potential endpoints in the Y direction.

head-encompass-penalty

Demerit to apply when note heads collide with a slur.

stem-encompass-penalty

Demerit to apply when stems collide with a slur.

edge-attraction-factor

Factor used to calculate the demerit for distances between slur endpoints and their corresponding base attachments.

same-slope-penalty

Demerit for slurs with attachment points that are horizontally aligned.

steeper-slope-factor

Factor used to calculate demerit only if this slur is not broken.

non-horizontal-penalty

Demerit for slurs with attachment points that are not horizontally aligned.

max-slope

The maximum slope allowed for this slur.

max-slope-factor

Factor that calculates demerit based on the max slope.

free-head-distance

The amount of vertical free space that must exist between a slur and note heads.

absolute-closeness-measure

Factor to calculate demerit for variance between a note head and slur.

extra-object-collision-penalty

Factor to calculate demerit for extra objects that the slur encompasses, including accidentals, fingerings, and tuplet numbers.

accidental-collision

Factor to calculate demerit for Accidental objects that the slur encompasses. This property value replaces the value of extra-object-collision-penalty.

extra-encompass-free-distance

The amount of vertical free space that must exist between a slur and various objects it encompasses, including accidentals, fingerings, and tuplet numbers.

extra-encompass-collision-distance

This detail is currently unused.

head-slur-distance-factor

Factor to calculate demerit for variance between a note head and slur.

head-slur-distance-max-ratio

The maximum value for the ratio of distance between a note head and slur.

gap-to-staffline-inside

Minimum gap inside the curve of the slur where the slur is parallel to a staffline.

gap-to-staffline-outside

Minimum gap outside the curve of the slur where the slur is parallel to a staffline.

free-slur-distance

The amount of vertical free space that must exist between adjacent slurs. This subproperty only works for PhrasingSlur.

edge-slope-exponent

Factor used to calculate the demerit for the slope of a slur near its endpoints; a larger value yields a larger demerit.

User settable properties:

annotation (string)

Annotate a grob for debug purposes.

avoid-slur (symbol)

Method of handling slur collisions. Choices are inside, outside, around, and ignore. inside adjusts the slur if needed to keep the grob inside the slur. outside moves the grob vertically to the outside of the slur. around moves the grob vertically to the outside of the slur only if there is a collision. ignore does not move either. In grobs whose notational significance depends on vertical position (such as accidentals, clefs, etc.), outside and around behave like ignore.

control-points (list of number pairs)

List of offsets (number pairs) that form control points for the tie, slur, or bracket shape. For Béziers, this should list the control points of a third-order Bézier curve.

dash-definition (pair)

List of dash-elements defining the dash structure. Each dash-element has a starting t value, an ending t-value, a dash-fraction, and a dash-period.

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 having a details property.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

eccentricity (number)

How asymmetrical to make a slur. Positive means move the center to the right.

height-limit (dimension, in staff space)

Maximum slur height: The longer the slur, the closer it is to this height.

inspect-quants (pair of numbers)

If debugging is set, set beam and slur position to a (quantized) position that is as close as possible to this value, and print the demerits for the inspected position in the output.

line-thickness (number)

For slurs and ties, this is the diameter of the virtual “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 Staff.StaffSymbol.thickness).

positions (pair of numbers)

Pair of staff coordinates (left . right), where both left and right are in staff-space units of the current staff. For slurs, this value selects which slur candidate to use; if extreme positions are requested, the closest one is taken.

ratio (number)

Parameter for slur shape. The higher this number, the quicker the slur attains its height-limit.

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

encompass-objects (array of grobs)

Objects that a slur should avoid in addition to notes and stems.

note-columns (array of grobs)

An array of NoteColumn grobs.

This grob interface is used in the following graphical object(s): PhrasingSlur and Slur.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.107 spaceable-grob-interface

A layout object that takes part in the spacing problem.

User settable properties:

allow-loose-spacing (boolean)

If set, column can be detached from main spacing.

keep-inside-line (boolean)

If set, this column cannot have objects sticking into the margin.

measure-length (moment)

Length of a measure. Used in some spacing situations.

Internal properties:

ideal-distances (list)

(obj . (dist . strength)) pairs.

left-neighbor (graphical (layout) object)

The right-most column that has a spacing-wish for this column.

minimum-distances (list)

A list of rods that have the format (obj . dist).

right-neighbor (graphical (layout) object)

See left-neighbor.

spacing-wishes (array of grobs)

An array of note spacing or staff spacing objects.

This grob interface is used in the following graphical object(s): NonMusicalPaperColumn and PaperColumn.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.108 spacing-interface

This object calculates the desired and minimum distances between two columns.

Internal properties:

left-items (array of grobs)

Grobs organized on the left by a spacing object.

right-items (array of grobs)

Grobs organized on the right by a spacing object.

This grob interface is used in the following graphical object(s): NoteSpacing and StaffSpacing.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.109 spacing-options-interface

Supports setting of spacing variables.

User settable properties:

shortest-duration-space (number)

Start with this multiple of spacing-increment space for the shortest duration. See also (internals)spacing-spanner-interface section ‘spacing-spanner-interface’ in Internals Reference.

spacing-increment (dimension, in staff space)

The unit of length for note-spacing. Typically, the width of a note head. See also (internals)spacing-spanner-interface section ‘spacing-spanner-interface’ in Internals Reference.

This grob interface is used in the following graphical object(s): GraceSpacing and SpacingSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.110 spacing-spanner-interface

The space taken by a note is dependent on its duration. Doubling a duration adds spacing-increment to the space. The most common shortest note gets shortest-duration-space. Notes that are even shorter are spaced proportonial to their duration.

Typically, the increment is the width of a black note head. In a piece with lots of 8th notes, and some 16th notes, the eighth note gets a 2 note heads width (i.e., the space following a note is a 1 note head width). A 16th note is followed by 0.5 note head width. The quarter note is followed by 3 NHW, the half by 4 NHW, etc.

User settable properties:

average-spacing-wishes (boolean)

If set, the spacing wishes are averaged over staves.

base-shortest-duration (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.

common-shortest-duration (moment)

The most common shortest note length. This is used in spacing. Enlarging this sets the score tighter.

packed-spacing (boolean)

If set, the notes are spaced as tightly as possible.

shortest-duration-space (number)

Start with this multiple of spacing-increment space for the shortest duration. See also (internals)spacing-spanner-interface section ‘spacing-spanner-interface’ in Internals Reference.

spacing-increment (dimension, in staff space)

The unit of length for note-spacing. Typically, the width of a note head. See also (internals)spacing-spanner-interface section ‘spacing-spanner-interface’ in Internals Reference.

strict-grace-spacing (boolean)

If set, main notes are spaced normally, then grace notes are put left of the musical columns for the main notes.

strict-note-spacing (boolean)

If set, unbroken columns with non-musical material (clefs, bar lines, etc.) are not spaced separately, but put before musical columns.

uniform-stretching (boolean)

If set, items stretch proportionally to their natural separation based on durations. This looks better in complex polyphonic patterns.

This grob interface is used in the following graphical object(s): SpacingSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.111 span-bar-interface

A bar line that is spanned between other barlines. This interface is used for bar lines that connect different staves.

User settable properties:

glyph-name (string)

The glyph name within the font.

In the context of (span) bar lines, glyph-name represents a processed form of glyph, where decisions about line breaking etc. are already taken.

Internal properties:

elements (array of grobs)

An array of grobs; the type is depending on the grob where this is set in.

pure-relevant-grobs (array of grobs)

All the grobs (items and spanners) that are relevant for finding the pure-Y-extent

pure-relevant-items (array of grobs)

A subset of elements that are relevant for finding the pure-Y-extent.

pure-relevant-spanners (array of grobs)

A subset of elements that are relevant for finding the pure-Y-extent.

pure-Y-common (graphical (layout) object)

A cache of the common_refpoint_of_array of the elements grob set.

This grob interface is used in the following graphical object(s): SpanBar.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.112 spanner-interface

Some objects are horizontally spanned between objects. For example, slurs, beams, ties, etc. These grobs form a subtype called Spanner. All spanners have two span points (these must be Item objects), one on the left and one on the right. The left bound is also the X reference point of the spanner.

User settable properties:

minimum-length (dimension, in staff space)

Try to make a spanner at least this long, normally in the horizontal direction. This requires an appropriate callback for the springs-and-rods property. If added to a Tie, this sets the minimum distance between noteheads.

minimum-length-after-break (dimension, in staff space)

If set, try to make a broken spanner starting a line this long. This requires an appropriate callback for the springs-and-rods property. If added to a Tie, this sets the minimum distance to the notehead.

normalized-endpoints (pair)

Represents left and right placement over the total spanner, where the width of the spanner is normalized between 0 and 1.

spanner-id (index or symbol)

An identifier to distinguish concurrent spanners.

to-barline (boolean)

If true, the spanner will stop at the bar line just before it would otherwise stop.

Internal properties:

spanner-broken (boolean)

Indicates whether spanner alignment should be broken after the current spanner.

This grob interface is used in the following graphical object(s): BalloonTextSpanner, BassFigureAlignment, BassFigureAlignmentPositioning, BassFigureContinuation, BassFigureLine, Beam, BendAfter, ClusterSpanner, DynamicLineSpanner, DynamicTextSpanner, Episema, FootnoteSpanner, Glissando, GraceSpacing, Hairpin, HorizontalBracket, HorizontalBracketText, InstrumentName, KievanLigature, LedgerLineSpanner, LigatureBracket, LyricExtender, LyricHyphen, LyricSpace, MeasureCounter, MeasureGrouping, MeasureSpanner, MensuralLigature, MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestScript, MultiMeasureRestText, OttavaBracket, PercentRepeat, PercentRepeatCounter, PhrasingSlur, PianoPedalBracket, Slur, SostenutoPedalLineSpanner, SpacingSpanner, StaffGrouper, StaffSymbol, SustainPedalLineSpanner, System, SystemStartBar, SystemStartBrace, SystemStartBracket, SystemStartSquare, TextSpanner, Tie, TieColumn, TrillSpanner, TupletBracket, TupletNumber, UnaCordaPedalLineSpanner, VaticanaLigature, VerticalAlignment, VerticalAxisGroup, VoiceFollower, VoltaBracket, VoltaBracketSpanner and VowelTransition.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.113 staff-grouper-interface

A grob that collects staves together.

User settable properties:

staff-staff-spacing (list)

When applied to a staff-group’s StaffGrouper grob, this spacing alist controls the distance between consecutive staves within the staff-group. When applied to a staff’s 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 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:

  • 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.
  • minimum-distance – the smallest allowable vertical distance, measured in staff-spaces, between the reference points of the two items, when compressing is in effect.
  • padding – the minimum required amount of unobstructed vertical whitespace between the bounding boxes (or skylines) of the two items, measured in staff-spaces.
  • stretchability – a unitless measure of the dimension’s relative propensity to stretch. If zero, the distance will not stretch (unless collisions would result).
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 staff-staff-spacing property of the staff’s VerticalAxisGroup grob is set, that is used instead. See staff-staff-spacing for a description of the alist structure.

This grob interface is used in the following graphical object(s): StaffGrouper.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.114 staff-spacing-interface

This object calculates spacing details from a breakable symbol (left) to another object. For example, it takes care of optical spacing from a bar line to a note.

User settable properties:

stem-spacing-correction (number)

Optical correction amount for stems that are placed in tight configurations. For opposite directions, this amount is the correction for two normal sized stems that overlap completely.

This grob interface is used in the following graphical object(s): StaffSpacing.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.115 staff-symbol-interface

This spanner draws the lines of a staff. A staff symbol defines a vertical unit, the staff space. Quantities that go by a half staff space are called positions. The center (i.e., middle line or space) is position 0. The length of the symbol may be set by hand through the width property.

User settable properties:

break-align-symbols (list)

A list of 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 break-visibility, we will align to the next grob (and so on). Choices are listed in (internals)break-alignment-interface section ‘break-alignment-interface’ in Internals Reference.

ledger-extra (dimension, in staff space)

Extra distance from staff line to draw ledger lines for.

ledger-line-thickness (pair of numbers)

The thickness of ledger lines. It is the sum of 2 numbers: The first is the factor for line thickness, and the second for staff space. Both contributions are added.

ledger-positions (list)

Vertical positions of ledger lines. When set on a StaffSymbol grob it defines a repeating pattern of ledger lines and any parenthesized groups will always be shown together.

ledger-positions-function (any type)

A quoted Scheme procedure that takes a StaffSymbol grob and the vertical position of a note head as arguments and returns a list of ledger line positions.

line-count (integer)

The number of staff lines.

line-positions (list)

Vertical positions of staff lines.

staff-space (dimension, in staff space)

Amount of space between staff lines, expressed in global staff-space.

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 “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 Staff.StaffSymbol.thickness).

width (dimension, in staff space)

The width of a grob measured in staff space.

This grob interface is used in the following graphical object(s): StaffSymbol.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.116 staff-symbol-referencer-interface

An object whose Y position is meant relative to a staff symbol. These usually have Staff_symbol_referencer::callback in their Y-offset-callbacks.

User settable properties:

staff-position (number)

Vertical position, measured in half staff spaces, counted from the middle line.

This grob interface is used in the following graphical object(s): AmbitusNoteHead, Arpeggio, Beam, Clef, CueClef, CueEndClef, Custos, Dots, KeyCancellation, KeySignature, MultiMeasureRest, NoteHead, Rest, TabNoteHead and TrillPitchHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.117 stanza-number-interface

A stanza number, to be put in from of a lyrics line.

This grob interface is used in the following graphical object(s): StanzaNumber.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.118 stem-interface

The stem represents the graphical stem. In addition, it internally connects note heads, beams, and tremolos. Rests and whole notes have invisible stems.

The following properties may be set in the details list.

beamed-lengths

List of stem lengths given beam multiplicity.

beamed-minimum-free-lengths

List of normal minimum free stem lengths (chord to beams) given beam multiplicity.

beamed-extreme-minimum-free-lengths

List of extreme minimum free stem lengths (chord to beams) given beam multiplicity.

lengths

Default stem lengths. The list gives a length for each flag count.

stem-shorten

How much a stem in a forced direction should be shortened. The list gives an amount depending on the number of flags and beams.

User settable properties:

avoid-note-head (boolean)

If set, the stem of a chord does not pass through all note heads, but starts at the last note head.

beaming (pair)

Pair of number lists. Each number list specifies which beams to make. 0 is the central beam, 1 is the next beam toward the note, etc. This information is used to determine how to connect the beaming patterns from stem to stem inside a beam.

beamlet-default-length (pair)

A pair of numbers. The first number specifies the default length of a beamlet that sticks out of the left hand side of this stem; the second number specifies the 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 beamlet-max-length-proportion, whichever is smaller.

beamlet-max-length-proportion (pair)

The maximum length of a beamlet, as a proportion of the distance between two adjacent stems.

default-direction (direction)

Direction determined by note head positions.

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 having a details property.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

double-stem-separation (number)

The distance between the two stems of a half note in tablature when using \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., 0 = whole note, 1 = half note, etc.

french-beaming (boolean)

Use French beaming style for this stem. The stem stops at the innermost beams.

length (dimension, in staff space)

User override for the stem length of unbeamed stems (each unit represents half a staff-space).

length-fraction (number)

Multiplier for lengths. Used for determining ledger lines and stem lengths.

max-beam-connect (integer)

Maximum number of beams to connect to beams from this stem. Further beams are typeset as beamlets.

neutral-direction (direction)

Which direction to take in the center of the staff.

no-stem-extend (boolean)

If set, notes with ledger lines do not get stems extending to the middle staff line.

note-collision-threshold (dimension, in staff space)

Simultaneous notes that are this close or closer in units of staff-space will be identified as vertically colliding. Used by Stem grobs for notes in the same voice, and NoteCollision grobs for notes in different voices. Default value 1.

stem-begin-position (number)

User override for the begin position of a stem.

stemlet-length (number)

How long should be a stem over a rest?

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

beam (graphical (layout) object)

A pointer to the beam, if applicable.

flag (graphical (layout) object)

A pointer to a Flag object.

french-beaming-stem-adjustment (dimension, in staff space)

Stem will be shortened by this amount of space in case of French beaming style.

melody-spanner (graphical (layout) object)

The MelodyItem object for a stem.

note-heads (array of grobs)

An array of note head grobs.

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

rests (array of grobs)

An array of rest objects.

stem-info (pair)

A cache of stem parameters.

tremolo-flag (graphical (layout) object)

The tremolo object on a stem.

tuplet-start (boolean)

Is stem at the start of a tuplet?

This grob interface is used in the following graphical object(s): Stem.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.119 stem-tremolo-interface

A beam slashing a stem to indicate a tremolo. The property shape can be beam-like or rectangle.

User settable properties:

beam-thickness (dimension, in staff space)

Beam thickness, measured in staff-space units.

beam-width (dimension, in staff space)

Width of the tremolo sign.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

flag-count (number)

The number of tremolo beams.

length-fraction (number)

Multiplier for lengths. Used for determining ledger lines and stem lengths.

shape (symbol)

This setting determines what shape a grob has. Valid choices depend on the stencil callback reading this property.

slope (number)

The slope of this object.

Internal properties:

stem (graphical (layout) object)

A pointer to a Stem object.

This grob interface is used in the following graphical object(s): StemTremolo.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.120 string-number-interface

A string number instruction.

This grob interface is used in the following graphical object(s): StringNumber.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.121 stroke-finger-interface

A right hand finger instruction.

User settable properties:

digit-names (vector)

Names for string finger digits.

This grob interface is used in the following graphical object(s): StrokeFinger.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.122 system-interface

This is the top-level object: Each object in a score ultimately has a System object as its X and Y parent.

User settable properties:

labels (list)

List of labels (symbols) placed on a column.

page-number (number)

Page number on which this system ends up.

rank-on-page (number)

0-based index of the system on a page.

Internal properties:

all-elements (array of grobs)

An array of all grobs in this line. Its function is to protect objects from being garbage collected.

columns (array of grobs)

An array of grobs, typically containing PaperColumn or NoteColumn objects.

footnote-stencil (stencil)

The stencil of a system’s footnotes.

footnotes-after-line-breaking (array of grobs)

Footnote grobs of a broken system.

footnotes-before-line-breaking (array of grobs)

Footnote grobs of a whole system.

in-note-direction (direction)

Direction to place in-notes above a system.

in-note-padding (number)

Padding between in-notes.

in-note-stencil (stencil)

The stencil of a system’s in-notes.

pure-Y-extent (pair of numbers)

The estimated height of a system.

vertical-alignment (graphical (layout) object)

The VerticalAlignment in a System.

This grob interface is used in the following graphical object(s): System.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.123 system-start-delimiter-interface

The brace, bracket or bar in front of the system. The following values for style are recognized:

bracket

A thick bracket, normally used to group similar instruments in a score. Default for StaffGroup. SystemStartBracket uses this style.

brace

A ‘piano style’ brace normally used for an instrument that uses two staves. The default style for GrandStaff. SystemStartBrace uses this style.

bar-line

A simple line between the staves in a score. Default for staves enclosed in << and >>. SystemStartBar uses this style.

line-bracket

A simple square, normally used for subgrouping instruments in a score. SystemStartSquare uses this style.

See also ‘input/regression/system-start-nesting.ly’.

User settable properties:

collapse-height (dimension, in staff space)

Minimum height of system start delimiter. If equal or smaller, the bracket/brace/line is removed.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

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 “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 Staff.StaffSymbol.thickness).

This grob interface is used in the following graphical object(s): SystemStartBar, SystemStartBrace, SystemStartBracket and SystemStartSquare.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.124 system-start-text-interface

Text in front of the system.

User settable properties:

long-text (markup)

Text markup. See (notation)Formatting text section ‘Formatting text’ in Notation Reference.

self-alignment-X (number)

Specify alignment of an object. The value -1 means left aligned, 0 centered, and 1 right-aligned in X direction. Other numerical values may also be specified - the unit is half the object width.

self-alignment-Y (number)

Like self-alignment-X but for the Y axis.

text (markup)

Text markup. See (notation)Formatting text section ‘Formatting text’ in Notation Reference.

This grob interface is used in the following graphical object(s): InstrumentName.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.125 tab-note-head-interface

A note head in tablature.

User settable properties:

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 having a details property.

Internal properties:

display-cautionary (boolean)

Should the grob be displayed as a cautionary grob?

span-start (boolean)

Is the note head at the start of a spanner?

This grob interface is used in the following graphical object(s): TabNoteHead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.126 text-interface

A Scheme markup text, see (notation)Formatting text section ‘Formatting text’ in Notation Reference and (extending)New markup command definition section ‘New markup command definition’ in Extending.

There are two important commands: ly:text-interface::print, which is a grob callback, and ly:text-interface::interpret-markup.

User settable properties:

baseline-skip (dimension, in staff space)

Distance between base lines of multiple lines of text.

flag-style (symbol)

The style of the flag to be used with MetronomeMark. Available are 'modern-straight-flag, 'old-straight-flag, flat-flag, mensural and 'default

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.

text (markup)

Text markup. See (notation)Formatting text section ‘Formatting text’ in Notation Reference.

text-direction (direction)

This controls the ordering of the words. The default RIGHT is for roman text. Arabic or Hebrew should use LEFT.

word-space (dimension, in staff space)

Space to insert between words in texts.

This grob interface is used in the following graphical object(s): BalloonTextItem, BalloonTextSpanner, BarNumber, BassFigure, BreathingSign, ChordName, ClefModifier, CombineTextScript, DoublePercentRepeatCounter, DynamicText, DynamicTextSpanner, Fingering, FootnoteItem, FootnoteSpanner, HorizontalBracketText, InstrumentName, InstrumentSwitch, LyricText, MeasureCounter, MeasureSpanner, MetronomeMark, MultiMeasureRestNumber, MultiMeasureRestText, NoteName, OttavaBracket, PercentRepeatCounter, RehearsalMark, SostenutoPedal, StanzaNumber, StringNumber, StrokeFinger, SustainPedal, TabNoteHead, TextScript, TupletNumber, UnaCordaPedal and VoltaBracket.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.127 text-script-interface

An object that is put above or below a note.

User settable properties:

avoid-slur (symbol)

Method of handling slur collisions. Choices are inside, outside, around, and ignore. inside adjusts the slur if needed to keep the grob inside the slur. outside moves the grob vertically to the outside of the slur. around moves the grob vertically to the outside of the slur only if there is a collision. ignore does not move either. In grobs whose notational significance depends on vertical position (such as accidentals, clefs, etc.), outside and around behave like ignore.

script-priority (number)

A key for determining the order of 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.

Internal properties:

slur (graphical (layout) object)

A pointer to a Slur object.

This grob interface is used in the following graphical object(s): CombineTextScript, Fingering, StringNumber, StrokeFinger and TextScript.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.128 tie-column-interface

Object that sets directions of multiple ties in a tied chord.

User settable properties:

tie-configuration (list)

List of (position . dir) pairs, indicating the desired tie configuration, where position is the offset from the center of the staff in staff space and dir indicates the direction of the tie (1=>up, -1=>down, 0=>center). A non-pair entry in the list causes the corresponding tie to be formatted automatically.

Internal properties:

positioning-done (boolean)

Used to signal that a positioning element did its job. This ensures that a positioning is only done once.

ties (array of grobs)

A grob array of Tie objects.

This grob interface is used in the following graphical object(s): TieColumn.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.129 tie-interface

A tie - a horizontal curve connecting two noteheads.

The following properties may be set in the details list.

height-limit

The maximum height allowed for this tie.

ratio

Parameter for tie shape. The higher this number, the quicker the slur attains its height-limit.

between-length-limit

This detail is currently unused.

wrong-direction-offset-penalty

Demerit for ties that are offset in the wrong direction.

min-length

If the tie is shorter than this amount (in staff-spaces) an increasingly large length penalty is incurred.

min-length-penalty-factor

Demerit factor for tie lengths shorter than min-length.

center-staff-line-clearance

If the center of the tie is closer to a staff line than this amount, an increasingly large staff line collision penalty is incurred.

tip-staff-line-clearance

If the tips of the tie are closer to a staff line than this amount, an increasingly large staff line collision penalty is incurred.

staff-line-collision-penalty

Demerit factor for ties whose tips or center come close to staff lines.

dot-collision-clearance

If the tie comes closer to a dot than this amount, an increasingly large dot collision penalty is incurred.

dot-collision-penalty

Demerit factor for ties which come close to dots.

note-head-gap

The distance (in staff-spaces) by which the ends of the tie are offset horizontally from the center line through the note head.

stem-gap

The distance (in staff-spaces) by which the ends of the tie are offset horizontally from a stem which is on the same side of the note head as the tie.

tie-column-monotonicity-penalty

Demerit if the y-position of this tie in the set of ties being considered is less than the y-position of the previous tie.

tie-tie-collision-distance

If this tie is closer than this amount to the previous tie in the set being considered, an increasingly large tie-tie collision penalty is incurred.

tie-tie-collision-penalty

Demerit factor for a tie in the set being considered which is close to the previous one.

horizontal-distance-penalty-factor

Demerit factor for ties in the set being considered which are horizontally distant from the note heads.

vertical-distance-penalty-factor

Demerit factor for ties in the set being considered which are vertically distant from the note heads.

same-dir-as-stem-penalty

Demerit if tie is on the same side as a stem or on the opposite side to the one specified.

intra-space-threshold

If the tie’s height (in half staff-spaces) is less than this it is positioned between two adjacent staff lines; otherwise it is positioned to straddle a staff line further from the note heads.

outer-tie-length-symmetry-penalty-factor

Demerit factor for ties horizontally positioned unsymmetrically with respect to the two note heads.

outer-tie-vertical-distance-symmetry-penalty-factor

Demerit factor for ties vertically positioned unsymmetrically with respect to the two note heads.

outer-tie-vertical-gap

Amount (in half staff-spaces) by which a tie is moved away from the note heads if it is closer to either of them than 0.25 half staff-spaces.

skyline-padding

Padding of the skylines around note heads in chords.

single-tie-region-size

The number of candidate ties to generate when only a single tie is required. Successive candidates differ in their initial vertical position by half a staff-space.

multi-tie-region-size

The number of variations that are tried for the extremal ties in a chord. Variations differ in their initial vertical position by half a staff-space.

User settable properties:

annotation (string)

Annotate a grob for debug purposes.

avoid-slur (symbol)

Method of handling slur collisions. Choices are inside, outside, around, and ignore. inside adjusts the slur if needed to keep the grob inside the slur. outside moves the grob vertically to the outside of the slur. around moves the grob vertically to the outside of the slur only if there is a collision. ignore does not move either. In grobs whose notational significance depends on vertical position (such as accidentals, clefs, etc.), outside and around behave like ignore.

control-points (list of number pairs)

List of offsets (number pairs) that form control points for the tie, slur, or bracket shape. For Béziers, this should list the control points of a third-order Bézier curve.

dash-definition (pair)

List of dash-elements defining the dash structure. Each dash-element has a starting t value, an ending t-value, a dash-fraction, and a dash-period.

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 having a details property.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

head-direction (direction)

Are the note heads left or right in a semitie?

line-thickness (number)

For slurs and ties, this is the diameter of the virtual “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 Staff.StaffSymbol.thickness).

neutral-direction (direction)

Which direction to take in the center of the staff.

staff-position (number)

Vertical position, measured in half staff spaces, counted from the middle line.

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 “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 Staff.StaffSymbol.thickness).

This grob interface is used in the following graphical object(s): Tie.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.130 time-signature-interface

A time signature, in different styles. The following values for style are are recognized:

C

4/4 and 2/2 are typeset as C and struck C, respectively. All other time signatures are written with two digits. The value default is equivalent to C.

neomensural

2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8, and 9/8 are typeset with neo-mensural style mensuration marks. All other time signatures are written with two digits.

mensural

2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8, and 9/8 are typeset with mensural style mensuration marks. All other time signatures are written with two digits.

single-digit

All time signatures are typeset with a single digit, e.g., 3/2 is written as 3.

numbered

All time signatures are typeset with two digits.

User settable properties:

fraction (fraction, as pair)

Numerator and denominator of a time signature object.

style (symbol)

This setting determines in what style a grob is typeset. Valid choices depend on the stencil callback reading this property.

This grob interface is used in the following graphical object(s): TimeSignature.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.131 trill-pitch-accidental-interface

An accidental for trill pitch.

This grob interface is used in the following graphical object(s): TrillPitchAccidental.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.132 trill-spanner-interface

A trill spanner.

This grob interface is used in the following graphical object(s): TrillSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.133 tuplet-bracket-interface

A bracket with a number in the middle, used for tuplets. When the bracket spans a line break, the value of break-overshoot determines how far it extends beyond the staff. At a line break, the markups in the edge-text are printed at the edges.

User settable properties:

avoid-scripts (boolean)

If set, a tuplet bracket avoids the scripts associated with the note heads it encompasses.

bracket-flare (pair of numbers)

A pair of numbers specifying how much edges of brackets should slant outward. Value 0.0 means straight edges.

bracket-visibility (boolean or symbol)

This controls the visibility of the tuplet bracket. Setting it to false prevents printing of the bracket. Setting the property to if-no-beam makes it print only if there is no beam associated with this tuplet bracket.

break-overshoot (pair of numbers)

How much does a broken spanner stick out of its bounds?

connect-to-neighbor (pair)

Pair of booleans, indicating whether this grob looks as a continued break.

dashed-edge (boolean)

If set, the bracket edges are dashed like the rest of the bracket.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

edge-height (pair)

A pair of numbers specifying the heights of the vertical edges: (left-height . right-height).

edge-text (pair)

A pair specifying the texts to be set at the edges: (left-text . right-text).

full-length-padding (number)

How much padding to use at the right side of a full-length tuplet bracket.

full-length-to-extent (boolean)

Run to the extent of the column for a full-length tuplet bracket.

gap (dimension, in staff space)

Size of a gap in a variable symbol.

padding (dimension, in staff space)

Add this much extra space between objects that are next to each other.

positions (pair of numbers)

Pair of staff coordinates (left . right), where both left and right are in staff-space units of the current staff. For slurs, this value selects which slur candidate to use; if extreme positions are requested, the closest one is taken.

shorten-pair (pair of numbers)

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.

staff-padding (dimension, in staff space)

Maintain this much space between reference points and the staff. Its effect is to align objects of differing sizes (like the dynamics p and f) on their baselines.

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 “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 Staff.StaffSymbol.thickness).

tuplet-slur (boolean)

Draw a slur instead of a bracket for tuplets.

X-positions (pair of numbers)

Pair of X staff coordinates of a spanner in the form (left . right), where both left and right are in staff-space units of the current staff.

Internal properties:

note-columns (array of grobs)

An array of NoteColumn grobs.

scripts (array of grobs)

An array of Script objects.

tuplet-number (graphical (layout) object)

The number for a bracket.

tuplets (array of grobs)

An array of smaller tuplet brackets.

This grob interface is used in the following graphical object(s): LigatureBracket and TupletBracket.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.134 tuplet-number-interface

The number for a bracket.

User settable properties:

avoid-slur (symbol)

Method of handling slur collisions. Choices are inside, outside, around, and ignore. inside adjusts the slur if needed to keep the grob inside the slur. outside moves the grob vertically to the outside of the slur. around moves the grob vertically to the outside of the slur only if there is a collision. ignore does not move either. In grobs whose notational significance depends on vertical position (such as accidentals, clefs, etc.), outside and around behave like ignore.

direction (direction)

If side-axis is 0 (or X), then this property determines whether the object is placed LEFT, CENTER or RIGHT with respect to the other object. Otherwise, it determines whether the object is placed UP, CENTER or DOWN. Numerical values may also be used: UP=1, DOWN=-1, LEFT=-1, RIGHT=1, CENTER=0.

knee-to-beam (boolean)

Determines whether a tuplet number will be positioned next to a kneed beam.

Internal properties:

bracket (graphical (layout) object)

The bracket for a number.

This grob interface is used in the following graphical object(s): TupletNumber.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.135 unbreakable-spanner-interface

A spanner that should not be broken across line breaks. Override with breakable=##t.

User settable properties:

breakable (boolean)

Allow breaks here.

This grob interface is used in the following graphical object(s): Beam and Glissando.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.136 vaticana-ligature-interface

A vaticana style Gregorian ligature.

User settable properties:

glyph-name (string)

The glyph name within the font.

In the context of (span) bar lines, glyph-name represents a processed form of glyph, where decisions about line breaking etc. are already taken.

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

add-cauda (boolean)

Does this flexa require an additional cauda on the left side?

add-join (boolean)

Is this ligature head-joined with the next one by a vertical line?

add-stem (boolean)

Is this ligature head a virga and therefore needs an additional stem on the right side?

delta-position (number)

The vertical position difference.

flexa-height (dimension, in staff space)

The height of a flexa shape in a ligature grob (in staff-space units).

flexa-width (dimension, in staff space)

The width of a flexa shape in a ligature grob (in staff-space units).

x-offset (dimension, in staff space)

Extra horizontal offset for ligature heads.

This grob interface is used in the following graphical object(s): NoteHead and VaticanaLigature.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.137 volta-bracket-interface

Volta bracket with number.

User settable properties:

dashed-edge (boolean)

If set, the bracket edges are dashed like the rest of the bracket.

height (dimension, in staff space)

Height of an object in staff-space units.

shorten-pair (pair of numbers)

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.

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 “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 Staff.StaffSymbol.thickness).

Internal properties:

bars (array of grobs)

An array of bar line pointers.

This grob interface is used in the following graphical object(s): VoltaBracket.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.138 volta-interface

A volta repeat.

This grob interface is used in the following graphical object(s): VoltaBracket and VoltaBracketSpanner.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated by gub on July 13, 2020 using texi2html 1.82.