GNU LilyPond

-- --

Staff

Handles clefs, bar lines, keys, accidentals. It can contain Voice contexts.

This context creates the following grobs: Accidental, BarLine, Clef, DotColumn, InstrumentName, KeySignature, NoteCollision, OctavateEight, RestCollision, SeparatingGroupSpanner, SeparationItem, SostenutoPedalLineSpanner, SostenutoPedal, StaffSymbol, SustainPedalLineSpanner, SustainPedal, TimeSignature, UnaCordaPedalLineSpanner, UnaCordaPedal, VerticalAxisGroup and VoltaBracket.

This context sets the following properties:

• Set translator property instr to #f
• Set translator property instrument to #f
• Set translator property localKeySignature to '()
• Set translator property verticalExtent to #f
• Set translator property extraVerticalExtent to #f
• Set translator property minimumVerticalExtent to '(-6 . 6)
• Set grob-property spacing-procedure in SeparatingGroupSpanner to Separating_group_spanner::set_spacing_rods_and_seqs

Context Staff can contain Voice

This context is built from the following engravers:

Engraver_group_engraver

A group of engravers taken together

Engraver_group_engraver is part of contexts: Voice, StaffGroup, PianoStaff, InnerStaffGroup, LyricsVoice, RhythmicStaff, NoteNames, TabVoice, FiguredBass, Thread, Staff, StaffContainer, ChordNames, GrandStaff, InnerChoirStaff, Lyrics, ChoirStaff and TabStaff

Forbid_line_break_engraver

Forbid line breaks when note heads are still playing at some point.

Properties (read)

busyGrobs (list):

a queue of (END-MOMENT . GROB) conses. This is for internal (C++) use only. Use at your own risk. This property contains the grobs for which END-MOMENT >= NOW.

Forbid_line_break_engraver is part of contexts: Staff and TabStaff

Grob_pq_engraver

Administrate when certain grobs (eg. note heads) stop playing; this engraver is a sort-of a failure, since it doesn't handle all sorts of borderline cases very well.

Properties (read)

busyGrobs (list):

a queue of (END-MOMENT . GROB) conses. This is for internal (C++) use only. Use at your own risk. This property contains the grobs for which END-MOMENT >= NOW.

Properties (write)

busyGrobs (list):

a queue of (END-MOMENT . GROB) conses. This is for internal (C++) use only. Use at your own risk. This property contains the grobs for which END-MOMENT >= NOW.

Grob_pq_engraver is part of contexts: Voice, TabVoice, Staff and TabStaff

Instrument_name_engraver

Prints the name of the instrument (specified by Staff.instrument and Staff.instr) at the left of the staff.

Properties (read)

instr (markup (list or string)):

see instrument

instrument (markup (list or string)):

If Instrument_name_engraver is added to the Staff translator, then the instrument property is used to label the first line of the staff and the instr property is used to label subsequent lines. If the midiInstrument property is not set, then instrument is used to determine the instrument for MIDI output.

Instrument_name_engraver is part of contexts: PianoStaff, RhythmicStaff, Staff and TabStaff

Piano_pedal_engraver

Engrave piano pedal symbols and brackets.

Properties (read)

pedalUnaCordaStrings (list):

see pedalSustainStrings.

pedalSustainStrings (list):

List of string to print for sustain-pedal. Format is (UP UPDOWN DOWN), where each of the three is the string to print when this is done with the pedal.

pedalSostenutoStrings (list):

see pedalSustainStrings.

Piano_pedal_engraver is part of contexts: Staff and TabStaff

Accidental_engraver

