LilyPond Internals Reference: 3.2.42 grob-interface

### 3.2.42 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:

> `X-extent` (pair of numbers)

>   Hard coded extent in X direction.

> `X-offset` (number)

>   The horizontal amount that this object is moved relative to its X-parent.

> `Y-extent` (pair of numbers)

>   Hard coded extent in Y direction.

> `Y-offset` (number)

>   The vertical amount that this object is moved relative to its Y-parent.

> `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-X-extent` (pair of numbers)

>   A grob is enlarged in X dimension by this much.

> `extra-Y-extent` (pair of numbers)

>   A grob is enlarged in Y dimension by this much.

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

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

> `outside-staff-horizontal-padding` (number)

>   By default, an outside-staff-object can be placed so that is it very close to another grob horizontally. If this property is set, the outside-staff-object is raised so that it is not so close to its neighbor.

> `outside-staff-padding` (number)

>   The padding to place between this grob and the staff when spacing according to `outside-staff-priority`.

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

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

> `springs-and-rods` (boolean)

>   Dummy variable for triggering spacing routines.

> `stencil` (stencil)

>   The symbol to print.

> `transparent` (boolean)

>   This makes the grob invisible.

> `whiteout` (boolean)

>   If true, the grob is printed over a white background to white-out underlying material, if the grob is visible. Usually #f by default.

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

>   For a beam or a stem, this is true if we depend on inter-staff spacing.

> `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, BarLine, BarNumber, BassFigure, BassFigureAlignment, BassFigureAlignmentPositioning, BassFigureBracket, BassFigureContinuation, BassFigureLine, Beam, BendAfter, BreakAlignGroup, BreakAlignment, BreathingSign, ChordName, Clef, ClusterSpanner, ClusterSpannerBeacon, CombineTextScript, CueClef, CueEndClef, Custos, DotColumn, Dots, DoublePercentRepeat, DoublePercentRepeatCounter, DoubleRepeatSlash, DynamicLineSpanner, DynamicText, DynamicTextSpanner, Episema, Fingering, FootnoteItem, FootnoteSpanner, FretBoard, Glissando, GraceSpacing, GridLine, GridPoint, Hairpin, HorizontalBracket, InstrumentName, InstrumentSwitch, KeyCancellation, KeySignature, LaissezVibrerTie, LaissezVibrerTieColumn, LedgerLineSpanner, LeftEdge, LigatureBracket, LyricExtender, LyricHyphen, LyricSpace, LyricText, MeasureGrouping, MelodyItem, MensuralLigature, MetronomeMark, MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestText, NonMusicalPaperColumn, NoteCollision, NoteColumn, NoteHead, NoteName, NoteSpacing, OctavateEight, OttavaBracket, PaperColumn, ParenthesesItem, PercentRepeat, PercentRepeatCounter, PhrasingSlur, PianoPedalBracket, RehearsalMark, RepeatSlash, RepeatTie, RepeatTieColumn, Rest, RestCollision, Script, ScriptColumn, ScriptRow, Slur, SostenutoPedal, SostenutoPedalLineSpanner, SpacingSpanner, SpanBar, StaffGrouper, StaffSpacing, StaffSymbol, StanzaNumber, Stem, 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 and VoltaBracketSpanner.

#### Internals Reference