Next: , Previous: gregorian-ligature-interface, Up: Graphical Object Interfaces



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, so they can easily be combined by stacking them, hanging one grob to the side of another, and coupling them into a 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 is also an abstract grob: it only moves around chords, but doesn't print anything.

Grobs have a properties: Scheme variables, that can be read and set. They have two types. 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 inmutable properties: every call to set-grob-property (or its C++ equivalent) sets a mutable property.

User settable properties:
X-extent (pair of numbers)
Hard coded extent in X direction.
X-extent-callback (procedure)
Procedure that calculates the extent of this object. If this value is set to #f, the object is empty in the X direction. The procedure takes a grob and axis argument, and returns a number-pair.
X-offset-callbacks (list)
A list of functions determining this objects' position relative to its parent. The last one in the list is called first. The functions take a grob and axis argument.
Y-extent (pair of numbers)
See X-extent.
Y-extent-callback (procedure)
see X-extent-callback.
Y-offset-callbacks (list)
see X-offset-callbacks.
before-line-breaking-callback (procedure)
This procedure is called before line breaking, but after splitting breakable items at potential line breaks.
extra-X-extent (pair of numbers)
A grob is enlarged in X dimension by this much.
extra-Y-extent (pair of numbers)
See extra-Y-extent.
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.
layer (number)
The output layer [0..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.
minimum-Y-extent (pair of numbers)
See minimum-Y-extent.
print-function (procedure)
Function taking grob as argument, returning a Stencil object.
spacing-procedure (procedure)
Procedure for calculating spacing parameters. The routine is called after before-line-breaking-callback.
transparent (boolean)
This is almost the same as setting print-function to #f, but this retains the dimensions of this grob, which means that grobs can be erased individually.
Internal properties:
after-line-breaking-callback (procedure)
This procedure is called after line breaking. Its return value is ignored.
cause (any type)
Any kind of causation objects (i.e. music, or perhaps translator) that was the cause for this grob.
dependencies (list of grobs)
list of score-grob pointers that indicate who to compute first for certain global passes.
interfaces (list)
list of symbols indicating the interfaces supported by this object. Is initialized from the meta field.
meta (list)
Contains meta information. It is an alist with the entries name and interfaces.
staff-symbol (layout object)
the staff symbol grob that we're in.
stencil (unknown)
Cached output of the print-function.

This grob interface is used in the following graphical objects: Accidental, AccidentalPlacement, Ambitus, Arpeggio, BarLine, BarNumber, BassFigure, Beam, BreakAlignGroup, BreakAlignment, BreathingSign, ChordName, Clef, ClusterSpanner, ClusterSpannerBeacon, CombineTextScript, Custos, DotColumn, Dots, DoublePercentRepeat, DynamicLineSpanner, DynamicText, Fingering, Glissando, Hairpin, HorizontalBracket, InstrumentName, KeySignature, LeftEdge, LigatureBracket, LyricExtender, LyricHyphen, LyricText, MeasureGrouping, MensuralLigature, MetronomeMark, MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestText, NonMusicalPaperColumn, NoteCollision, NoteColumn, NoteHead, NoteName, NoteSpacing, OctavateEight, OttavaBracket, PaperColumn, PercentRepeat, PhrasingSlur, PianoPedalBracket, RehearsalMark, RemoveEmptyVerticalGroup, RepeatSlash, Rest, RestCollision, Script, ScriptColumn, SeparatingGroupSpanner, SeparationItem, Slur, SostenutoPedal, SostenutoPedalLineSpanner, SpacingSpanner, SpanBar, StaffSpacing, StaffSymbol, StanzaNumber, Stem, StemTremolo, SustainPedal, SustainPedalLineSpanner, System, SystemStartBar, SystemStartBrace, SystemStartBracket, TabNoteHead, TextScript, TextSpanner, Tie, TieColumn, TimeSignature, TupletBracket, UnaCordaPedal, UnaCordaPedalLineSpanner, VaticanaLigature, VerticalAlignment, VerticalAxisGroup, VocalName, VoiceFollower and VoltaBracket

Read comments on this page, or add one.

This page is for LilyPond-2.2.6 (stable-branch).

Report errors to <bug-lilypond@gnu.org>.