[icon]

GNU LilyPond

-- --

What is LilyPond
Home
Examples
Templates
Download
GNU/Linux binaries
Windows binaries
Source code
Documentation
Tutorial
Manual
Glossary
Index

Support
Mailing lists
Search
WikiWiki

External sites
lilypond.org/stable
lilypond.org/development
savannah.gnu.org
ftp.lilypond.org
Mutopia
Other music online

Stem

Stem grobs are created by: Stem_engraver


item-interface

Grobs can be distinguished in their role in the horizontal spacing. Many grobs define constraints on the spacing by their sizes. For example, note heads, clefs, stems, and all other symbols with a fixed shape. These grobs form a subtype called Item.


break-visibility (procedure)
a function that takes the break direction and returns a cons of booleans containing (TRANSPARENT . EMPTY).

Some items need special treatment for line breaking. For example, a clef is normally only printed at the start of a line (i.e. after a line break). To model this, `breakable' items (clef, key signature, bar lines, etc.) are copied twice. Then we have three versions of each breakable item: one version if there is no line break, one version that is printed before the line break (at the end of a system), one version that is printed after the line break.

Whether these versions are visible and take up space, is determined by the outcome of the break-visibility. This grob property is a function taking a direction (-1, 0 or 1) as argument. It returns a cons of booleans, signifying whether this grob should be transparent and have no extent. Default value: (unset)

breakable (boolean)
boolean indicating if this is a breakable item (clef, barline, key sig, etc.). Default value: (unset)
no-spacing-rods (boolean)
read from grobs: boolean that makes Separation_item ignore this item (MOVE ME TO ITEM). Default value: (unset)

font-interface

Any symbol that is typeset through fixed sets of glyphs (ie. fonts)


font (unknown)
Cached font metric object Default value: (unset)
font-design-size (number)
partial font definition: exact font size in points FIXME: should override font-relative-size. Default value: (unset)
font-family (symbol)
partial font definition: music roman braces dynamic math ... Default value: 'music
font-magnification (number)
Magnification of the font. If undefined, the default is 1.0. Default value: (unset)
font-name (string)
file name for the font to load. Overrides all other font-X qualifiers. Default value: (unset)
font-relative-size (number)
partial font definition: the relative size compared the `normal' size. 0 is style-sheet's normal size, -1 is smaller, +1 is bigger. Default value: (unset)
font-series (symbol)
partial font definition: medium, bold. Default value: (unset)
font-shape (symbol)
partial font definition: upright or italic. Default value: (unset)
font-style (symbol)
a precooked set of font definitions, eg. finger volta timesig mark script large Large dynamic. Default value: (unset)

stem-interface

A stem


adjust-if-on-staffline (boolean)
If this grob is on a staff line, adjust its appearance, so that it better fits into the staff. E.g., if set true on stem grobs, flares of mensural flags will always be aligned with the staff lines, regardless if the associated note head is printed on a staff line or inbetween. Default value: #t
avoid-note-head (boolean)
if set, the stem of a chord does not pass through all note head, but start at the last note head. Used by tablature. Default value: #f
beam (grob (GRaphical OBject))
pointer to the beam, if applicable. Default value: (unset)
beamed-extreme-minimum-free-lengths (list)
list of extreme minimum free stem lengths (chord to beams) given beam multiplicity. Default value: '(1.83 1.5)
beamed-lengths (list)
list of stem lengths given beam multiplicity . Default value: '(3.26)
beamed-minimum-free-lengths (list)
list of normal minimum free stem lengths (chord to beams) given beam multiplicity. Default value: '(2.5 2.0 1.5)
beaming (pair)
Pair of number lists. Each number list specifies which beams to make. 0 is the central beam, 1 is the next beam toward the note etc. This information is used to determine how to connect the beaming patterns from stem to stem inside a beam. Default value: (unset)
direction (direction)
up or down, left or right?. Default value: (unset)
duration-log (integer)
2-log of the notehead duration, i.e. 0=whole note, 1 = half note, etc. Default value: (unset)
flag-style (symbol)
a string determining what style of glyph is typeset on a Stem. Valid options include undefined and mensural. Additionally, no-flag switches off the flag. Default value: (unset)
french-beaming (boolean)
Use French beaming style: stems stop at innermost beams. Default value: (unset)
length (dimension, in staff space)
Stem length for unbeamed stems, only for user override. Default value: (unset)
lengths (list)
Stem length given multiplicity of flag. The Nth element of the list gives the stem length of a note with N flags.

Default value: '(3.5 3.5 3.5 4.5 5.0)

