5.1.1 Objects and interfaces

Tweaking involves modifying the internal operation and structures of the LilyPond program, so we must first introduce some terms which are used to describe those internal operations and structures.

The term Object is a generic term used to refer to the multitude of internal structures built by LilyPond during the processing of an input file. So when a command like \new Staff is encountered a new object of type Staff is constructed. That Staff object then holds all the properties associated with that particular staff, for example, its name and its key signature, together with details of the engravers which have been assigned to operate within that staff’s context. Similarly, there are objects to hold the properties of all other contexts, such as Voice objects, Score objects, Lyrics objects, as well as objects to represent all notational elements such as bar lines, note heads, ties, dynamics, etc. Every object has its own set of property values.

Some types of object are given special names. Objects that represent items of notation on the printed output such as note heads, stems, slurs, ties, fingering, clefs, etc are called ‘Layout objects’, often known as ‘Graphical Objects’, or grobs for short. These are still objects in the generic sense above, and so they too all have properties associated with them, such as their position, size, color, etc.

Some layout objects are still more specialized. Phrasing slurs, crescendo hairpins, ottava marks, and many other grobs are not localized in a single place – they have a starting point, an ending point, and maybe other properties concerned with their shape. Objects with an extended shape like these are called spanners.

Spanners cannot be tweaked after their creation. This includes both StaffSymbol and LedgerLineSpanner, which continue throughout the score, except if they are terminated by the \stopStaff command and then recreated using \startStaff command.

What is more, there are ‘abstract’ grobs which do not print anything of their own, but rather collect, position and manage other grobs. Common examples for this are DynamicLineSpanner, BreakAlignment, NoteColumn, VerticalAxisGroup, or NonMusicalPaperColumn. We will see how some of these are used later.

It remains to explain what interfaces are. Many objects, even though they are quite different, share common features which need to be processed in the same way. For example, all grobs have a color, a size, a position, etc, and all these properties are processed in the same way during LilyPond’s interpretation of the input file. To simplify these internal operations these common actions and properties are grouped together in an object called a grob-interface. There are many other groupings of common properties like this, each one given a name ending in interface. In total there are over 100 such interfaces. We shall see later why this is of interest and use to the user.

These, then, are the main terms relating to objects which we shall use in this chapter.

LilyPond Learning Manual v2.25.18 (development-branch).