[ << Backend ]	[Top][Contents][Index]	[ Scheme functions >> ]
[ < grid-point-interface ]	[ Up: Graphical Object Interfaces ]	[ hairpin-interface > ]

---

3.2.60 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 (association list (list of pairs))

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"))

produces

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

parenthesis-id (symbol)

When parenthesized grobs created in the same time step have this property, there is one set of parentheses for each group of grobs having the same value.

parenthesized (boolean)

Parenthesize this grob.

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.

show-horizontal-skylines (boolean)

If true, print this grob’s horizontal skylines. This is meant for debugging purposes.

show-vertical-skylines (boolean)

If true, print this grob’s vertical skylines. This is meant for debugging purposes.

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. If whiteout-color is set, use this color instead of white for the background.

whiteout-color (color)

The background color used if property whiteout is set.

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.

Note that many objects have special positioning considerations, which cause any setting of X-offset to be ignored or modified, even though the object supports the self-alignment-interface.

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.

Note that many objects have special positioning considerations, which cause any setting of Y-offset to be ignored or modified, even though the object supports the self-alignment-interface.

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

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, BalloonText, BarLine, BarNumber, BassFigure, BassFigureAlignment, BassFigureAlignmentPositioning, BassFigureBracket, BassFigureContinuation, BassFigureLine, Beam, BendAfter, BendSpanner, BreakAlignGroup, BreakAlignment, BreathingSign, CaesuraScript, CenteredBarNumber, CenteredBarNumberLineSpanner, ChordName, ChordSquare, Clef, ClefModifier, ClusterSpanner, ClusterSpannerBeacon, CodaMark, CombineTextScript, ControlPoint, ControlPolygon, CueClef, CueEndClef, Custos, Divisio, DotColumn, Dots, DoublePercentRepeat, DoublePercentRepeatCounter, DoubleRepeatSlash, DurationLine, DynamicLineSpanner, DynamicText, DynamicTextSpanner, Episema, FingerGlideSpanner, Fingering, FingeringColumn, Flag, Footnote, FretBoard, Glissando, GraceSpacing, GridChordName, GridLine, GridPoint, Hairpin, HorizontalBracket, HorizontalBracketText, InstrumentName, InstrumentSwitch, JumpScript, KeyCancellation, KeySignature, KievanLigature, LaissezVibrerTie, LaissezVibrerTieColumn, LedgerLineSpanner, LeftEdge, LigatureBracket, LyricExtender, LyricHyphen, LyricRepeatCount, LyricSpace, LyricText, MeasureCounter, MeasureGrouping, MeasureSpanner, MelodyItem, MensuralLigature, MetronomeMark, MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestScript, MultiMeasureRestText, NonMusicalPaperColumn, NoteCollision, NoteColumn, NoteHead, NoteName, NoteSpacing, OptionalMaterialBracket, OttavaBracket, PaperColumn, Parentheses, PercentRepeat, PercentRepeatCounter, PhrasingSlur, PianoPedalBracket, RehearsalMark, RepeatSlash, RepeatTie, RepeatTieColumn, Rest, RestCollision, Script, ScriptColumn, ScriptRow, SectionLabel, SegnoMark, SignumRepetitionis, Slur, SostenutoPedal, SostenutoPedalLineSpanner, SpacingSpanner, SpanBar, SpanBarStub, StaffEllipsis, StaffGrouper, StaffHighlight, StaffSpacing, StaffSymbol, StanzaNumber, Stem, StemStub, StemTremolo, StringNumber, StrokeFinger, SustainPedal, SustainPedalLineSpanner, System, SystemStartBar, SystemStartBrace, SystemStartBracket, SystemStartSquare, TabNoteHead, TextMark, TextScript, TextSpanner, Tie, TieColumn, TimeSignature, TrillPitchAccidental, TrillPitchGroup, TrillPitchHead, TrillPitchParentheses, TrillSpanner, TupletBracket, TupletNumber, UnaCordaPedal, UnaCordaPedalLineSpanner, VaticanaLigature, VerticalAlignment, VerticalAxisGroup, VoiceFollower, VoltaBracket, VoltaBracketSpanner and VowelTransition.