LilyPond program-reference: 3.2.37 grob-interface

### 3.2.37 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 `set-grob-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 `around`, `inside`, `outside`. If unset, scripts and slurs ignore each other. `around` only moves the script if there is a collision; `outside` always moves the script.

> `before-line-breaking` (boolean)

>   Dummy property, used to trigger a callback function.

> `color` (list)

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

>   The output layer (a value between 0 and 2): Layers define the order of printing objects. Objects in lower layers are overprinted by objects in higher layers.

> `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` (unknown)

>   The symbol to print.

> `transparent` (boolean)

>   This makes the grob invisible.

#### Internal properties:

> `axis-group-parent-X` (layout object)

>   Containing X axis group.

> `axis-group-parent-Y` (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` (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, Custos, DotColumn, Dots, DoublePercentRepeat, DoublePercentRepeatCounter, DynamicLineSpanner, DynamicText, DynamicTextSpanner, Fingering, FretBoard, Glissando, GraceSpacing, GridLine, GridPoint, Hairpin, HarmonicParenthesesItem, 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, SeparationItem, Slur, SostenutoPedal, SostenutoPedalLineSpanner, SpacingSpanner, SpanBar, 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