Make accidentals. Catches note heads, ties and notices key-change events. Due to interaction with ties (which don't come together with note heads), this needs to be in a context higher than Tie_engraver.

Properties (read)

autoCautionaries (list):

List similar to autoAccidentals, but it controls cautionary accidentals rather than normal ones. Both lists are tried, and the one giving the most accidentals wins. In case of draw, a normal accidental is typeset.

autoAccidentals (list):

List of different ways to typeset an accidental. All algorithms in the list are tried, and the one returning the most accidentals is used. Each entry is either a symbol containg a context name or a name-value pair containing an algorithm-description. The list must begin with a symbol (context name). The symbols denote in which context THE FOLLOWING algorithms (until next symbol) will be interpreted. All notes in the interpretation context will share accidentals. The contexts must be stated in order, innermost first. The algorithms are:

same-octave:

This is the default algorithm. Accidentals are typeset if the note changes the accidental of that note in that octave. Accidentals lasts to the end of the measure and then as many measures as specified in the value. I.e. 1 means to the end of next measure, -1 means to the end of previous measure (that is: no duration at all), etc. #t means forever.

any-octave:

Accidentals are typeset if the note is different from the previous note on the same pitch in any octave. The value has same meaning as in same-octave.

extraNatural (boolean):

Whether to typeset an extra natural sign before accidentals changing from a non-natural to another non-natural.

localKeySignature (list):

the key signature at this point in the measure. The format is the same as for keySignature. Is reset at every bar line.

Properties (write)

localKeySignature (list):

the key signature at this point in the measure. The format is the same as for keySignature. Is reset at every bar line.

Accidental_engraver is part of contexts: Staff

Rest_collision_engraver

Handles collisions of rests.

This engraver creates the following grobs: RestCollision.

Rest_collision_engraver is part of contexts: Staff and TabStaff

Collision_engraver

This engraver creates the following grobs: NoteCollision.

Collision_engraver is part of contexts: Staff and TabStaff

Staff_symbol_engraver

create the constellation of five (default) staff lines.

This engraver creates the following grobs: StaffSymbol.

Staff_symbol_engraver is part of contexts: RhythmicStaff, Staff and TabStaff

Time_signature_engraver

Create a TimeSignature whenever timeSignatureFraction changes

This engraver creates the following grobs: TimeSignature.

Time_signature_engraver is part of contexts: RhythmicStaff, Staff and TabStaff

Key_engraver

Properties (read)

keySignature (list):

The current key signature. This is an alist containing (NAME . ALTER) or ((OCTAVE . NAME) . ALTER) or ((OCTAVE . NAME) . (ALTER . BARNUMBER)) pairs, where NAME is from 0.. 6 and ALTER from -2,-1,0,1,2. The optional barnumber contains the number of the measure of the accidental. FIXME: describe broken tie entries.

keyAccidentalOrder (list):

Alist that defines in what order alterations should be printed. The format is (NAME . ALTER), where NAME is from 0 .. 6 and ALTER from -1, 1.

createKeyOnClefChange (boolean):

Print a key signature whenever the clef is changed.

explicitKeySignatureVisibility (procedure):

visibility-lambda function for explicit Key changes; override of #'break-visibility will set the visibility for normal (ie. at the start of the line) key signatures.

lastKeySignature (list):

Last key signature before a key signature change.

keySignature (list):

The current key signature. This is an alist containing (NAME . ALTER) or ((OCTAVE . NAME) . ALTER) or ((OCTAVE . NAME) . (ALTER . BARNUMBER)) pairs, where NAME is from 0.. 6 and ALTER from -2,-1,0,1,2. The optional barnumber contains the number of the measure of the accidental. FIXME: describe broken tie entries.

Properties (write)

lastKeySignature (list):

Last key signature before a key signature change.

Key_engraver is part of contexts: Staff

Clef_engraver

Determine and set reference point for pitches

Properties (read)

explicitClefVisibility (procedure):

visibility-lambda function for clef changes.

clefOctavation (integer):

Add this much extra octavation. Values of 7 and -7 are common.

centralCPosition (number):

Place of the central C. Usually determined by looking at clefPosition and clefGlyph.

clefGlyph (string):

Name of the symbol within the music font

clefPosition (number):

Where should the center of the symbol go?

Clef_engraver is part of contexts: Staff and TabStaff

Dot_column_engraver

Engraves dots on dotted notes shifted to the right of the note. If omitted, then dots appear on top of the notes.

This engraver creates the following grobs: DotColumn.

Dot_column_engraver is part of contexts: RhythmicStaff, Staff and TabStaff

Separating_line_group_engraver

Generates objects for computing spacing parameters.

This engraver creates the following grobs: SeparatingGroupSpanner and SeparationItem.

Separating_line_group_engraver is part of contexts: LyricsVoice, RhythmicStaff, NoteNames, Staff, ChordNames and TabStaff

Volta_engraver

Make volta brackets

Properties (read)

voltaOnThisStaff (boolean):

Normally, volta brackets are put only on the topmost staff. Setting this variable to true, will force a bracket to be on this staff as well.

stavesFound (list):

list of all staff-symbols found.

voltaSpannerDuration (moment):

maximum duration of the volta bracket.

Set to a duration to control the size of the brackets printed by \alternative. It specifies the number of whole notes duration to use for the brackets. This can be used to shrink the length of brackets in the situation where one alternative is very large. It may have odd effects if the specified duration is longer than the music given in an \alternative. .

repeatCommands (list):

This property is read to find any command of the form (volta . X), where X is a string or #f

Volta_engraver is part of contexts: RhythmicStaff, Staff and TabStaff

Font_size_engraver

Puts fontSize into font-relative-size grob property.

Properties (read)

fontSize (integer):

Used to set the relative size of all grobs in a context. This is done using the Font_size_engraver.

Font_size_engraver is part of contexts: Voice, TabVoice, Thread, Staff and TabStaff

Bar_engraver

Create barlines. This engraver is controlled through the whichBar property. If it has no bar line to create, it will forbid a linebreak at this point

Properties (read)

whichBar (string):

This property is read to determine what type of barline to create.

Example:

          \property Staff.whichBar = "|:"
          

This will create a start-repeat bar in this staff only.

If not set explicitly (by property or bar), this is set according to values of defaultBarType, barAlways, barNonAuto and measurePosition.

Valid values are described in (lilypond-internals)bar-line-interface.

.

Bar_engraver is part of contexts: RhythmicStaff, Staff and TabStaff

Output_property_engraver

Interpret Music of Output_property type, and apply a function to any Graphic objects that satisfies the predicate.

Output_property_engraver is part of contexts: Voice, StaffGroup, InnerStaffGroup, RhythmicStaff, TabVoice, Thread, Staff, Score, ChordNames and TabStaff

Axis_group_engraver

Group all objects created in this context in a VerticalAxisGroup spanner.

Properties (read)

extraVerticalExtent (pair of numbers):

extra vertical extent, same format as MinimumVerticalExtent

minimumVerticalExtent (pair of numbers):

minimum vertical extent, same format as VerticalExtent

verticalExtent (pair of numbers):

hard coded vertical extent. The format is a pair of dimensions, for example, this sets the sizes of a staff to 10 (5+5) staffspaces high.

          property Staff.verticalExtent = #(-5.0 . 5.0)
          

VerticalExtent, MinimumVerticalExtent and ExtraVerticalExtent are predefined in all relevant contexts to #f, so they will not inherit values.

Note that these VerticalExtents can only operate on vertical groups, and therefore only work in contexts which contain an Axis_group_engraver.

Axis_group_engraver is part of contexts: LyricsVoice, RhythmicStaff, NoteNames, FiguredBass, Staff, StaffContainer, ChordNames, Lyrics and TabStaff

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.