neutral-direction (direction)
Where to go if we're on the neutral position of the staff (by default, the middle of the staff; see also grob-property neutral-position). [Ross] has the following to say about this: Some engravers consider the middle line neutral, and take the option of using either up- or down-stems for notes that fall on it. However, more up-to-date engraving no longer permits an option; now a down-stem is always appropriate. Default value: -1
no-stem-extend (boolean)
should stem not be extended to middle staff line?. Default value: (unset)
note-heads (list of grobs)
List of note head grobs Default value: (unset)
stem-end-position (number)
Where does the stem end (the end is opposite to the support-head. Default value: (unset)
stem-info (pair)
caching of stem parameters Default value: (unset)
stem-shorten (list)
shorten stems in forced directions given flag multiplicity: the Nth element of the list gives the amount stem shortening of a note with N flags.

Default value: '(1.0 0.5)

stroke-style (string)
set to "grace" to turn stroke through flag on. Default value: (unset)
support-head (grob (GRaphical OBject))
the note head at one end of the stem. Default value: (unset)
thickness (number)
thickness, measured in stafflinethickness. Default value: 1.3
up-to-staff (boolean)
if set, stems' lengths are set so as stems end out of the staff. Used by tablature. Default value: #f

grob-interface

In music notation, lots of symbols are related in some way. You can think of music notation as a graph where nodes are formed by the symbols, and the arcs by their relations. A grob is a node in that graph. The directed edges in the graph are formed by references to other grobs (i.e. pointers). This big graph of grobs specifies the notation problem. The solution of this problem is a description of the printout in closed form, i.e. a list of values. These values are Molecules.

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

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.


X-extent (pair of numbers)
Store extent. internal use only. Default value: (unset)
X-extent-callback (procedure)
procedure taking an grob and axis argument, returning a number-pair. The return value is the extent of the grob.

The size of a grob are determined through callbacks, settable with grob properties X-extent-callback and Y-extent-callback. There can be only one extent-callback for each axis. No callback (Scheme value #f) means: `empty in this direction'. If you fill in a pair of numbers, that pair hard-codes the extent in that coordinate.

Default value: Stem::dim_callback

X-offset-callbacks (list)
list of functions, each taking an grob and axis argument. The function determine the position relative to this grob's parent. The last one in the list is called first.

Offsets of grobs are relative to a parent reference point. Most positions are not known when an object is created, so these are calculated as needed. This is done by adding a callback for a specific direction.

Offset callbacks can be stacked, i.e.

                  property .... override #'Y-offset-callbacks = #(list
                          callback1 callback2 callback3)
          
          

The callbacks will be executed in the order callback3 callback2 callback1. This is used for quantized positioning: the staccato dot is above or below a note head, and it must not be on a staff-line. To achieve this, the staccato dot has two callbacks: one that positions the grob above or below the note head, and one that rounds the Y-position of the grob to the nearest open space.

Default value: '(#<primitive-procedure Stem::off_callback>)

Y-extent (pair of numbers)
Store extent. internal use only. Default value: (unset)
Y-extent-callback (procedure)
see X-extent-callback. Default value: Stem::height
Y-offset-callbacks (list)
see X-offset-callbacks. Default value: '(#<primitive-procedure Staff_symbol_referencer::callback>)
after-line-breaking-callback (procedure)
Procedure taking a grob as argument. This procedure is called (using dependency resolution) after line breaking. Return value is ignored. Default value: (unset)
before-line-breaking-callback (procedure)
Procedure taking grob as argument. This procedure is called (using dependency resolution) before line breaking, but after generating discretionary items. Return value is ignored. Default value: Stem::before_line_breaking
cause (any type)
Any kind of causation objects (i.e. music, or perhaps translator) that was the cause for this grob. Default value: (unset)
causes (list)
list of cause objects; these can be music objects or grobs. Default value: (unset)
dependencies (list of grobs)
list of score-grob pointers that indicate who to compute first for certain global passes. Default value: (unset)
extra-X-extent (pair of numbers)
enlarge in X dimension by this much, measured in staff space. Default value: (unset)
extra-Y-extent (pair of numbers)
see extra-Y-extent. Default value: (unset)
extra-offset (pair of numbers)
pair of reals (a cons) forcing an extra offset before outputting. extra-offset is added just before `printing' the grob, so the typesetting engine is completely oblivious to it.

Default value: (unset)

interfaces (list)
list of symbols indicating the interfaces supported by this object. Is initialized from the meta field. Default value: (unset)
layer (number)
The output layer [0..2]. The default is 1. Default value: (unset)
meta (list)
Alist of meta information of this grob.

The alist contains the following entries: name, interfaces.

Default value: '((name . Stem) (interfaces grob-interface stem-interface font-interface item-interface))

minimum-X-extent (pair of numbers)
minimum size in X dimension, measured in staff space. Default value: (unset)
minimum-Y-extent (pair of numbers)
see minimum-Y-extent. Default value: (unset)
molecule (unknown)
Cached output of the molecule-callback. Default value: (unset)
molecule-callback (procedure)
Function taking grob as argument, returning a smobbed Molecule.

All visible, i.e. non-transparent, grobs have a callback to create a Molecule. The callback should be a Scheme function taking one argument (the grob) and returning a Molecule. Most molecule callbacks are written in C++, but you can also write them in Scheme. An example is provided in input/regression/molecule-hacking.ly.

Default value: Stem::brew_molecule

spacing-procedure (procedure)
procedure taking grob as argument. This is called after before-line-breaking-callback, but before the actual line breaking itself. Return value is ignored. Default value: (unset)
staff-symbol (grob (GRaphical OBject))
the staff symbol grob that we're in. Default value: (unset)
transparent (boolean)
This is almost the same as setting molecule-callback to #f, but this retains the dimensions of this grob, which means that you can erase grobs individually. . Default value: (unset)

Go back to index of LilyPond.

Please send GNU LilyPond questions and comments to lilypond-user@gnu.org.

Please send comments on these web pages to (address unknown)

Copyright (c) 1997--2002 Han-Wen Nienhuys and Jan Nieuwenhuizen.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.


This page was built from LilyPond-1.7.14 (development-branch) by

Buchan Milne <(address unknown)>, Thu Mar 6 21:11:35 2003 CET.