3.2.130 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.

absolute-closeness-measure

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

accidental-collision

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

close-to-edge-length

Threshold to decide whether an object to avoid is horizontally close to the slur’s edge. If it is, it doesn’t influence the slur’s height.

edge-attraction-factor

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

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.

encompass-object-range-overshoot

Widen the range of encompass-object positions by this amount for computing the slur.

extra-encompass-collision-distance

This detail is currently unused.

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-object-collision-penalty

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

free-head-distance

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

free-slur-distance

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

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.

head-encompass-penalty

Demerit to apply when note heads collide with a slur.

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.

max-slope

The maximum slope allowed for this slur.

max-slope-factor

Factor that calculates demerit based on the max slope. Notice that there exists a homonymous property for tuplet brackets.

non-horizontal-penalty

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

region-size

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

same-slope-penalty

Demerit for slurs with attachment points that are horizontally aligned.

slur-tie-extrema-min-distance

If a slur starts or ends very near to or at the same position as a tie, check this threshold whether slur and tie are too close.

slur-tie-extrema-min-distance-penalty

Demerit to apply if slur-tie-extrema-min-distance gets triggered.

steeper-slope-factor

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

stem-encompass-penalty

Demerit to apply when stems collide with a slur.

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.

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 (alist, with symbols as keys)

An alist of parameters for detailed grob behavior. See section All layout objects for more information on the available parameters and their default values of a particular grob’s details property. See section Graphical Object Interfaces for documentation of the available parameters. Supporting interfaces can be found at the bottom of a grob’s description section.

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 (start . end), where start and end are vertical positions 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:

annotation (string)

Annotate a grob for debug purposes.

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.


LilyPond Internals Reference v2.25.14 (development-branch).